Generator ULID

Czym jest ULID?

ULID (Universally Unique Lexicographically Sortable Identifier) to 128-bitowy format identyfikatora zaprojektowany tak, aby być zarówno unikalnym, jak i naturalnie sortowalnym. W odróżnieniu od UUID v4, który jest całkowicie losowy, ULID osadza uniksowy znacznik czasu z dokładnością do milisekundy w swoich wysokich bitach — zapewniając, że identyfikatory generowane później sortują się po identyfikatorach generowanych wcześniej.

ULID-y są kodowane przy użyciu alfabetu Crockford's Base32, produkując kompaktowy 26-znakowy ciąg bezpieczny dla URL, bez rozróżniania wielkości liter i wolny od wizualnie niejednoznacznych znaków.

Specyfikacja ULID została stworzona przez Alizaina Feerastę i jest szeroko stosowana w systemach rozproszonych, event sourcingu i kluczach głównych baz danych, gdzie liczy się zarówno unikalność, jak i porządek czasowy. ULID-y nie są standardem IETF — są specyfikacją społecznościową dostępną na ulid.github.io.

Struktura ULID

ULID ma 128 bitów szerokości, podzielonych na dwa komponenty:

Kodowany jako 26 znaków Crockford Base32: pierwsze 10 znaków reprezentuje znacznik czasu, ostatnie 16 znaków reprezentuje komponent losowy.

Alfabet Crockford Base32

ULID-y używają kodowania Crockford's Base32, które korzysta z 32 ze 36 znaków alfanumerycznych. Alfabet to: 0123456789ABCDEFGHJKMNPQRSTVWXYZ

Crockford Base32 jest bardziej wydajny niż szesnastkowy (32 symbole vs 16) i bardziej czytelny dla człowieka niż Base64 (bez znaków + / =, bez rozróżniania wielkości liter).

ULID a UUID

ULID-y i UUID-y reprezentują 128-bitowe identyfikatory, ale znacznie różnią się kodowaniem i celami projektowymi:

Jeśli jesteś już w ekosystemie UUID (kolumny uuid PostgreSQL, REST API, ORM z obsługą UUID), UUID v7 jest zazwyczaj lepszym wyborem niż ULID. Jeśli wolisz bardziej przyjazne dla człowieka kodowanie i kontrolujesz cały stos, ULID jest doskonałym wyborem.

ULID a nanoid

Zarówno ULID, jak i nanoid produkują krótkie, bezpieczne dla URL identyfikatory, ale mają różne cele projektowe:

Wybierz ULID, gdy potrzebujesz porządku czasowego. Wybierz nanoid, gdy potrzebujesz maksymalnej entropii w krótkim, losowym ciągu.

Używanie ULID w bazach danych

ULID-y można przechowywać w bazach danych na kilka sposobów w zależności od wymagań:

Przykłady kodu

Generowanie ULID wymaga biblioteki ulid (dostępnej dla JavaScript, Python, Go, Rust i innych):

// Using the 'ulid' npm package
import { ulid } from 'ulid'

const id = ulid()          // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
const id2 = ulid()         // "01ARZ3NDEKXXXXXXXXXXXX..." (same ms, incremented random)

// With a custom timestamp
const id3 = ulid(1469918176385) // deterministic time portion

// Extract the timestamp back out
import { decodeTime } from 'ulid'
decodeTime(id)  // → 1469918176385 (Unix ms)

# Using python-ulid
from ulid import ULID

uid = ULID()
str(uid)                    # "01ARZ3NDEKTSV4RRFFQ69G5FAV"
uid.timestamp               # 1469918176.385
uid.datetime                # datetime(2016, 7, 30, 23, 36, 16, 385000, tzinfo=timezone.utc)

# Parse an existing ULID string
parsed = ULID.from_str("01ARZ3NDEKTSV4RRFFQ69G5FAV")
parsed.timestamp            # 1469918176.385

-- Store ULIDs as TEXT or CHAR(26)
CREATE TABLE events (
  id   CHAR(26) PRIMARY KEY DEFAULT gen_ulid(),  -- if using a PG extension
  name TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Or pass the ULID from your application layer
INSERT INTO events (id, name, created_at)
VALUES ('01ARZ3NDEKTSV4RRFFQ69G5FAV', 'user.signup', NOW());

-- Range queries are efficient because ULIDs sort chronologically
SELECT * FROM events
WHERE id > '01ARZ3NDEKTSV4RRFFQ69G5FAV'
ORDER BY id
LIMIT 20;

// Pure browser / Deno / Node.js implementation (no dependencies)
const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'

function encodeTime(ms) {
  let result = '', n = BigInt(ms)
  for (let i = 9; i >= 0; i--) {
    result = CROCKFORD[Number(n & 31n)] + result
    n >>= 5n
  }
  return result
}

function encodeRandom(bytes) {
  let n = 0n
  for (const b of bytes) n = (n << 8n) | BigInt(b)
  let result = ''
  for (let i = 15; i >= 0; i--) {
    result = CROCKFORD[Number(n & 31n)] + result
    n >>= 5n
  }
  return result
}

function generateULID() {
  const randomBytes = new Uint8Array(10)
  crypto.getRandomValues(randomBytes)
  return encodeTime(Date.now()) + encodeRandom(randomBytes)
}

Często zadawane pytania