What UUIDv7 Sorting Tells You Across Processes

Published November 9, 2026

UUIDv7 keys generated close together tend to land near each other in a database index. Sorting by those keys can still put two writes from different workers in the wrong order, even on the same machine.

What the four-worker benchmark found

REPTILE.HAUS ran four processes on one Linux host and compared adjacent IDs in a stream ordered by a separately recorded clock. For four Python implementations using the final RFC layout, 49.84% to 50.01% of adjacent pairs from different workers had the later ID sort first. The same implementations showed zero inversions between adjacent IDs from the same worker. REPTILE.HAUS benchmark

The first 48 bits of UUIDv7 encode Unix milliseconds. When two IDs have the same timestamp, their remaining bits decide the sort order. A counter can preserve order within one generator, while independent workers can start at different counter values or use different random bits. Those IDs still occupy the same timestamp range in the index. RFC 9562, section 5.7

A frozen clock exposed a counter overflow

In a separate test, the benchmark held the clock at one millisecond and exercised @kripod/uuidv7 version 0.3.4. Its 12-bit counter filled all 4,096 slots. The next call returned a 37-character string after the counter grew beyond its allotted three hexadecimal digits. The benchmark also observed malformed output after moving the clock backward. Benchmark overflow results

Store event time separately and test the generator at its limits

Keep an explicit timestamp for the event you mean to order, such as record creation or ingestion. Timestamps can tie or disagree across machines. If the application needs a strict order, record an authoritative sequence at the point that defines it.

For bulk generation, hold the clock steady long enough to exhaust the counter, simulate a backward jump, and run concurrent workers. Check the format, version, variant, and uniqueness of every successful ID. Check ordering against the scope the generator actually promises, and verify that exhaustion yields a valid ID or an explicit failure. RFC 9562, section 6.2

Inspect the embedded millisecond with the UUID decoder, or compare the index tradeoffs in the v4 vs v7 guide.