UUID Version Guide
What is a UUID?
A UUID (Universally Unique Identifier) is a 128-bit number used to uniquely identify objects in software systems. Standardized in RFC 4122, it is formatted as 32 hexadecimal digits in five hyphen-separated groups: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
UUIDs are designed to be generated without a central authority. Any system can generate a UUID at any time and be confident it will not collide with UUIDs generated by other systems. This property makes them invaluable as database primary keys, request trace IDs, file names, and entity identifiers in distributed architectures.
There are several versions, each with different trade-offs. Version 4 (random) is the most widely used. Version 7 (time-sortable) is rapidly gaining adoption because its chronological ordering makes it much more efficient for database indexing than random UUIDs.
UUID Format
A UUID is a 128-bit identifier displayed as 32 hexadecimal characters in 5 groups:
xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
^ ^ ^ ^ ^
8 chars 4 4 4 12 chars
M = version (1, 4, 5, 7, ...)
N = variant (8, 9, a, b = RFC 4122)UUID Versions Compared
| Version | Algorithm | Sortable | Unique Guarantee | Best For |
|---|---|---|---|---|
| v1 | Time + MAC address | Yes (nanosecond) | Yes (per machine) | Legacy systems, time-ordered logs |
| v4 | Cryptographic random | No | Probabilistic (very high) | General purpose IDs |
| v5 | SHA-1 hash of name+namespace | No | Deterministic | Content-addressed IDs |
| v7 | Millisecond timestamp + random | Yes (millisecond) | Yes | Database primary keys |
UUID v4 — Random
// Node.js
import { randomUUID } from 'crypto';
const id = randomUUID();
// → "f47ac10b-58cc-4372-a567-0e02b2c3d479"
// Browser
const id = crypto.randomUUID();
// Python
import uuid
id = str(uuid.uuid4())
// Go
import "github.com/google/uuid"
id := uuid.New().String()
// Java
String id = UUID.randomUUID().toString();UUID v7 — Time-Sortable (Recommended for DBs)
v7 structure:
┌────────────────────────────────────────────────────────────â”
│ unix_ts_ms (48 bits) │ ver (4) │ rand_a (12) │ var │ rand_b │
└────────────────────────────────────────────────────────────┘
Example: 018e0f1a-7b00-7xxx-8xxx-xxxxxxxxxxxx
^^^^^^^^^^^^^^^^ ↠timestamp prefix (sortable!)UUID v7 is PostgreSQL 17+, MariaDB 10.10+, and MySQL 8.0+ compatible. It improves B-tree index performance by avoiding random page splits.
UUID v5 — Name-Based (Deterministic)
// v5 generates the same UUID for the same input every time
// Useful for: content-addressed IDs, deduplication
import { v5 } from 'uuid';
const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // DNS namespace
const id1 = v5('example.com', NAMESPACE);
const id2 = v5('example.com', NAMESPACE);
console.log(id1 === id2); // true — deterministic!Database Recommendations
| Database | Recommended Type | Column Type | Notes |
|---|---|---|---|
| PostgreSQL | UUID v7 | UUID | Native uuid type, gen_random_uuid() for v4 |
| MySQL / MariaDB | UUID v7 | CHAR(36) or BINARY(16) | BINARY(16) is more efficient |
| SQLite | UUID v4 or v7 | TEXT | No native UUID type |
| MongoDB | ObjectId (12 bytes) | ObjectId | ObjectId is already time-sortable |
| DynamoDB | UUID v4 | String (S) | No UUID type — store as string |