UUIDv7, a popular ID generation standard, is often promoted as providing monotonically increasing IDs with embedded timestamps and unguessable values. However, according to analysis of RFC 9562-compliant implementations, none of these properties are strictly guaranteed.
The timestamp embedded in UUIDv7 IDs may not reflect actual object creation time. RFC 9562 explicitly allows implementations to alter the timestamp field, and the Postgres documentation warns that “the extracted timestamp is not necessarily exactly equal to the time the UUID was generated.” The specification permits implementations to increment timestamps ahead of the system clock, particularly when handling high creation rates. This can cause the embedded timestamp to diverge arbitrarily from actual time.
Python’s standard library uuid.uuid7() demonstrates this problem acutely. When a system clock jumps backward, the generator can enter an increment cycle where the embedded timestamp races ahead of system time without bound. In testing, after setting a clock back one hour, the delta between the UUID timestamp and actual time grew from 3,695 seconds to nearly 4,000 seconds as the system generated IDs at high rates.
Regarding monotonicity, UUIDv7 IDs provide only “rough order” rather than strict ordering. The RFC describes creating monotonically ordered IDs across nodes—a problem proven impossible in the 1970s due to clock synchronization limitations. Even on a single node, implementations using millisecond timestamps without counters trivially generate out-of-order IDs in tight loops. Specific implementations with sub-millisecond timestamps and counters may perform better, but the specification itself provides no strict monotonicity guarantee.
Timestamp leakage also presents a concern in some contexts. Embedding timestamps means sharing a UUIDv7 ID also reveals high-precision creation time, potentially leaking metadata through URLs or other publicly visible identifiers.
Additionally, most UUIDv7 implementations fail to write the last-used timestamp to persistent storage, causing out-of-order IDs when process restarts follow clock jumps. The only property UUIDv7 strictly provides is uniqueness and collision resistance. Developers should reconsider assumptions about ordering, timestamp accuracy, and security when adopting UUIDv7, though roughly ordered IDs remain useful for many applications.
Key facts
- RFC 9562 allows implementations to alter UUIDv7 timestamps, which may not match actual object creation time
- Python’s uuid.uuid7() can have embedded timestamps that race arbitrarily ahead of system time when clocks jump backward
- UUIDv7 provides only rough ordering, not strict monotonicity, despite RFC claims
- Most UUIDv7 implementations don’t persist the last-used timestamp, causing out-of-order IDs after process restarts following clock jumps
- The only strictly guaranteed UUIDv7 property is uniqueness and collision resistance