uuidv7 generator

UUID v7 is a time-sortable unique identifier defined by IETF RFC 9562, the standard that modernizes the original UUID specification from RFC 4122. It was designed as the recommended evolution of UUID v4 for applications that need both global uniqueness and chronological ordering. UUID v7 embeds a 48-bit millisecond-precision Unix timestamp in the most significant bits of the 128-bit value, followed by version and variant markers, with the remaining space filled by cryptographically secure random data. The result is an identifier that fits the familiar 8-4-4-4-12 hexadecimal format of traditional UUIDs while naturally sorting in the order it was created. This makes UUID v7 a true drop-in replacement for UUID v4 in any system that already accepts UUIDs, with the substantial bonus of sequential ordering that benefits database performance, event streaming, and distributed tracing.

UUID v7 was developed in response to a growing recognition that purely random UUIDs, while excellent for uniqueness, cause significant performance problems in database systems. Random identifiers scatter inserts across B-tree index pages, leading to write amplification, cache inefficiency, and fragmented storage. Formats like ULID and KSUID had already demonstrated the value of time-prefixed identifiers, but they required custom storage types and lacked formal standardization. The IETF working group behind RFC 9562 incorporated these lessons into UUID v7, giving the industry a standardized, time-sortable UUID that works with existing infrastructure without modification.

How UUID v7 Works

A UUID v7 value occupies 128 bits, the same size as every other UUID version. The bit layout is carefully structured to maximize timestamp precision while maintaining compatibility with the UUID format.

The first 48 bits contain a Unix timestamp measured in milliseconds since January 1, 1970, 00:00:00 UTC. This 48-bit allocation provides a range of approximately 281 trillion milliseconds, which translates to coverage until the year 10889. Because these timestamp bits occupy the most significant positions, UUID v7 values generated at different times are guaranteed to sort in chronological order when compared as raw bytes, strings, or integer representations. This chronological sorting is the core property that distinguishes UUID v7 from UUID v4.

Bits 48 through 51 contain the version nibble, which is set to 0111 (decimal 7) to identify the UUID as version 7. This is the same position used by all UUID versions, so existing parsers can detect the version by reading the 13th hexadecimal character of the string representation, which will always be 7 for UUID v7.

Bits 52 through 63 provide 12 bits of sub-millisecond precision or additional randomness, depending on the implementation. RFC 9562 allows these bits to be used as fractional millisecond data for microsecond-level ordering or as random values. Most implementations choose randomness for simplicity, but those needing tighter monotonic ordering within a millisecond can use the fractional approach.

Bits 64 and 65 contain the variant field, set to 10 to indicate the RFC 4122/9562 variant. This leaves bits 66 through 127 as 62 bits of cryptographically random data, generated using a CSPRNG. Combined with the 12 optional random bits in the sub-millisecond section, a UUID v7 typically contains 74 bits of randomness per millisecond, yielding approximately 1.9 x 10^22 unique values per millisecond. This makes within-millisecond collisions extraordinarily unlikely even at the highest generation rates.

The resulting 128-bit value is formatted as a standard UUID string with hyphens: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx, where 7 is the version nibble and y is one of 8, 9, a, or b (indicating the variant). This format is accepted by every UUID column type in PostgreSQL, MySQL, SQL Server, and other databases without schema changes.

Some implementations add a monotonic counter that increments within the same millisecond, ensuring that IDs generated in rapid succession on the same machine are strictly ordered. This optional behavior is permitted by the RFC and is recommended for applications where insertion order must match generation order.

Use Cases

Relational database primary keys. UUID v7 is the ideal primary key format for relational databases in distributed systems. The time-sorted property ensures that new rows are appended to the end of B-tree indexes rather than scattered randomly across pages. This reduces page splits, write amplification, and index fragmentation compared to UUID v4. PostgreSQL, MySQL, and CockroachDB all benefit from sequential inserts, and UUID v7 delivers this without requiring auto-incrementing sequences. Existing UUID columns accept UUID v7 values without schema migration.

Event sourcing and audit logs. Applications that record immutable sequences of events need identifiers that preserve creation order. UUID v7 provides this naturally: events stored with UUID v7 identifiers can be queried in chronological order using a simple ORDER BY on the ID column, eliminating the need for a separate timestamp column or composite index. The embedded timestamp also allows approximate time extraction directly from the identifier, which is useful for partition pruning and time-range queries.

Distributed tracing and correlation. In microservice architectures, trace IDs and correlation IDs propagate across service boundaries to link related operations together. UUID v7 is well-suited for this role because its time-sorted property makes it easy to reconstruct the chronological flow of a request across services. Log aggregation systems can sort trace spans by their UUID v7 correlation ID to display a timeline without parsing separate timestamp fields.

Message queue ordering. Message brokers like Apache Kafka and Amazon SQS often need message IDs that reflect production order. UUID v7 ensures that messages produced later have higher-sorting identifiers, simplifying consumer-side ordering logic and deduplication.

Comparison with Alternatives

The most direct predecessor is UUID version 4, which fills 122 bits with pure randomness. UUID v4 is well-suited for applications that have no need for time-based ordering, such as generating API tokens or identifiers where creation-time privacy is important. The disadvantage of UUID v4 in database contexts is that random values cause index fragmentation and degrade write performance at scale. UUID v7 solves this while retaining the same format, size, and compatibility. For new projects that use UUIDs as primary keys, UUID v7 is the recommended default.

ULID shares the same fundamental design as UUID v7: a millisecond timestamp in the leading bits followed by randomness. The output format differs, however. ULID uses Crockford's Base32 encoding to produce a 26-character string, while UUID v7 uses the standard 36-character hexadecimal representation with hyphens. ULID's shorter output is an advantage for URL slugs and human-readable contexts, but UUID v7 benefits from native database support, IETF standardization, and universal library availability. In practice, teams already invested in UUID infrastructure should choose UUID v7, while teams starting from scratch in JavaScript-heavy environments may prefer ULID for its compactness.

TSID (Time-Sorted ID) packs a millisecond timestamp and randomness into a 64-bit integer, producing a compact 13-character Crockford Base32 string. The 64-bit size makes TSID extremely efficient for storage and indexing, fitting natively into a BIGINT database column. However, the reduced bit space limits the amount of randomness available per millisecond, which can become a concern at very high generation rates in large distributed systems. UUID v7's 128-bit size provides a much larger random space and broader interoperability at the cost of a longer string representation. For systems where storage efficiency is critical and generation rates are moderate, TSID is an excellent choice. For systems where standardization and maximum collision resistance matter, UUID v7 is preferable.