If you use gen_random_uuid() (UUID v4) as the primary key across high-write PostgreSQL tables, you get zero coordination overhead and unguessable public IDs—but once a table outgrows shared_buffers, random primary keys quietly destroy your write throughput.

Here is what actually happens inside the B-Tree index, how RFC 9562 UUID v7 solves it without changing your schema type, and a practical workflow to test UUID v7 data locally before migrating.

1. The Hidden Cost of Random UUID v4 in B-Tree Indexes

A standard UUID v4 places 122 pseudo-random bits across a 128-bit integer. Because PostgreSQL indexes uuid primary keys in a standard B-Tree:

  1. Every INSERT lands on a completely random leaf page inside the index instead of appending sequentially at the rightmost edge.
  2. Once the index exceeds RAM (shared_buffers), PostgreSQL constantly evicts hot pages and pulls cold leaf pages back from disk.
  3. Half-full pages split repeatedly (B-Tree page splits), inflating index size on disk and multiplying Write-Ahead Log (WAL) volume during replication.

Compare that with sequential keys (BIGINT or time-ordered UUIDs):

Metric (High-Churn Table) Random UUID v4 Time-Ordered UUID v7
Insert Locality Random across entire B-Tree Append-mostly (rightmost leaf pages)
Buffer Cache Hit Ratio Degrades rapidly past RAM size Stays high on recent writes
Index Bloat & Page Splits High under concurrent inserts Low, predictable fill factor
Lexicographical Time Sort Impossible Built-in (millisecond precision)
Postgres Column Type uuid (16 bytes) uuid (16 bytes — drop-in compatible)

2. Inside RFC 9562 UUID v7

Standardized in RFC 9562, UUID v7 preserves the familiar 8-4-4-4-12 hex layout (019339a4-7b20-7c1e-9a42-3f8d12c9b410) while structuring the first 48 bits as a big-endian Unix timestamp in milliseconds:

 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | unix_ts_ms (32 bits) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | unix_ts_ms (16 bits) | ver | rand_a (12b) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |var| rand_b (62 bits) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | rand_b (continued) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 

Because unix_ts_ms sits in the most significant bits, PostgreSQL sorts new rows in chronological order automatically—without exposing predictable sequential integer counts like /orders/1042 to external users.

3. Using UUID v7 in SQL & Application Code

PostgreSQL 18+ (Native uuidv7())

PostgreSQL 18 introduced native uuidv7() directly in core:

CREATE TABLE events ( id uuid PRIMARY KEY DEFAULT uuidv7(), tenant_id uuid NOT NULL, payload jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); 

Node.js / TypeScript (Or Quick Local Test Batches)

If you are on PostgreSQL 15–17 or generating IDs at the application edge (Node.js, Cloudflare Workers, Next.js), you can generate RFC 9562 UUID v7 strings before executing parameterized INSERTs—or quickly generate bulk SQL INSERT seed fixtures locally using a browser-side tool like the Taprico UUID v4 & UUID v7 Generator (runs 100% client-side and exports SQL INSERT, JSON, or CSV batches).

4. Two Practical Migration Rules Before Switching

  1. Keep Existing UUID v4 Rows Untouched: Because UUID v4 and UUID v7 share the exact same 128-bit uuid PostgreSQL column type, you do not need to rewrite historical primary keys. Simply switch the column DEFAULT (or app generator) for new writes—existing foreign keys keep working cleanly.
  2. Watch Clock Skew in High-Throughput Monotonic Pools: When generating hundreds of IDs within the same millisecond inside one Node.js worker, ensure your generator preserves monotonic sub-millisecond counters (rand_a) so batch inserts still land in strict order.

If you want to benchmark page splits or read a shorter migration checklist, I also documented the full Postgres B-Tree notes here: PostgreSQL UUID v7 vs. UUID v4 Migration Guide.

Are you already using UUID v7 in production, or still sticking with BIGINT / ULIDs? Curious to hear what your pg_stat_user_indexes bloat looks like.