2026-09-09 · 8 min read
- uuid
- identifiers
- distributed-systems
UUIDv7 combines a 48-bit Unix-millisecond timestamp with version, variant, and random or implementation-defined monotonic fields. Its high-order timestamp generally improves insertion locality and rough time sorting while preserving globally useful identifier semantics.
It is not a centralized sequence. Values produced in the same millisecond or on different clocks may not sort by the business event order, database commit order, or user-visible chronology.
Choose UUIDv7 for the right property
Use UUIDv7 when decentralized creation and time-oriented locality are valuable. Keep a separate sequence, event timestamp, or cursor when the application requires gap-free numbers, strict causality, trusted time, or a total order.
- Treat identifiers as opaque at API boundaries.
- Do not expose creation time accidentally when that metadata is sensitive.
- Use an explicit secondary sort key for stable pagination.
- Keep authorization independent from identifier unpredictability.
Standardize generation and rollback policy
Adopt maintained RFC 9562 implementations and document how each generator handles bursts within one millisecond, clock rollback, process restarts, and exhaustion of any monotonic state. Conforming libraries can make different valid choices.
Client-generated UUIDs are untrusted input. Validate syntax and accepted versions if the contract requires them, but do not trust the embedded timestamp for audit, retention, or authorization decisions.
Preserve canonical storage order
Store UUIDs in a native UUID type when the database provides compatible semantics, or in a documented 16-byte or canonical lowercase text representation. Verify that drivers and legacy optimized-UUID functions do not reorder byte groups.
- Round-trip through every language and database driver.
- Compare as unsigned canonical 128-bit values.
- Index according to measured query patterns.
- Plan coexistence with UUIDv4 and other legacy versions.
Test clocks, bursts, and pagination
Use Flashman's UUID generator for disposable values, timestamp converter for millisecond interpretation, number-base converter for field inspection, diff for representation changes, and hash tool to label public fixture sets.
Test equal-millisecond bursts, backward and forward clock changes, multiple hosts, process restarts, binary and text storage, driver upgrades, lexical sorting, compound cursors, mixed versions, malformed variants, duplicate handling, and data exports.