What a UUID is
A universally unique identifier is a 128-bit value written as 32 hexadecimal digits in five hyphen-separated groups: 8-4-4-4-12. For example f47ac10b-58cc-4372-a567-0e02b2c3d479.
The purpose is generating identifiers that will not collide, without any central coordination. Two systems on opposite sides of the world can each mint UUIDs and be confident they will never produce the same one — which is what makes them valuable in distributed systems.
This generator uses crypto.randomUUID() where available, falling back to crypto.getRandomValues. Both draw on the operating system's cryptographic random source.
Why collisions effectively never happen
A version 4 UUID has 122 random bits — the other 6 are fixed version and variant markers. That gives roughly 5.3 × 1036 possible values.
The often-quoted illustration: to reach a 50% chance of a single collision you would need to generate about 2.7 × 1018 UUIDs. Producing a billion per second, that takes around 85 years. For any realistic application, treating v4 UUIDs as unique is safe.
The caveat is randomness quality. A UUID generated from a weak pseudo-random source can collide far sooner, which is why using the platform's cryptographic generator matters rather than Math.random().
The versions and when they differ
Version 4 is randomly generated and by far the most common. Use it unless you have a specific reason not to.
Version 1 combines a timestamp with the machine's MAC address. It sorts roughly by creation time but leaks hardware identity and creation time, which is a privacy consideration.
Versions 3 and 5 are deterministic, derived by hashing a namespace and a name — the same input always produces the same UUID. Useful when you need a stable identifier derived from existing data.
Version 7, standardised more recently, embeds a Unix timestamp in the high bits followed by random data. This makes it sortable by creation time while remaining unpredictable, which solves a real database problem described below.
The database index problem
Random UUIDs as primary keys have a genuine performance cost that catches teams out at scale.
Databases store rows in B-tree indexes. Sequential integer keys append to the end of the index, which is cheap. Random UUIDs insert at arbitrary positions, causing page splits, index fragmentation, and poor cache locality. On large tables the difference in write throughput can be substantial.
UUIDs are also 16 bytes against 4 or 8 for an integer, and every secondary index carries a copy of the primary key. On a table with several indexes and millions of rows, the storage overhead compounds.
The usual answers are: use UUIDv7 or another time-ordered scheme so inserts stay roughly sequential; store the value as a native UUID or BINARY(16) column rather than a 36-character string; or keep an internal auto-increment primary key and expose a UUID as a separate indexed column.
Where UUIDs earn their keep
Distributed ID generation — multiple services creating records without coordinating.
Offline-first applications — a mobile client can create records with real IDs while disconnected, and sync later without renumbering.
Non-enumerable public identifiers — sequential integers in URLs let anyone count your records and iterate through them. UUIDs do not.
Idempotency keys — a client-generated UUID lets an API safely detect and ignore a duplicate request after a network retry.
A UUID is not a security token, though. It is unguessable but not secret, and it is frequently logged, cached, and included in URLs. Use a purpose-built token for authorisation.
Frequently asked questions
What is the chance of a UUID collision?
Negligible for any realistic use. A version 4 UUID has 122 random bits, and reaching a 50% chance of one collision would take roughly 85 years of generating a billion per second.
Should I use UUIDs as database primary keys?
It depends on scale. Random UUIDs fragment B-tree indexes and slow inserts on large tables. UUIDv7 or another time-ordered scheme avoids most of that, as does keeping an internal integer key alongside a public UUID.
What is the difference between UUID v4 and v7?
V4 is entirely random. V7 embeds a Unix timestamp in the high bits followed by random data, making it sortable by creation time while staying unpredictable - which is much friendlier to database indexes.
Are UUIDs secure enough to use as secret tokens?
No. A version 4 UUID is unguessable but not secret - it is routinely logged, cached, and placed in URLs. Use a purpose-built cryptographic token for authorisation.