What is a UUID Version 7?
UUID Version 7 is a time-ordered identifier format introduced in RFC 9562 (published May 2024). It addresses a long-standing limitation of UUID v4 — the lack of natural ordering — by embedding a 48-bit Unix timestamp (millisecond precision) in the most significant bits, followed by random data in the remaining bits.
How UUID v7 is Generated
- Capture the current Unix timestamp — The current time is recorded as milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
- Fill the random payload — The remaining 74 bits are filled with cryptographically secure random data using
crypto.getRandomValues(). - Set the version nibble — Bits 48–51 are set to
0111(decimal 7). - Set the variant bits — Bits 64–65 are set to
10, indicating RFC 9562 compliance.
UUID v7 Byte Structure
| Field | Bits | Content |
|---|---|---|
| unix_ts_ms | 0–47 | 48-bit Unix timestamp in milliseconds |
| ver | 48–51 | 0111 (version 7) |
| rand_a | 52–63 | 12 random bits |
| var | 64–65 | 10 (RFC 9562 variant) |
| rand_b | 66–127 | 62 random bits |
Why UUID v7 is Better for Databases
UUID v4's random distribution causes B-tree page splits on every insert. UUID v7's sequential nature means inserts always go to the end of the index — the same pattern as auto-incrementing integers. Benchmarks consistently show 2–10x write throughput improvement on large tables.
UUID v7 vs v1
| Aspect | Version 1 | Version 7 |
|---|---|---|
| Timestamp epoch | Gregorian (1582-10-15) | Unix (1970-01-01) |
| Timestamp precision | 100 nanoseconds | 1 millisecond |
| Byte ordering | Non-sequential (time_low first) | Sequential (MSB first) |
| String sortable | No | Yes |
| Node field | MAC address or random | Random only |
| Specification | RFC 4122 (2005) / RFC 9562 | RFC 9562 (2024) |
When to Use UUID v7
- Database primary keys — Sequential ordering minimizes index fragmentation and maximizes write throughput.
- Event logs and time-series data — Natural chronological ordering simplifies queries and partitioning.
- Distributed systems requiring ordered IDs — Multiple nodes can generate locally-ordered IDs without coordination.
- Replacing ULID or custom Snowflake IDs — UUID v7 provides the same ordering benefits within the standard UUID format.
Frequently Asked Questions
What is a UUID Version 7?
UUID Version 7 is a time-ordered UUID format that combines a 48-bit Unix timestamp (millisecond precision) with 74 bits of random data. It was introduced in RFC 9562 as a modern alternative to UUID v1.
Why is UUID v7 better for databases than v4?
UUID v7's time-ordered structure means new IDs are always greater than previous ones, resulting in sequential B-tree index inserts. UUID v4's random values cause scattered inserts that degrade write performance by 2–10x on large tables.
Can I extract the timestamp from a UUID v7?
Yes. The first 48 bits (12 hex characters) of a UUID v7 contain a Unix timestamp in milliseconds. To extract it, parse the hex value and convert it with new Date(parseInt(uuid.slice(0,8) + uuid.slice(9,13), 16)).
Should I migrate from UUID v4 to v7?
Consider migrating if you use UUIDs as database primary keys and experience write performance issues from index fragmentation. Existing v4 UUIDs can coexist with new v7 UUIDs in the same column.