Developer tools
How to generate and use UUIDs
Learn what UUIDs are, how version 4 random UUIDs work, and when to use them for database keys and API identifiers.
Document summary
A guide to UUIDs: what they are, when to use them as database keys and API IDs, and how to generate them correctly.
Key takeaways
- UUIDs are unique without a central counter
- Version 4 uses random bytes from the crypto API
- Store them in UUID or CHAR(36) columns
What a UUID is
A UUID (universally unique identifier) is a 128-bit value usually written as 36 characters in groups of 8-4-4-4-12 hex digits, such as 123e4567-e89b-12d3-a456-426614174000.
The version digit (the first digit of the third group) tells you how the UUID was produced. Version 4 is generated from random bytes, which makes collisions astronomically unlikely.
When UUIDs are the right choice
- Primary keys when records are created on multiple devices
- Public API identifiers that should not reveal record counts
- Idempotency keys so retries do not create duplicates
- Merging data from separate databases without key conflicts
Generate UUIDs for your project
- 1
Open the UUID generator locally.
- 2
Choose the format: hyphenated, plain, uppercase, or lowercase.
- 3
Generate one UUID or a batch for test fixtures.
- 4
Copy the values into your migration or seed script.
Store and index UUIDs correctly
Store UUIDs in a UUID column where the database supports it, or CHAR(36) elsewhere. Text indexes on UUIDs are larger than integer indexes, which matters at scale.
Keep UUIDs as opaque identifiers: do not parse meaning into them, and do not use them where sequential ordering is required.
Frequently asked questions
Are UUID collisions possible?
Theoretically yes, but version 4 uses 122 random bits, so the chance of collision is negligible even across billions of records.
What is the difference between UUID versions?
Version 4 is random. Versions 1 and 3/5 use time and namespace inputs. For most applications version 4 is the right default.
Can I use UUIDs as public API IDs?
Yes. Unlike sequential IDs, UUIDs do not reveal how many records exist.
Are UUIDs generated on a server?
No. The generator uses the browser crypto API locally.
