A UUID is a 128-bit identifier you can generate anywhere without coordination. That property makes it attractive as a primary key, and v4 — the familiar random one — quietly makes your database slower in a way that only shows up at scale.
Why random keys hurt
Database indexes are ordered structures. Sequential keys append to the end, touching the same pages repeatedly, which stay cached. Random keys land in arbitrary positions, so each insert may touch a different page and the working set becomes the entire index.
On a small table this is invisible. On a large one it shows up as steadily degrading insert performance and a cache that no longer helps, because there is no locality left to exploit.
What v7 changes
UUIDv7 puts a 48-bit millisecond timestamp in the leading bits and fills the rest with randomness. The result is still a UUID — same length, same format, still generated without coordination — but values created around the same time sort near each other.
That restores the locality sequential keys had, while keeping the ability to generate identifiers on any machine. For most new tables it is simply the better default.
When v4 is still right
v7 encodes creation time to the millisecond, and anyone holding the identifier can read it. If the identifier is public — in a URL, an API response, a filename — that may leak more than you want: when an account was created, or how quickly records are being added.
For public-facing identifiers where that matters, v4 remains the right choice. A reasonable pattern is v7 internally as the primary key and a separate v4 exposed externally.
In short
Use v7 for database keys and v4 for anything public. Both are collision-safe in practice; the difference is index locality against information leakage.
UUID Generator
Generate random v4 or time-ordered v7 UUIDs in bulk, in whichever format your system expects.
Keep reading
Why your link preview isn't showing, and how to fix it
A shared link with no card is nearly always one of five things. How previews are fetched, which tags matter, and why Slack works when WhatsApp won't.
How to read a regular expression without panicking
Regex looks like line noise until you know the four things it is made of. A practical guide to reading any pattern, plus the mistakes that waste the most time.
How to read messy JSON, and fix the errors it throws
Deeply nested API responses are hard to hold in your head. How to navigate JSON structurally, and what the three most common parse errors actually mean.