UUID v7 Generator — Sortable Time-Ordered UUID

A UUID v7 is 128 bits divided into three main sections. The first 48 bits (12 hex characters) contain a Unix timestamp in milliseconds — the number of milliseconds since January 1, 1970 UTC. Because these bits are at the most significant end of the UUID, lexicographic sorting of UUID v7 strings produces chronological ordering. A UUID generated later is always lexicographically greater than one generated earlier (within the same millisecond, additional random bits maintain ordering via a monotonically increasing counter). The next 4 bits are the version field set to 7. The following 12 bits (plus 2 variant bits) form a sub-millisecond sequence counter, and the remaining 62 bits are random. This structure gives millisecond-level time resolution with strong uniqueness guarantees from the random suffix.

A critical property of UUID v7 for database use is monotonic ordering within a single process. When multiple UUID v7 values are generated within the same millisecond, a counter in the sub-millisecond bits ensures they remain in increasing order. This means that a batch of UUID v7 values generated in rapid succession will still be globally ordered, not just ordered within the same millisecond boundary. RFC 9562 specifies a "Method 3" approach where 12 random bits are replaced by a 12-bit counter that increments with each generation within the same millisecond. This ensures that even at very high generation rates, UUID v7 values remain monotonically increasing within a single process, which is the property that delivers the database performance benefits.

Most databases use B-tree indexes for primary keys. B-trees maintain sorted order, which means every insert must find the correct sorted position. With random UUID v4 primary keys, each new record is inserted at a random position in the index — statistically distributed across the entire tree. This causes frequent page splits (when a B-tree page is full and must be divided), poor write locality (each insert likely touches a different disk page), and high index fragmentation over time. In PostgreSQL, this manifests as bloated tables and indexes requiring frequent VACUUM operations. In MySQL/InnoDB, random UUIDs cause the clustered primary key index to become highly fragmented, significantly degrading range scan and insert performance.

UUID v7 is one of several sortable ID formats designed to solve the random UUID problem. ULID (Universally Unique Lexicographically Sortable Identifier) uses a 48-bit millisecond timestamp and 80 random bits, encoded in base32 (26 characters). CUID2 uses a 32-character base36 encoded identifier with a timestamp prefix. UUID v7 has the advantage of being a proper UUID format (8-4-4-4-12 hex), making it compatible with any system that accepts UUIDs including databases with native UUID columns. PostgreSQL 17 includes built-in support for generating UUID v7. If your stack already handles UUIDs (UUID columns in your database, UUID types in your ORM), UUID v7 is the upgrade path with zero format changes required — just swap the generation function.