CUID Generator

Was ist CUID?

CUID (Collision-Resistant Unique Identifier) ist ein Open-Source-Algorithmus zur Generierung eindeutiger IDs, die in verteilten Systemen ohne einen zentralen Koordinator gut funktionieren. Im Gegensatz zu einem einfachen UUID ist ein CUID so konzipiert, dass er horizontal skalierbar ist — mehrere Server oder Browser-Tabs können jeweils unabhängig IDs generieren, mit minimalem Kollisionsrisiko.

Jede CUID beginnt mit dem Kleinbuchstaben c, wodurch das Format auf den ersten Blick sofort erkennbar ist. Die verbleibenden Zeichen sind alle alphanumerische Kleinbuchstaben (base36), sodass eine CUID URL-sicher ist und direkt als URL-Pfadsegment oder Datenbankprimärschlüssel ohne zusätzliche Kodierung verwendet werden kann.

Die ursprüngliche CUID-Spezifikation (v1) wurde von Eric Elliott erstellt und über das npm-Paket cuid verbreitet. Sie wird nun von CUID v2 abgelöst, das kryptografische Sicherheit bietet. Diese Seite — und der obige Generator — erzeugt CUID v1-IDs, das klassische Format, das noch weit verbreitet in Produktions-Codebasen vorkommt.

CUID-Struktur

Eine CUID v1 ist etwa 25 Zeichen lang und besteht aus fünf verketteten Segmenten, die jeweils einen anderen Entropietyp tragen:

Die Segmente werden einfach verkettet — es gibt keine Trennzeichen. Die Gesamtlänge variiert leicht je nach aktuellem Zeitstempelwert, bleibt aber bei ungefähr 25 Zeichen.

Wie CUID Kollisionen Verhindert

Kollisionsresistenz entsteht durch das Überlagern unabhängiger Entropiequellen, sodass selbst in Worst-Case-Szenarien (Tausende von IDs pro Millisekunde über viele Maschinen) die Wahrscheinlichkeit zweier identischer IDs verschwindend gering bleibt.

CUID vs UUID v4

Sowohl CUID als auch UUID v4 werden häufig für die clientseitige ID-Generierung verwendet. Sie verfolgen unterschiedliche Ansätze für dasselbe Problem:

UUID v4 ist die sicherere Wahl für sicherheitssensible Szenarien, da es keine Zeitinformationen preisgibt. CUID hat den Vorteil, wenn Sie IDs wollen, die ungefähr sortierbar, kürzer und ohne Bindestriche sind — praktisch für die Verwendung in URLs, Dateinamen oder Logs, wo Sie schnell erkennen wollen, wann ein Datensatz erstellt wurde.

CUID v1 vs CUID2

Die CUID-Spezifikation wurde erheblich überarbeitet. Das Verständnis der Unterschiede hilft Ihnen, die richtige Version für Ihr Projekt zu wählen:

Für neue Projekte ist CUID v2 die empfohlene Wahl. Die SHA-3-basierte Konstruktion bedeutet, dass die Ausgabe opak ist — kein Zeitstempel, Zähler oder Fingerabdruck kann aus der ID rückentwickelt werden. Verwenden Sie CUID v1 nur, wenn Sie Abwärtskompatibilität mit einem vorhandenen Datensatz benötigen oder eine abhängigkeitsfreie Implementierung wünschen.

Anwendungsfälle

Code-Beispiele

Installieren Sie das offizielle CUID v2-Paket (empfohlen) oder schreiben Sie eine minimale v1-Implementierung ohne Abhängigkeiten:

// npm install @paralleldrive/cuid2  (recommended — CUID v2)
import { createId } from '@paralleldrive/cuid2'

const id = createId()
// → 'tz4a98xxat96iws9zmbrgj3a'

// Custom length
import { init } from '@paralleldrive/cuid2'
const createShortId = init({ length: 10 })
createShortId() // → 'zxp1l6mf4c'

Wenn Sie eine abhängigkeitsfreie Node.js-Implementierung des v1-Algorithmus bevorzugen:

// Pure Node.js — CUID v1 style (no dependencies)
let counter = 0

function pad(str, size) {
  return str.padStart(size, '0').slice(-size)
}

function fingerprint() {
  const os = require('os')
  const source = [process.pid, os.hostname().length].join('')
  let hash = 0
  for (const c of source) {
    hash = ((hash << 5) - hash) + c.charCodeAt(0)
    hash |= 0
  }
  return pad(Math.abs(hash).toString(36), 4)
}

function cuid() {
  const timestamp = Date.now().toString(36)
  const cnt       = pad((counter++ & 0xffff).toString(36), 4)
  const fp        = fingerprint()
  const rnd       = pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
              + pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
  return 'c' + timestamp + cnt + fp + rnd
}

console.log(cuid()) // → 'clrc4gkwz001ag2hs3k7f9m2q'

Verwendung von CUID als Datenbankprimärschlüssel mit Prisma und PostgreSQL:

-- Use CUID as a primary key in PostgreSQL
CREATE TABLE users (
  id   TEXT        PRIMARY KEY DEFAULT gen_cuid(),
  name TEXT        NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Prisma schema (auto-generates CUID by default)
model User {
  id        String   @id @default(cuid())
  name      String
  createdAt DateTime @default(now())
}

Häufig gestellte Fragen