Skip to content
Sarj Standards

SQL · performance

prefer-uuidv7-default

sql:prefer-uuidv7-default

`gen_random_uuid()` emits a random UUIDv4 — use `uuidv7()` so keys are time-ordered.

Code
SARJ109
Default
error
Fix
none
Languages
sql

Why

Random UUID keys scatter inserts across a B-tree, while time-ordered UUIDv7 values preserve index locality.

Fix

Use the PostgreSQL uuidv7() function for generated UUID defaults and values.

Before / after

Executed by this rule’s unit tests.

Before

Random UUID default

migrations/001_calls.sql · focus
CREATE TABLE call (id UUID PRIMARY KEY DEFAULT gen_random_uuid());

After

Time-ordered UUID default

migrations/001_calls.sql · focus
CREATE TABLE call (id UUID PRIMARY KEY DEFAULT uuidv7());

Limits

  • uuidv7() requires PostgreSQL 18 or an equivalent extension-provided function.