UUID Versions Explained: When to Use v4 vs v7

UUIDs (Universally Unique Identifiers) are 128-bit identifiers used everywhere from database primary keys to distributed tracing. But not all UUIDs are the same — the version matters for performance, security, and ordering. This guide explains when to use which version.

UUID v4: The Random Standard

UUID v4 is the most widely used version. It generates 122 bits of cryptographically random data, giving approximately 5.3 x 10^36 unique values.

f47ac10b-58cc-4372-a567-0d02b2c3d479
              ^
              4 = version indicator

Pros: Simple, widely supported, no coordination needed, no information leakage. Cons: Completely random, which causes problems with B-tree database indexes. New UUIDs scatter across the index, causing page splits and fragmentation.

// Node.js
import { randomUUID } from "crypto";
const id = randomUUID();

UUID v7: Time-Sorted for Databases

UUID v7 (RFC 9562, finalized in 2024) encodes a Unix timestamp in the first 48 bits, followed by random data. This makes v7 UUIDs lexicographically sortable by creation time.

018f6b5a-8c3e-7f00-a1b2-c3d4e5f6a7b8
              ^
              7 = version indicator
|-- timestamp --|-- random --|

Pros: Time-sortable, dramatically better database index performance than v4, still globally unique without coordination. Cons: Leaks creation time (first 48 bits), newer standard with less library support.

// Using the uuid package (v10+)
import { v7 as uuidv7 } from "uuid";
const id = uuidv7();

// Or using uuidv7 package
import { uuidv7 } from "uuidv7";
const id = uuidv7();

The Database Performance Impact

The difference between v4 and v7 for database primary keys is significant. With v4, inserting 1 million rows causes random writes across the B-tree index. With v7, inserts are always at the end of the index because new IDs are always larger than previous ones.

Benchmarks typically show 2-5x better insert performance with v7 on PostgreSQL and MySQL for write-heavy tables. Read performance also improves because recently created (and frequently accessed) rows are physically near each other on disk.

UUID v1 and v6: Legacy Versions

UUID v1 encodes a timestamp and MAC address. It is time-sortable but leaks your hardware identity. Avoid it unless required for backward compatibility. UUID v6 reorders v1's timestamp bits for better sortability. It is effectively superseded by v7, which uses a simpler Unix timestamp.

UUID v5: Deterministic Hashing

UUID v5 generates a consistent UUID from a namespace and a name using SHA-1 hashing. The same inputs always produce the same UUID.

import { v5 as uuidv5 } from "uuid";
const DNS_NAMESPACE = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
const id = uuidv5("example.com", DNS_NAMESPACE);
// Always returns the same UUID for "example.com"

Use v5 when you need idempotent ID generation from known inputs.

Decision Guide

| Use Case | Version | Why |

|----------|---------|-----|

| Database primary key | v7 | Sort-friendly, best index performance |

| API idempotency key | v4 | Random, no info leakage |

| Distributed tracing | v7 | Time-sortable for log correlation |

| Content-addressed ID | v5 | Deterministic from inputs |

| Legacy system compat | v4 | Widest support |

Conclusion

Default to UUID v7 for database primary keys and anywhere time-ordering is beneficial. Use UUID v4 when you need pure randomness with no information leakage. Use UUID v5 for deterministic ID generation. There is rarely a reason to use v1 or v6 in new projects.