Deep Dive into UUID Versions: When to Use v1, v4, or v7

Universally Unique Identifiers (UUIDs) are 128-bit numbers used to uniquely identify information in computer systems. Because they can be generated independently without a central registry, they are the backbone of distributed systems, microservices, and modern database architectures.

However, "generate a UUID" is no longer a simple instruction. The IETF RFC 4122 standard (and its recent updates) defines multiple versions of UUIDs, each utilizing entirely different generation algorithms. Choosing the wrong version can lead to severe database performance degradation or privacy leaks. Let's break down the mechanics of UUID v1, v4, and the revolutionary v7.

Before diving into versions, we must understand the structure. A standard UUID is represented as 32 hexadecimal characters, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters.

Example: 123e4567-e89b-12d3-a456-426614174000

Buried within those hex characters are specific bits that indicate the UUID's version (how it was generated) and variant (the layout of the UUID). If you look closely at the first character of the third group in the example above (1), it tells you this is a Version 1 UUID.

UUID Version 1 was designed in an era where network cards were the ultimate source of uniqueness. A v1 UUID is generated using a combination of the computer's MAC address and a 60-bit timestamp (representing the number of 100-nanosecond intervals since midnight, October 15, 1582).

The Pros and Cons of v1

• Pros: Guaranteed uniqueness across a network, since no two machines have the same MAC address.
• Cons: Severe privacy implications. If you publish a v1 UUID, anyone can extract the exact MAC address of the machine that generated it, along with the precise time it was generated. Because of this, UUID v1 is largely deprecated in modern public-facing applications.

When developers ask for a UUID today, they almost always mean Version 4. A v4 UUID throws away timestamps and MAC addresses entirely in favor of pure randomness.

Of the 128 bits, 6 bits are reserved for version and variant information, leaving 122 bits of randomly generated data. This results in 2^122 possible UUIDs (roughly 5.3 undecillion). To put this in perspective: you would need to generate 1 billion UUIDs per second for 85 years to reach a 50% chance of a single collision.

When to use v4

UUID v4 is perfect for session IDs, API tokens, idempotency keys, and any scenario where the ID should not reveal any underlying information about the system or time of creation.

Despite its popularity, UUID v4 has a fatal flaw when used as a Primary Key in relational databases (like PostgreSQL or MySQL). Because v4 UUIDs are completely random, they are not sortable. When a database inserts a new v4 UUID into an indexed B-Tree, it must write the data to random locations on the disk.

As the table grows to millions of rows, this randomness causes severe index fragmentation and page thrashing. The database has to constantly rebalance the index tree, and inserts become exponentially slower. This is known as the "UUID Primary Key Performance Cliff."

To solve the database fragmentation problem, the IETF drafted a new standard: UUID Version 7. UUID v7 combines the best aspects of v1 and v4.

The first 48 bits of a v7 UUID consist of a Unix timestamp in milliseconds. The remaining 74 bits are cryptographically random. Because the timestamp sits at the very beginning of the string, v7 UUIDs are time-ordered (lexicographically sortable).

Why v7 is a Game Changer

When you insert UUID v7 records into a database, the sequential timestamps ensure that new records are appended to the end of the B-Tree index rather than scattered randomly throughout it. This eliminates index fragmentation, resulting in insert performance that rivals traditional auto-incrementing integers, while maintaining the distributed generation benefits of a UUID.

Here is the modern rule of thumb for developers:

• Use UUID v7 for database Primary Keys, sorting, or anything that benefits from time-based locality.
• Use UUID v4 for access tokens, session IDs, or scenarios where time-based predictability is a security risk.
• Avoid UUID v1 unless maintaining legacy systems.

Karuvigal provides dedicated generators for v1, v4, and v7 UUIDs, allowing you to instantly generate batches of identifiers tailored exactly to your architectural requirements.