How to Generate UUID v7: Complete Guide 2026

Why Use UUID v7?

UUID v7 is the modern solution to a long-standing problem in distributed systems: how to generate unique identifiers that are also friendly to database indexes. Traditional UUID v4 generates completely random 128-bit values that are distributed uniformly across the entire key space. While this guarantees uniqueness without coordination, it creates severe performance problems for B-tree indexes because new rows are inserted at random positions, causing frequent page splits and index fragmentation.

UUID v7 solves this by embedding a timestamp in the most significant bits of the identifier. This means UUIDs generated sequentially are also sorted sequentially, allowing database indexes to append new entries at the end of the index rather than inserting them at random positions. The result is write performance comparable to auto-increment integers with the distributed uniqueness benefits of UUIDs. This makes UUID v7 the preferred choice for primary keys in modern distributed database architectures.

The GoToolly UUID v7 Generator implements RFC 9562, the official standard published in May 2024. It combines a 48-bit Unix timestamp in milliseconds with 74 bits of randomness, ensuring both time-ordering and uniqueness across systems. The timestamp portion provides milliseconds of precision, and the random portion makes collisions astronomically unlikely even when generating many UUIDs within the same millisecond.

• Database Primary Keys: Time-ordered UUIDs eliminate random I/O and index fragmentation in B-tree indexes.
• Distributed Systems: Generate globally unique identifiers without a central coordinator.
• Event Sourcing: The embedded timestamp provides natural ordering of events and records.
• Logging and Tracing: Correlate distributed system events with sortable unique identifiers.

UUID v4 vs. UUID v7: Key Differences

Choosing between UUID v4 and UUID v7 depends on your specific requirements. Here is a detailed comparison of the two formats:

UUID v4

UUID v4 is the most widely used UUID version. It generates 122 bits of random data plus 6 fixed variant and version bits, producing a 128-bit identifier. UUID v4 is fully random: there is no relationship between the value of the identifier and when it was generated. This makes UUID v4 suitable for scenarios where you do not want identifiers to leak timing information, such as API tokens, session identifiers, or user-facing IDs where predictability must be minimized.

The main drawback of UUID v4 is its impact on database performance. When used as a primary key in a B-tree index, random inserts cause approximately 30-50% more index maintenance overhead compared to sequential keys. For small tables this is negligible, but for large tables with millions of rows, the performance penalty is significant.

UUID v7

UUID v7 embeds a 48-bit millisecond-precision Unix timestamp as the most significant bits. The remaining 74 bits are random. Because the timestamp occupies the high-order bits, UUID v7 values are naturally sorted in chronological order. This provides the key advantage of UUID v7 for database primary keys: new rows are appended to the right side of the index, minimizing page splits and index fragmentation.

UUID v7 still provides excellent uniqueness characteristics. The 74 random bits provide approximately 36 bits of uniqueness per millisecond, which is more than sufficient for any practical generation rate. The trade-off is that the timestamp leaks the approximate creation time of the identifier, which may be undesirable for security-sensitive applications. For primary keys and most database applications, this is not a concern.

Step-by-Step: Generate UUID v7 with GoToolly

Best Practices for UUID v7

• Use as Primary Keys: UUID v7 is ideal for primary keys in distributed databases, especially when using MySQL, PostgreSQL, or CockroachDB. The time-ordered nature dramatically reduces index fragmentation compared to UUID v4.
• Consider Clock Synchronization: UUID v7 relies on the system clock for its timestamp. If your system clock jumps backward (e.g., after NTP correction), the monotonicity guarantee may be temporarily violated. For mission-critical systems, implement monotonicity fallbacks.
• Store Efficiently: Store UUID v7 as BINARY(16) or UUID-native types in your database rather than as VARCHAR(36). This reduces storage from 36 bytes to 16 bytes and improves index performance.
• Avoid for Security Tokens: Because UUID v7 leaks the generation timestamp, avoid using it for session tokens, password reset links, or security-sensitive identifiers where temporal information should not be exposed.
• Combine with Bulk Generation: When seeding a database with historical data, generate UUIDs in chronological batch order to maintain realistic time-ordering in your test data.

Limitations and Considerations

While UUID v7 solves many problems, it is not the right choice for every scenario. The most significant limitation is that UUID v7 reveals the timestamp of creation. For applications where this constitutes a security concern, UUID v4 remains the better choice. Additionally, UUID v7 generation depends on an accurate system clock. If the system clock is incorrect, the generated UUIDs will carry incorrect timestamps, though uniqueness is still maintained.

Not all databases and ORMs have native support for UUID v7 yet. While the format is specified in RFC 9562, some tools may require custom handling or type mapping. Check your database and ORM documentation before migrating to UUID v7. For example, PostgreSQL has native UUID support but does not distinguish between UUID versions at the storage level, so UUID v7 values can be stored in standard UUID columns without issues.

The GoToolly generator produces standard RFC 9562 UUID v7 values. If you need UUID v6, v8, or other experimental formats, you will need a specialized tool. UUID v7 represents the consensus standard for time-ordered UUIDs and is expected to be the dominant format going forward.

Frequently Asked Questions