2026-10-14 · 6 min read · Rahul Chitturi
- uuid
- databases
- identifiers
A version 7 UUID is not a random blob with a clock glued on the side. RFC 9562 puts a 48-bit Unix timestamp, in milliseconds, in the most significant bits, then a version nibble of 7, then random bits. Sorted as bytes, or as the canonical hyphenated string, newer ids tend to land after older ones.
Version 4 ids do not have that property. If a table used to be filled with randomUUID() values and a new writer emits version 7, an ORDER BY on the text column changes meaning. The bug report says the sort is wrong. The ids are doing what their version says.
Read the version before you read the clock
In the canonical form, strip the hyphens and look at the first character of the third group. That character is the version. 4 means the rest is random. 7 means the first twelve hex digits are a big-endian millisecond timestamp. Mixed versions in one column are a migration, not a single format.
Convert those twelve hex digits to a decimal millisecond instant and compare it with the row's created_at. A version 7 id whose timestamp is hours away from the application clock was minted by another clock, or the id was copied from an old fixture and relabeled.
- Reject a non-canonical string before you parse the timestamp.
- Compare the version nibble across writers.
- Keep version 4 samples next to version 7 samples in the ticket.
- Do not treat the id as a secret. The timestamp is visible.
Do not expect a total order inside one millisecond
Two nodes that mint a version 7 id in the same millisecond are distinguished by the random bits, not by a cluster-wide sequence. Byte order between those two ids is not creation order. A clock that steps backward can also insert a new id before an older one.
If the product needs a gapless sequence, use a database sequence or a dedicated counter. Use version 7 when you want index locality and a rough creation time. Use version 4 when the id must not reveal when it was created.
Check the column type that actually sorts
A native uuid column sorts the 16 bytes. A text column sorts the canonical string, which still follows time for version 7 because the timestamp is the prefix. A column that stores unhyphenated ids next to hyphenated ids does not. Diff the stored form before you change the index.
Flashman's UUID tool generates version 4 fixtures with the platform random UUID. Use the timestamp converter on the twelve hex digits of a version 7 id, diff to compare a version 4 sample with the production id, and the JSON formatter when the id is buried in an API payload.