How to Choose the Right UUID Type for Your Needs
When designing software architectures, developers often reach for a UUID (Universally Unique Identifier) without fully understanding the underlying mechanics. Choosing the wrong UUID version can lead to severe database fragmentation, security vulnerabilities, or privacy leaks.
In this guide, we will break down exactly how to choose the right UUID type for your specific engineering requirements. We will cover the differences between versions, analyze the mathematical mechanics, and discuss when you should transition away from legacy standards.
TL;DR: The Quick Recommendation
If you are inserting rows into a relational database, use UUIDv7. If you are generating a random API key or temporary session token, use UUIDv4. If you need reproducible IDs based on input strings, use UUIDv5.
1. Understanding the UUID Landscape
A UUID is a 128-bit label used for information in computer systems. Standardized by the IETF in RFC 4122 (and recently updated in RFC 9562), UUIDs have evolved significantly over the last three decades to address changing computing needs.
If you're still relying on default generators, you might be wondering what UUID package you should use. Native implementations like Node.js crypto.randomUUID() exist, but they predominantly generate version 4 identifiers. To make an informed choice, you must understand what each version actually does under the hood.
2. UUID v4: The Random Standard
UUID version 4 is currently the most widely deployed UUID format on the internet. Unlike older versions, UUIDv4 is almost entirely reliant on pseudorandom number generators (PRNGs).
How UUID v4 Works
A UUIDv4 consists of 122 bits of randomly generated data, with the remaining 6 bits reserved for version and variant metadata. Because it depends on random entropy, it offers no contextual information about when or where the UUID was generated.
When to use UUID v4:
- Generating stateless session identifiers.
- Creating one-time access tokens or password reset links.
- Situations where predictability is a security risk.
While UUIDv4 is excellent for randomness, it is terrible for database performance. The total lack of sequential order means that inserting UUIDv4 strings into a B-Tree index causes massive page splits and fragmentation. If you are debating UUID vs integer primary keys, the primary argument against UUIDs stems entirely from the chaotic nature of version 4.
3. UUID v7: The Modern Database Solution
To solve the database fragmentation issues caused by UUIDv4, the IETF recently standardized UUIDv7. This is arguably the most important update to the UUID specification in decades.
How UUID v7 Works
UUIDv7 combines a 48-bit Unix timestamp (millisecond precision) with 74 bits of cryptographic randomness. This guarantees that UUIDs generated around the same time will sort sequentially, while maintaining enough randomness to prevent collisions.
// Conceptual structure of UUIDv7
const timestamp = getCurrentTimeMillis(); // 48 bits
const randomData = getSecureRandomBits(); // 74 bits
const uuid = constructUUIDv7(timestamp, randomData);
When to use UUID v7:
- As a primary key in PostgreSQL, MySQL, or SQL Server.
- When you need to naturally sort records by creation time without a separate timestamp column.
- For high-volume distributed systems where database write performance is critical.
If you have noticed that your database inserts are slowing down as your tables grow, you should investigate upgrading to v7. You can refer to our dedicated guide on how to generate UUIDs in your application for specific implementation patterns across different languages.
4. UUID v5: The Deterministic Hasher
Sometimes, you do not want a randomly generated ID. You want an ID that is mathematically guaranteed to be the same if the input data is the same. This is where Name-Based UUIDs come into play.
UUIDv5 uses SHA-1 hashing to combine a predefined "namespace" UUID with a custom string (the "name"). Because hashing is deterministic, processing the same namespace and string will always yield the exact same UUIDv5.
When to use UUID v5:
- Deduplicating data ingestion streams.
- Generating primary keys from external system identifiers (e.g., mapping a Stripe customer ID to your internal database UUID).
- Creating consistent object references in distributed microservices without network calls.
5. UUID v1: The Legacy Standard to Avoid
UUID version 1 is a time-based format that predates the modern web. It combines a 60-bit timestamp (measured in 100-nanosecond intervals since October 15, 1582) with the MAC address of the computer generating the UUID.
While UUIDv1 is sequential and fast, embedding the physical MAC address of the server into the identifier creates severe privacy and security vulnerabilities. Malicious actors can extract the MAC address to identify specific hardware or predict future UUIDs. For this reason, UUIDv1 should be completely avoided in modern software architecture unless you are supporting legacy systems.
6. Frequently Asked Questions
What is the best UUID version for database primary keys?
For modern database primary keys, UUID v7 is considered the best choice. It combines a time-based prefix with random data, resulting in sequential identifiers that prevent database index fragmentation while maintaining security.
Should I use UUID v4 or v7?
You should use UUID v4 when you need completely random identifiers for stateless tokens or session IDs. You should choose UUID v7 when inserting records into a database, as the time-ordered nature significantly improves write performance.
Is it safe to use UUID v1?
It is generally not safe to use UUID v1 in public-facing applications because it embeds the MAC address of the host machine. This exposes underlying hardware details and can lead to severe privacy or security vulnerabilities.
How does UUID v5 differ from other versions?
Unlike versions 1, 4, or 7 which generate unique IDs every time, UUID v5 uses deterministic SHA-1 hashing. If you input the same namespace and name into a UUID v5 generator, it will always output the exact same UUID.
7. Conclusion
Learning how to choose the right UUID type is a critical skill for backend engineers. The default approach for many years has been to blindly implement UUIDv4, but the standardization of UUIDv7 has shifted the landscape entirely. By auditing your database performance and security requirements, you can select the identifier that ensures scalability and safety for your applications.