UUID v4 vs v7: which one belongs in your database?

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.