UUIDv7: Timestamps Aren’t Time-ordered And Other Oddities

TL;DR

Before you orderOffer from Amazon

Get the latest gadgets delivered free with Prime

• Fast, free delivery on millions of items
• Prime Video, Amazon Music and more included
• Member-only deals all year

Start your free Prime trial →Free trial for eligible customers · Cancel anytime

As an affiliate, we earn on qualifying purchases.Hide

A report on UUIDv7 says its embedded timestamp is not guaranteed to match the time an ID was generated, and that chronological ordering is not strict. It points to clock adjustments and generator behavior as reasons applications should not treat UUIDv7 as a precise creation-time record.

A technical report on UUIDv7 says its embedded timestamps are not guaranteed to reflect when an object was created, and that the IDs do not provide strict chronological ordering. The analysis points to rules in RFC 9562 and a clock-adjustment scenario in Python’s standard-library generator, warning developers not to treat UUIDv7 as a precise substitute for a creation-time field.

UUIDv7 combines a timestamp-based field with other bits used to distinguish identifiers. That design can make IDs roughly sortable and may help database workloads that frequently retrieve records in an order resembling creation time. But the report, published by Built on Shards of Silicon, says neither timestamp accuracy nor strict monotonic ordering is guaranteed by the specification.

The report cites RFC 9562, which allows implementations to alter the timestamp field and does not require the encoded clock value to stay close to actual time. The specification also permits generators to increment timestamps ahead of the system clock in some circumstances. PostgreSQL’s documentation for uuid_extract_timestamp likewise cautions that the extracted time is not necessarily exactly when the UUID was generated.

The author describes a case involving Python’s uuid.uuid7(): after the system clock is moved backward, the generator may keep advancing its embedded timestamp to avoid moving backward itself. Under sustained generation above one ID per millisecond, the report’s example shows that the difference from the system clock can continue to grow. The author says similar behavior can occur in other implementations, but the supplied report does not establish that every UUIDv7 generator behaves this way.

Why Timestamp Drift Matters

Applications that use a UUIDv7 value as if it were an authoritative creation-time record may store misleading timestamps or produce unexpected sort order. A database index on UUIDs can still be useful for approximate ordering, but it should not replace a separate time field when exact event time, auditability, or reliable chronological queries matter.

The report also notes a privacy trade-off: sharing a UUIDv7 can reveal an associated timestamp, even if the surrounding page does not display when an account or record was created. The author characterizes this as a limited concern in many security reviews, while noting that the exposed metadata could matter in particular settings.

These limits do not mean UUIDv7 is unusable. The report says its dependable practical property is uniqueness and collision resistance, while its time-related behavior is approximate and depends on implementation and operating conditions. Teams need to match the identifier’s guarantees to the requirements of their systems.

How UUIDv7 Handles Time

UUIDv7 is part of the UUID family and is designed to place timestamp information near the start of the identifier, making values broadly sortable. That arrangement can support index locality and convenient ordering without a separate index in some workloads. Those are potential benefits, not a guarantee that sorting UUIDs will reproduce the exact sequence of real-world events.

RFC 9562 describes options for generators to preserve ordering when multiple IDs are created in a short interval, including counters and timestamp adjustments. The report says the RFC recommends a counter of at least 12 bits; a counter of that size would overflow only at a rate above 4,096 IDs per millisecond per node if used in the described way. The author adds that clock freezes can make counter behavior relevant even when ordinary generation rates are lower.

The report’s Python example is a specific implementation scenario, not a claim that all UUIDv7 libraries share identical code or outcomes. Its wider point is that the standard allows implementation choices, so developers should check the behavior of the generator they actually use rather than assume every UUIDv7 timestamp has the same relationship to wall-clock time.

“This specification makes no requirement or guarantee about how close the clock value needs to be to the actual time.”

— RFC 9562, Section 6.1, as quoted in the report

Limits Across UUID Implementations

The report does not provide a survey of all UUIDv7 libraries, nor does it quantify how often clock jumps or timestamp drift occur in deployed systems. Its Python demonstration depends on a particular clock change and sustained ID-generation pattern; the source does not establish that the same runaway behavior occurs under all workloads or in every implementation.

It is also not clear from the supplied material whether Python’s generator behavior will change, or whether other maintainers plan adjustments. The report says developers involved in a related issue viewed the behavior as consistent with the RFC and difficult to avoid on a flawed system, while the author argues implementations could handle backward clock changes better.

Checks for UUIDv7 Users

Developers should check the documentation and implementation details for the UUIDv7 generator used in their applications, particularly how it responds to clock rollback, clock freezes, and high generation rates. Systems that require dependable event times should retain a separate timestamp recorded for that purpose and define how their application handles clock errors.

The report does not identify a scheduled standards change or a confirmed software fix. Any future action depends on implementation maintainers and application teams deciding whether to adjust generator behavior or change how they use UUIDv7 values. Until then, the practical next step is to treat UUIDv7 ordering as approximate and avoid exposing IDs where their timestamp metadata would be sensitive.

Key Questions

Does a UUIDv7 timestamp show exactly when the ID was generated?

No guarantee. RFC 9562 allows implementations to alter the timestamp, and PostgreSQL’s documentation warns that an extracted timestamp may not exactly match generation time.

Are UUIDv7 values strictly ordered by creation time?

No. UUIDv7 can provide a rough ordering, but clock differences, generator strategies, and other implementation details mean it should not be treated as a strict record of event sequence.

What does the report say can happen in Python’s UUIDv7 generator?

The report describes a clock rollback scenario in which the generator’s timestamp can move ahead of system time. Under sustained generation above one ID per millisecond, its example shows the gap growing; the report does not claim every implementation behaves identically.

Can a UUIDv7 reveal information about an account?

It can expose timestamp metadata associated with the ID. The report gives a profile URL as an example where the identifier might reveal account timing information that the page itself does not show.

Should UUIDv7 replace a separate creation-time column?

Not when exact, auditable creation times are required. The report says UUIDv7 can be useful for approximate ordering, but applications with precise time requirements should store a separate timestamp.

Source: hn