Why UUID v7 Replaces UUID v4 for Database Primary Keys
Standardized in IETF RFC 9562, UUID Version 7 (UUIDv7) solves the biggest database performance bottleneck of random UUIDv4 keys: B-Tree index fragmentation and random page splits. By embedding a 48-bit big-endian Unix Epoch millisecond timestamp in the most significant bits, every newly generated UUIDv7 sorts monotonically in chronological order.
When inserting rows into PostgreSQL, MySQL (InnoDB clustered indexes), SQLite, or distributed KV stores like CockroachDB and TiDB, UUIDv7 appends new index entries sequentially at the right edge of the B-Tree—matching the write locality and buffer-pool cache efficiency of BIGINT AUTO_INCREMENT while keeping 128-bit global uniqueness.
- 48-Bit Unix Millisecond Prefix (Bits 0–47): Encodes milliseconds since 1970-01-01T00:00:00Z in big-endian hex, enabling natural lexicographical and binary sorting.
- Version & Variant Nibbles: Bits 48–51 are fixed to 0111 (hex digit 7) and bits 64–65 are fixed to RFC 9562 variant 10 (hex 8, 9, a, or b).
- 74 Bits of CSPRNG Entropy (rand_a + rand_b): Guarantees collision resistance across distributed nodes generating millions of IDs within the same millisecond.
RFC 9562 Bit Layout: UUIDv7 vs UUIDv4 vs ULID
Unlike ULID (which requires non-standard 26-character Crockford Base32 encoding and custom database column types), UUIDv7 uses the canonical 36-character 8-4-4-4-12 hexadecimal wire format supported natively by PostgreSQL uuid columns, MySQL BINARY(16), and every OpenAPI/JSON Schema validator.
Because the 48-bit Unix millisecond timestamp occupies the first 12 hexadecimal digits, database query planners can also leverage index range scans and BRIN block indexes directly on the primary key without maintaining a redundant created_at B-Tree index.
- PostgreSQL 17+ & Native uuid Type: Stores UUIDv7 in 16 bytes with zero casting overhead and supports range scans on creation time without a separate indexed created_at column.
- 100% Client-Side Web Crypto Generation: Every UUIDv7 batch is generated locally in your browser using window.crypto.getRandomValues() with zero network requests.
Practical Real-World Use Cases
Engineering teams adopt UUIDv7 wherever globally unique keys must be minted by stateless application nodes without sacrificing relational index locality:
- High-Throughput Order & Ledger Tables in PostgreSQL / InnoDB: Generate primary keys on API edge servers before INSERT so multi-region microservices avoid sequence round-trips while keeping B-Tree leaf pages sequentially packed.
- Event-Sourced Audit Logs & Kafka Message Keys: Assign monotonic UUIDv7 IDs to domain events and outbox rows so consumers can sort, paginate with keyset cursors (WHERE id > $last_id), and partition streams chronologically.
- Seed Data & Integration Test Fixtures: Mint deterministic-looking batches of 10 to 100 chronological UUIDv7 identifiers for SQL migration seeds, Prisma/Drizzle fixtures, and OpenAPI mock payloads.
Frequently Asked Questions
What is UUID v7 (RFC 9562) and how is it structured?
UUID v7 is a 128-bit time-ordered identifier standardized in IETF RFC 9562. Its first 48 bits store a Unix Epoch timestamp in milliseconds, followed by a 4-bit version marker (0111 = 7), 12 bits of sub-millisecond/random data (rand_a), a 2-bit variant (10), and 62 bits of cryptographically secure random data (rand_b).
Why is UUID v7 better than UUID v4 for PostgreSQL and MySQL primary keys?
UUID v4 is completely random, forcing database B-Tree indexes to insert keys into random disk pages and causing severe buffer-pool thrashing and index bloat. UUID v7 starts with a monotonically increasing timestamp, so new rows append sequentially at the end of the B-Tree index—delivering up to 3× faster insert throughput.
Can you extract the creation timestamp from a UUID v7 string?
Yes. Remove the first hyphen from the first 13 characters of a UUID v7 (the first 12 hex digits = 48 bits), parse that hexadecimal integer in base 16, and pass the resulting millisecond value to new Date(ms) to recover the exact UTC creation timestamp.