UUID v4 vs v7: Which Should You Use?
Published
Choosing a UUID version affects how your identifiers behave long after you generate them. Start with three questions: do you need time ordering, can you expose a timestamp, and what do your existing systems accept?
The difference in one table
| Property | UUID v4 | UUID v7 |
|---|---|---|
| Structure | Random data plus version and variant | Timestamp first, then random or monotonic fields |
| Embedded time | None | Unix milliseconds in the first 48 bits |
| Index locality | Inserts scattered across the key range | Nearby timestamps produce nearby keys |
These layouts and their ordering properties are defined in RFC 9562. Sorting v7 values does not establish a global event order: clocks can differ, and ordering within a millisecond depends on the generator.
When v4 is a good fit
Keep v4 when it already meets your needs, or when you want an identifier without an embedded creation timestamp. A system with modest write volume may have little reason to change an established identifier contract just to optimize key order.
In browsers, crypto.randomUUID() generates v4 using a cryptographically secure random source and requires a secure context. See the Web Crypto documentation and our JavaScript UUID guide. Switching this call to v7 requires a different generator.
When to evaluate v7
Consider v7 for new database records when insertion locality matters. Benchmark it with your actual indexes, row sizes, concurrent writers, and read queries before promising a performance improvement. A useful trial compares insertion latency and index size at a realistic data volume.
PostgreSQL's native uuid type can store UUIDs of any version, so storing v7 does not require turning the column into text. Generation support is a separate question. Consult the PostgreSQL UUID type documentation and our PostgreSQL guide for version-specific generation options.
A migration checklist
- Check API validators, database constraints, SDKs, and consumers for rules that only accept v4.
- Decide whether exposing an approximate creation time is acceptable for every place the ID appears.
- Keep a separate creation or event timestamp with clearly defined semantics; an identifier should not silently become your audit trail.
- Plan how mixed versions will be sorted. Existing v4 records will not acquire chronological order when new records start using v7.
- Preserve existing IDs and references. Changing the version digit of a v4 UUID does not convert it into a meaningful v7 value.
Compare a few values
Generate samples with the v4 generator and v7 generator, then inspect them in the UUID decoder. Before putting either version in a public API, read about UUIDs and access control.
Browse all UUID articles →