Generator UUID v7

Czym jest UUID v7?

UUID v7 to format UUID nowej generacji standaryzowany w RFC 9562 (maj 2024). Koduje 48-bitowy uniksowy znacznik czasu w milisekundach w bitach o największym znaczeniu, a następnie znaczniki wersji i wariantu, a pozostałe bity wypełnia kryptograficznie bezpiecznymi losowymi danymi.

Ponieważ znacznik czasu zajmuje wysokie bity, wartości UUID v7 sortują się chronologicznie — zarówno leksykograficznie, jak i numerycznie. Dzięki temu doskonale nadają się do kluczy głównych bazy danych, gdzie losowe UUID (v4) powodują fragmentację indeksu B-tree.

Dlaczego losowe UUID fragmentują indeksy bazy danych

Indeksy B-tree — używane przez PostgreSQL, MySQL, SQLite i większość innych baz danych — przechowują wiersze posortowane według wartości klucza. Podczas wstawiania nowego wiersza baza danych musi umieścić go na właściwej posortowanej pozycji w indeksie.

W przypadku UUID v4 (w pełni losowego) każde nowe wstawianie trafia do zasadniczo losowej pozycji w drzewie indeksów. Zmusza to bazę danych do ciągłego odczytywania i przepisywania wewnętrznych stron indeksu, dzielenia pełnych stron i pozostawiania innych do połowy pustych. Wynikiem jest pofragmentowany, nadmiernie rozrośnięty indeks, który spowalnia zarówno zapisy, jak i odczyty w miarę wzrostu tabeli.

Układ bitów UUID v7

UUID v7 ma 128 bitów szerokości, podzielonych na sześć pól:

Precyzja znacznika czasu wynosi 1 milisekundę. W obrębie tej samej milisekundy wartości UUID v7 są uporządkowane według losowego sufiksu — nie ma gwarancji monotonicznego wzrostu poniżej milisekundy, ale są k-sortowalne: identyfikatory generowane blisko siebie w czasie będą sortowały się blisko siebie w indeksie.

UUID v7 a UUID v1

Zarówno UUID v1, jak i UUID v7 zawierają znacznik czasu, ale znacznie różnią się projektem:

W przypadku każdego nowego projektu wymagającego UUID posortowanych według czasu, preferuj UUID v7 nad UUID v1. UUID v1 jest przestarzały i ujawnia informacje o hoście.

UUID v7 a ULID

ULID (Universally Unique Lexicographically Sortable Identifier) rozwiązuje podobny problem co UUID v7. Oto porównanie:

Jeśli jesteś już w ekosystemie UUID (kolumna uuid PostgreSQL, REST API zwracające UUID), użyj UUID v7. Jeśli zaczynasz od nowa i wolisz bardziej przyjazne dla człowieka kodowanie, ULID jest rozsądną alternatywą.

Używanie UUID v7 w bazach danych

UUID v7 nie jest jeszcze natywnie generowany przez większość baz danych, ale może być przechowywany w standardowych kolumnach UUID i generowany w kodzie aplikacji lub przez rozszerzenia:

Przykłady kodu

UUID v7 nie jest jeszcze dostępny przez crypto.randomUUID(). Używaj biblioteki takiej jak uuidv7 (npm) do czasu pojawienia się natywnej obsługi:

function generateUuidV7() {
  const buf = new Uint8Array(16)
  crypto.getRandomValues(buf)

  const ms = BigInt(Date.now())

  // Embed 48-bit Unix ms timestamp
  buf[0] = Number((ms >> 40n) & 0xFFn)
  buf[1] = Number((ms >> 32n) & 0xFFn)
  buf[2] = Number((ms >> 24n) & 0xFFn)
  buf[3] = Number((ms >> 16n) & 0xFFn)
  buf[4] = Number((ms >> 8n)  & 0xFFn)
  buf[5] = Number(ms & 0xFFn)

  // Set version 7 (0111xxxx)
  buf[6] = (buf[6] & 0x0F) | 0x70

  // Set variant (10xxxxxx)
  buf[8] = (buf[8] & 0x3F) | 0x80

  const hex = [...buf].map(b => b.toString(16).padStart(2, '0')).join('')
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}`
}

// Node.js 20+ built-in
// import { randomUUID } from 'node:crypto'  // v4 only — no v7 yet in stdlib

# pip install uuid7
import uuid_extensions

uid = uuid_extensions.uuid7()
print(uid)                       # e.g. 018e2b3d-1a2b-7000-8000-abc123456789
print(uid.time)                  # Unix ms timestamp embedded in the UUID

# Or as a plain string
from uuid_extensions import uuid7str
print(uuid7str())

-- PostgreSQL 13+ extension-free implementation
CREATE OR REPLACE FUNCTION uuid_generate_v7()
RETURNS uuid
LANGUAGE sql
AS $$
  SELECT encode(
    set_bit(
      set_bit(
        overlay(
          uuid_send(gen_random_uuid())
          PLACING substring(int8send(floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint) FROM 3)
          FROM 1 FOR 6
        ),
        52, 1
      ),
      53, 1
    ),
    'hex'
  )::uuid;
$$;

-- Usage as a default primary key
CREATE TABLE events (
  id uuid PRIMARY KEY DEFAULT uuid_generate_v7(),
  payload jsonb,
  created_at timestamptz DEFAULT now()
);

function extractTimestamp(uuid: string): Date {
  const hex = uuid.replace(/-/g, '')
  const ms = parseInt(hex.slice(0, 12), 16)  // first 48 bits = ms timestamp
  return new Date(ms)
}

const uid = '018e2b3d-1a2b-7000-8000-abc123456789'
console.log(extractTimestamp(uid).toISOString())
// → "2024-03-15T10:22:05.259Z"

Często zadawane pytania