What is a UUID?
A UUID (Universally Unique Identifier, also called a GUID) is a
128-bit identifier formatted as 32 hexadecimal digits with hyphens:
xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx. The
M nibble identifies the version and
N identifies the variant. UUIDs are
designed to be collision-free across machines without a central
coordinator, which makes them ideal for distributed systems.
UUID v4 vs UUID v7 — which one should I use?
- UUID v4 — 122 bits of randomness. Maximum entropy, zero ordering. Great for opaque ids; bad for database primary keys because random inserts trash B-tree locality.
- UUID v7 — first 48 bits encode a Unix millisecond timestamp, followed by 74 random bits. Sortable by creation time. The right default for new database primary keys: you get UUID-style global uniqueness with sequential insert performance. Defined in RFC 9562.
Common use cases
- Primary keys in distributed databases.
- Request and trace IDs that need to be unique across services.
- File or upload IDs you don't want to look enumerable.
- Idempotency keys for API write operations.
Where does the randomness come from?
UUID v4 uses crypto.randomUUID() where
available, falling back to crypto.getRandomValues().
UUID v7 uses the same cryptographically strong random source for its
74-bit random tail and Date.now() for the
48-bit timestamp prefix. No server is contacted — generation is
entirely local.