UUID versions: random, time-ordered and name-based

What it is

RFC 9562 (obsoleting RFC 4122) specifies the 128-bit UUID layout and versions. Version 4 is 122 random bits. Version 7 places a Unix millisecond timestamp in the most significant bits followed by random bits, so values sort by creation time. Version 5 hashes a namespace and a name with SHA-1 into a stable identifier. Versions 1 and 6 encode a timestamp with a node identifier.

Why it matters

Random keys spread inserts across a B-tree index, which is fine for small tables but causes page splits and poor locality at scale; time-ordered keys keep recent rows together. Deterministic keys let two systems agree on an identifier without coordination (this wiki derives idempotency keys that way in its examples).

How to apply

• Default to version 4 for identifiers that must be unguessable and need no ordering.
• Prefer version 7 for primary keys of large, append-heavy tables and for keyset pagination by creation time.
• Use version 5 when the same input must always map to the same id (imports, deduplication).
• Store as the database's native UUID type, not as text.

Pitfalls

Version 7 leaks creation time; do not use it where that is sensitive. Version 5 with a guessable name is guessable. Sorting version 4 keys has no meaning; do not paginate by them alone.

What it is

RFC 9562 (obsoleting RFC 4122) specifies the 128-bit UUID layout and versions. Version 4 is 122 random bits. Version 7 places a Unix millisecond timestamp in the most significant bits followed by random bits, so values sort by creation time. Version 5 hashes a namespace and a name with SHA-1 into a stable identifier. Versions 1 and 6 encode a timestamp with a node identifier.

Why it matters

Random keys spread inserts across a B-tree index, which is fine for small tables but causes page splits and poor locality at scale; time-ordered keys keep recent rows together. Deterministic keys let two systems agree on an identifier without coordination (this wiki derives idempotency keys that way in its examples).

How to apply

• Default to version 4 for identifiers that must be unguessable and need no ordering.
• Prefer version 7 for primary keys of large, append-heavy tables and for keyset pagination by creation time.
• Use version 5 when the same input must always map to the same id (imports, deduplication).
• Store as the database's native UUID type, not as text.

Pitfalls

Version 7 leaks creation time; do not use it where that is sensitive. Version 5 with a guessable name is guessable. Sorting version 4 keys has no meaning; do not paginate by them alone.

Trade-off: time-ordered identifiers reveal creation time

Version 7 identifiers embed a millisecond timestamp, so anyone who sees the ID learns roughly when the record was created; in sequences they reveal creation rates. For public identifiers of sensitive resources (orders, users, medical records), either use version 4 or expose a separate random public identifier while keeping v7 as the internal key.