UUID Generator v7: Time-Ordered Identifiers Explained

The layout

The first 48 bits are a Unix timestamp in milliseconds. Then 4 version bits, 12 random bits, 2 variant bits, and 62 more random bits — 74 random bits in total.

0191a2b3-c4d5-7abc-8def-0123456789ab
\______________/ ^    ^
 48-bit ms time  |    variant (8, 9, a or b)
                 version 7

Because the timestamp comes first and is big-endian, sorting the UUIDs as strings or as bytes sorts them by creation time.

Why index locality matters

A v4 primary key lands at a random position in the B-tree on every insert. Pages split constantly, and the parts of the index being written are spread across the whole structure — so the working set does not fit in memory and write throughput falls as the table grows.

v7 inserts land at the right edge, like an auto-increment key. You keep client-side generation and lose the write penalty, which is why frameworks and databases adopted it quickly.

Generating one

uuid.uuid7()                              # Python 3.14+ (uuid6 package before)
Uuid::uuid7()                             // PHP, ramsey/uuid 4.7+
Generators.timeBasedEpochGenerator()      // Java, java-uuid-generator
Guid.CreateVersion7()                     // .NET 9+
uuidv7()                                  // JS, uuid npm v10+
SELECT uuidv7();                          -- PostgreSQL 18+

Reuse the generator object where the library has one — a fresh instance per call gives up the counter that keeps ordering stable inside a single millisecond.

What to watch for

The timestamp is readable by anyone holding the identifier. Creation time, record age and the interval between two records all leak, which can be commercially meaningful — signup rate, for instance.

Clock changes matter: a backwards NTP adjustment can produce out-of-order values. Good implementations guard against it; a hand-rolled one usually does not.

Where identifiers are public and creation time should stay private, keep v7 internally and expose something opaque.