UUID Generator

What a UUID is and what it guarantees

A UUID is an identifier you can generate without asking anyone. That is the whole proposition: no central counter, no coordination between servers, no round trip to the database to find out what the next id is. Two machines that have never met can mint ids all day and never collide, which is what makes UUIDs the default key for anything distributed, offline-capable or merged after the fact.

The guarantee is probabilistic rather than absolute. With 122 random bits there are about 5.3×10^36 possible version 4 UUIDs; you would need to generate roughly 2.7×10^18 of them before the chance of a single collision reached 50%. At a million ids a second that is about eighty-five thousand years. It is not impossible, it is just never the thing that breaks.

Version 4 or version 7

• Version 4: random the one almost everyone means by "a UUID". Pure randomness, no information about when or where it was made, and therefore nothing leaked by the id itself. The default choice for a public identifier.
• Version 7: time-ordered a millisecond timestamp first, randomness after. Standardised in RFC 9562 in 2024, and the better choice for a database primary key.
• Why ordering matters a B-tree index writes new rows wherever the key falls. Random keys scatter writes across the whole index and keep evicting cached pages; time-ordered keys append at the end. On a large table that difference shows up as insert throughput and index size.
• What v7 gives away its creation time, to anyone who can read it. That is usually fine for an internal key and a bad idea for something a stranger can enumerate.
• Versions 1, 3 and 5 v1 is time plus the machine’s MAC address, which leaks hardware identity; v3 and v5 are hashes of a name in a namespace, for deriving the same id from the same input. Not generated here, but read correctly by the inspector.

The practical details that bite

Storing a UUID as text is the most common avoidable mistake. As a 36-character string it costs 36 bytes and compares character by character; as 16 raw bytes, Postgres uuid, MySQL BINARY(16), it costs 16 and compares as two machine words. On a table with a few million rows and a couple of indexes, the difference is measured in gigabytes.

Case and braces are formatting, not identity. 123E4567-E89B-... and 123e4567-e89b-... are the same UUID, and so is the same value wrapped in braces the way Windows tooling writes it. Lowercase with hyphens is the canonical form in RFC 9562, so that is what to store; accept the rest on input and normalise.

And the nil UUID, all zeros, is valid, which surprises people. It is a legal UUID with version 0, and it is the value you get when an uninitialised field gets written out. If you see it in your data, something defaulted rather than generated.

When something looks wrong

• All the ids start with the same characters expected in version 7: that prefix is the timestamp, shared by everything generated in the same millisecond. In version 4 it would mean a broken random source.
• The inspector says version 0 the nil UUID, or a value that was never actually generated as a UUID. Check whatever wrote it.
• The inspector refuses a 32-character string a UUID without hyphens is a common storage format but not the canonical one. Add the hyphens, or paste it into a tool that expects the compact form.
• Two ids are identical in practice this means one was copied, or a seeded pseudo-random generator was used instead of a cryptographic one. Math.random in a loop can repeat; getRandomValues does not.
• A database rejects it usually a column typed CHAR(36) receiving a braced or uppercase form, or a uuid column receiving the hyphen-free one. Normalise before writing.

The adjacent vocabulary

• GUID Microsoft’s name for the same 128-bit identifier. Same thing, different spelling, and historically written in braces.
• ULID a non-standard alternative with the same time-ordered idea, written in 26 characters of base32. Readable and sortable, but not a UUID, so a uuid column will not take it.
• Snowflake id a 64-bit id with a timestamp, a machine number and a counter. Smaller than a UUID, sortable, but it needs machine numbers handed out centrally.
• Variant the two bits that say which UUID layout is in use. RFC 4122 is the one everything modern uses; the inspector names it.
• Collision two generated ids coming out identical. For v4 the probability is negligible; the realistic failure is a weak random source, not bad luck.