When timestamps aren’t time-ordered and other oddities
\n\n\n2026-10-19
\nI’m going to call it. UUIDv7 is weird.
\nMost blog posts about UUIDv7 tout these benefits:
\nBut none of these properties are strictly held.\nCertain RFC compliant implementations of UUIDv7 violate these properties to extreme degrees.\nThe only useful property UUIDv7 appears to strictly provide is uniqueness and therefore collision resistance.\nI’ve already discussed how\nUUIDv7 IDs can be guessable,\nso this post explores the other properties.
\nSuperficially, it seems that embedding a timestamp in the ID can remove the need to track the creation time in a separate database column, providing marginally more efficient database operations.\nIf you need to list things ordered by creation time very often, it’s useful if the primary index gives that behavior, removing the need for another index.
\nUnfortunately, the timestamp embedded in a UUIDv7 ID may not relate to the object creation time.\nThe Postgres docs for uuid_extract_timestamp\nhelpfully warn that “the extracted timestamp is not necessarily exactly equal to the time the UUID was generated”.
RFC 9562\nallows implementations to alter the timestamp field, using values that aren’t strictly derived from the system clock.\nThis relates to the tension between UUID monotonicity and timestamp accuracy.\nIn certain scenarios, the difference between the timestamp and the current time can be arbitrarily large.
\n\nImplementations MAY alter the actual timestamp. — RFC 9562 §6.1
\nThis specification makes no requirement or guarantee about how close the clock value needs to be to the actual time. — RFC 9562 §6.1
\n… implementations MAY increment the timestamp ahead of the actual time … — RFC 9562 §6.2
Incrementing the timestamp ahead of the system clock is an interesting problem.\nIf the generator is seeing so much load that a counter field is regularly overflowing then the timestamp could accelerate into the future.\nUsing a sufficiently large counter would be wise and the RFC says the minimum size SHOULD be 12 bits.\nA counter overflow would require a pretty aggressive creation rate, over 4,096 IDs per millisecond per node, which is beyond the limits of many systems.\nThis overflow becomes relevant, however, if the timestamp freezes; which I’ll discuss in a later section.
\nOne prominent implementation that increments the timestamp is the Python standard library’s UUIDv7.\nThe increment happens only in certain circumstances, like when the counter overflows.\nUnfortunately, the generator can get stuck in an increment cycle if the clock ever jumps backwards and the timestamp can race ahead of the system time by an arbitrarily large amount.
\nHere’s a simple example:
\nimport uuid\nfrom datetime import datetime\n\n# Prime the generator with the current time\nt = uuid.uuid7().time\nnow = datetime.now()\ndelta = (datetime.fromtimestamp(t/1000) - now).total_seconds()\nprint("Initial delta: ", delta)\n# Ask the user to change the time\ninput("Set clock back one hour")\n\nwhile True:\n for _ in range(100000):\n uuid.uuid7()\n t = uuid.uuid7().time\n now = datetime.now()\n delta = (datetime.fromtimestamp(t/1000) - now).total_seconds()\n print("New delta: ", delta)Which gives:
\n$ uv run --python 3.14 main.py\nInitial delta: -0.000748\nSet clock back one hour\nNew delta: 3695.277581\nNew delta: 3795.042411\nNew delta: 3894.80756\nNew delta: 3994.573106\n^CWe expect the difference to be 3600 seconds (one hour) as the implementation refuses to allow the embedded timestamp to jump backwards and we expect the difference to decrease as the system clock catches up to the frozen timestamp.\nBut when the load is above one ID per millisecond the difference will increase without bound.\nAt lower loads it will take longer for the system clock to catch the timestamp, but we don’t see the runaway effect.
\nThe related issue\nshows Python developers reasoning that this is consistent with the RFC, is consistent with other implementations, and that there isn’t “much we can do” on a “flawed system”.\nI think these points are correct as I see this same behavior in other implementations.\nNevertheless, it would be helpful if existing UUIDv7 implementations could handle system clock jumps without runaway behavior.\nThere are many real-world examples of clocks jumping backwards,\neven decades out of sync in time-sensitive environments.
\nEmbedding the timestamp in the ID means that you cannot share the ID without also sharing the timestamp.
\nIt’s pretty difficult to think of an example where this really matters.\nOne example could be a user profile page that doesn’t disclose when the account was created, but the UUIDv7 ID in the URL leaks the high-precision timestamp.
\nThis issue would typically be very low on my list of security concerns because I find much more severe problems when I do security assessments.\nNevertheless, there are contexts where this matters and engineering resources would be focused on addressing it.\nIf you’re in the latter camp, be wary of UUIDv7 leaking metadata.
\nThis section is even more pedantic, so skip ahead if you’ve had enough.\nBriefly: UUIDv7 IDs provide some sort of rough order, which may be suitable for your requirements.
\nWhen I was reading the UUIDv7 RFC I was surprised to see it describing a method for creating IDs across different nodes that are monotonically ordered.\nThis was\nproven impossible back in the 1970s,\nand lead to the development of vector clocks and similar technology. At a high level, the problem is that system clocks cannot be synchronized to a suitable precision.\nOrdering things by timestamp only works if you know precisely what time it is.\nAny uncertainty in the time results in uncertainty of event ordering.
\nSuccinctly: Timestamps are only time-ordered if you know what time it is and you don’t know what time it is.
\nFor this reason, similar ID formats claim to be nearly sorted.\nIt seems odd that UUIDv7 makes a stricter claim and does not deliver on them.\nAt the very least, the\nchallenges of synchronizing clocks across systems\nmake the millisecond and especially the sub-millisecond timestamps quite suspect.
\nBut even on a single node, using a single implementation, UUIDv7 IDs are not strictly monotonic.\nThe easiest way to get out-of-order UUIDv7 IDs is to use an implementation that uses a millisecond timestamp without a counter.\nThis approach trivially generates out-of-order IDs inside a small for loop.
\nSo no, there’s nothing in the UUIDv7 specification that would ensure the IDs are strictly monotonically increasing.\nSpecific implementations may do better than others (with sub-millisecond timestamps, counters, well-synchronized clocks, etc), but we’ve known since the 1970s that this problem is not strictly solvable.
\nIn UUIDv7’s favor, roughly ordered IDs are still quite useful.\nSo don’t rip UUIDv7 out of your systems just yet.\nJust be wary of what assumptions you have.
\nThe RFC has lots of discussion about the handling of clocks that jump backwards.\nTimestamps are only time-ordered if clocks tick forwards, so special care is needed.
\nWe’ve already discussed one mitigation: tracking the last generated timestamp to ensure that an earlier timestamp is never used.\nTo do this safely you’ll need to write the last used timestamp to persistent storage, such that you can read it again after a system reboot or a process restart.
\nI’ve looked at several UUIDv7 implementations I couldn’t find one that writes timestamps to persistent storage.\nSo implementers seems disinterested in addressing the issue and they generate out-of-order IDs when a process restart follows a clock jumping backwards.
\nLooking at real-world clock synchronization problems, you’ll find many examples of\nclocks getting set to future dates.\nWhen this happens, the backwards jump would align the timestamp to the actual time, but a last-used-timestamp guard would force timestamps to use keep using that incorrect timestamp until the system clock catches up.\nIf the system clock takes a long time to catch up, you may start experiencing counter rollovers.
\nMy mental model for UUIDv7 is that it’s a mash-up of a bunch of different ideas which implementations are free to choose as they see fit.\nThere’s a wide variance of properties that UUIDv7 implementations can provide, with varying degrees of certainty they can successfully provide those properties.\nIf you’re building your own implementation you can likely build something that has the properties you need.\nBut most of us want to reach for an off-the-shelf version, especially when standard libraries provide an implementation, so we’re generally at the mercy of someone else’s implementation decisions.\nImplementations can change over time, making broad changes to their behavior while still being RFC compliant.\nDistributed systems may have multiple implementations across their subsystems, each with distinct properties.\nThe only thing you can really expect is strong collision avoidance and ID uniqueness.
\nBe sure to ask these questions when picking a UUIDv7 implementation:
\nUnfortunately, this sort of analysis is much more difficult than building an RFC compliant generator.\nAuthors of UUIDv7 generators may not know the answers to these questions and may themselves be surprised that the RFC does handle this for them.
","headings":[{"level":1,"text":"UUIDv7 doesn't have the properties you think it does","id":"uuidv7-doesn-t-have-the-properties-you-think-it-does"},{"level":2,"text":"Is the timestamp useful?","id":"is-the-timestamp-useful"},{"level":3,"text":"Example: Python uuid.uuid7()","id":"example-python-uuid-uuid7"},{"level":2,"text":"Is leaking a timestamp harmful?","id":"is-leaking-a-timestamp-harmful"},{"level":2,"text":"Are UUIDv7s monotonic?","id":"are-uuidv7s-monotonic"},{"level":2,"text":"Restarting a UUIDv7 generator","id":"restarting-a-uuidv7-generator"},{"level":2,"text":"So what is UUIDv7?","id":"so-what-is-uuidv7"}]}}