UUID v4 vs v7 — Sortable IDs in New Projects

Primary key inserts on UUID v4 looked random — because they were. Postgres index pages split constantly at 50M rows. Query plans scanning WHERE created_at > yesterday still hit random leaf pages because PK order ≠ time order.

UUID v7 doesn't replace v4 everywhere. It fixes a specific pain: time-correlated inserts with random UUID primary keys.

UUID v4 recap

• 122 random bits + version/variant bits
• No semantic meaning
• Excellent unpredictability for public tokens
• Poor insertion locality in B-trees

How UUIDs Work, UUID in API Development.

UUID v7 recap

• 48-bit Unix ms timestamp (top)
• Random bits fill remainder
• Roughly sortable by creation time
• Better index append patterns
• Leaks timing — trade privacy for performance

Standardized in RFC 9562 (2024).

Comparison table

| Aspect | v4 | v7 | | --- | --- | --- | | Sortable by time | No | Approximate yes | | Index locality | Poor | Better | | Guessability | Very low | Timestamp visible | | Library support | Universal | Growing | | Public exposure | Safer opaque | Consider exposure |

When to choose v7

• High-volume OLTP with UUID PK
• Range queries on ID as proxy for time
• Distributed generators without central sequence
• New greenfield Postgres/MySQL designs

When to stay v4

• Public session tokens in URLs
• Low volume apps — premature optimization
• Runtimes without v7 yet in prod
• Security requirement for non-guessable opaque IDs

Hybrid pattern: internal v7 PK, external opaque public_id v4 column.

Database notes

Postgres — uuid type; v7 benefits B-tree on id. Still use created_at for precise time — don't rely on v7 ms alone in distributed clocks.

MySQL — UUID as BINARY(16) stores efficiently; v7 hex sort ≈ time sort.

SQLite — less critical at small scale.

Collision and clock skew

v7 assumes reasonable clock sync. NTP skew across generators can produce out-of-order IDs rarely — acceptable for most apps; not for strict monotonic global ordering (use Snowflake IDs instead).

Generate test IDs in UUID Generator.

Migration from v4

Don't rewrite existing PKs. New tables v7; old tables v4. Mixed DB fine.

JSON APIs

IDs as strings "018f3e2a-..." — validate format — JSON Schema Validation.

Troubleshooting

What is the difference between UUID v4 and v7? UUID v4 is mostly random with 122 bits of randomness. UUID v7 encodes a Unix timestamp in the most significant bits with random bits below — making IDs roughly time-sortable while remaining globally unique without coordination.

Why use UUID v7 instead of v4? v7 improves B-tree index locality in databases — newer rows cluster near each other reducing page splits and improving range query performance on primary keys ordered by insertion time.

Is UUID v4 still fine for new projects? Yes for many apps where insert order indexing doesn't matter or volumes are moderate. v4 is universally supported everywhere v7 isn't yet. v7 is increasingly supported in Postgres 18+, libraries, and language runtimes.

Limitations

When not to use this approach

Conclusion

v7 for new high-volume time-ordered PKs; v4 for opaque public tokens and universal compatibility.

Timestamp leak is real — don't put v7 in customer-visible URLs if timing is sensitive. Index locality is real too — at 50M rows you'll notice.

ULID and Snowflake alternatives

UUID v7 not only sortable ID — ULID (Crockford base32) human-transcribable; Snowflake IDs need central worker ID allocation. Compare when v7 timestamp leak unacceptable but sortability needed.

Database index type

Postgres B-tree default; UUID PK works. Consider BRIN on created_at column separately if queries time-range heavy — v7 helps but dedicated timestamp column clearer for analytics.

Logging correlation

v7 IDs sortable in log grep approximate time window — useful debugging production without separate timestamp column in log line if ID logged.