UUID v7 no PostgreSQL: performance, indexação e quando evitar

UUID v7 no PostgreSQL resolve um problema que UUID v4 carrega desde sempre: fragmentação de índice B-tree causada por valores aleatórios. Enquanto v4 espalha inserts por toda a árvore — forçando page splits constantes —, v7 gera identificadores monotônicos baseados em timestamp que se acumulam no final do índice, na mesma direção que o tempo. O resultado prático é insert mais rápido, leitura sequencial mais eficiente e índices que ocupam menos espaço em disco. Mas v7 não é bala de prata, e trocar sem entender os trade-offs cria problemas novos.

Como UUID v7 funciona por dentro

UUID v7 embute um timestamp Unix em milissegundos nos primeiros 48 bits do identificador. Os bits restantes são preenchidos com dados aleatórios, mas a ordenação temporal já está garantida pela porção inicial. Isso torna o valor monotonicamente crescente — dois UUIDs gerados em sequência sempre respeitam a ordem cronológica, mesmo vindos de processos diferentes (desde que os relógios estejam sincronizados com precisão razoável).

UUID v4, por contraste, é 122 bits de puro random. Não existe relação entre a hora de criação e o valor gerado. Para a aplicação isso geralmente não importa — um ID é um ID. Mas para o mecanismo de indexação do banco, a diferença é brutal.

Por que B-tree sofre com UUID v4

Índices B-tree no PostgreSQL armazenam valores em páginas ordenadas de 8 KB. Quando a chave primária é um inteiro auto-incremento (SERIAL, BIGSERIAL), novos registros sempre caem na última página da árvore — o chamado right-append pattern. O banco mantém essa página no buffer pool, os inserts são sequenciais e os page splits são raros.

UUID v4 destrói esse padrão. Cada novo valor cai numa posição aleatória da árvore, forçando o PostgreSQL a carregar páginas dispersas do disco pro buffer pool, dividir páginas cheias (page split) e reorganizar ponteiros. Em tabelas com milhões de registros, isso se traduz em:

• Write amplification — cada insert pode tocar 3–5 páginas em vez de 1.
• Índice inchado — page splits criam páginas parcialmente vazias (fill factor real cai pra 50–70%).
• Buffer pool churn — páginas aleatórias expulsam páginas quentes do cache, prejudicando leituras.
• Vacuum mais pesado — mais dead tuples espalhadas significam mais trabalho pro autovacuum.

UUID v7 elimina a raiz do problema. Como os valores são monotônicos, o padrão de insert volta a ser right-append — igual a um BIGSERIAL, mas com a vantagem de ser globalmente único sem coordenação centralizada.

Gerando UUID v7 no PostgreSQL

PostgreSQL 18 inclui a função nativa uuidv7(), que gera UUIDs versão 7 diretamente no banco. Em versões anteriores (14–17), é preciso usar uma extensão como pg_uuidv7 ou gerar o valor na aplicação. O caminho mais comum em stacks com Supabase ou ORMs como Drizzle/Prisma é gerar no lado da aplicação e enviar como parâmetro — o que funciona igualmente bem, desde que o relógio da máquina esteja razoavelmente sincronizado.

Para versões anteriores ao PostgreSQL 18, a geração pode ser feita no lado do servidor da aplicação. Em TypeScript com a lib uuidv7:

Medindo a diferença: EXPLAIN ANALYZE na prática

A melhoria de performance do UUID v7 sobre v4 não é teórica. Ela aparece em três métricas concretas que qualquer instância PostgreSQL consegue medir: tamanho do índice em disco, latência média de INSERT em batch, e eficiência de range scans sobre a PK.

Em testes típicos com 1 milhão de registros, o índice B-tree de uma tabela com UUID v4 ocupa significativamente mais espaço que o equivalente com v7 — a diferença varia conforme o hardware e a configuração do fill_factor, mas o padrão é consistente: menos page splits resultam em páginas mais cheias e índice menor.

Para medir a latência de insert, a forma mais direta é usar \timing no psql e rodar um batch de INSERT INTO ... SELECT com generate_series. A diferença fica mais visível à medida que a tabela cresce — em tabelas pequenas (< 100 mil registros), v4 e v7 são quase indistinguíveis.

Range scans — queries do tipo WHERE id > $1 ORDER BY id LIMIT 100 — se beneficiam diretamente da monotonicidade. Como UUIDs v7 são cronológicos, um range scan sobre a PK equivale a uma paginação temporal. Com v4, o mesmo range scan retorna registros em ordem arbitrária, sem utilidade prática pra cursores.

Quando UUID v4 ainda é a escolha certa

UUID v7 não substitui v4 em todos os cenários. Existem pelo menos três situações onde v4 continua fazendo mais sentido:

1. Privacidade do identificador. UUID v7 revela quando o registro foi criado. Em APIs públicas onde o timestamp do ID é informação sensível (tokens de acesso, IDs de usuário expostos em URL), v4 é preferível porque não vaza cronologia.
2. Compatibilidade com sistemas legados. Muitos ORMs, bibliotecas de validação e APIs de terceiros esperam UUID v4 ou tratam qualquer UUID como opaco. Migrar pra v7 pode exigir atualizar validações, serializers e testes — custo que nem sempre se paga em tabelas pequenas.
3. Tabelas que nunca passam de 100 mil registros. A vantagem de indexação do v7 escala com o volume. Em tabelas de configuração, lookup ou referência que raramente crescem, a diferença de performance é irrelevante e v4 é mais simples de gerar em qualquer linguagem.

UUID v7 vs v4 vs BIGSERIAL: comparação direta

A tabela deixa claro o posicionamento: UUID v7 combina a vantagem de performance do BIGSERIAL com a unicidade global do UUID. O custo é o dobro do tamanho (16 bytes vs 8) e a exposição do timestamp — trade-offs aceitáveis na maioria dos casos onde um UUID como chave primária já é a decisão tomada.

Migrando uma tabela existente de v4 para v7

Migrar registros existentes de UUID v4 pra v7 quase nunca vale a pena. Os IDs antigos já estão referenciados em foreign keys, logs, URLs, webhooks e caches externos. Reescrever todos é arriscado e caro. A abordagem pragmática é:

1. Mudar o default da coluna pra uuidv7() (ou gerar v7 na aplicação) — novos registros já entram monotônicos.
2. Manter os UUIDs v4 antigos como estão — a coluna continua sendo uuid, o tipo não muda.
3. Rodar REINDEX na tabela depois de um tempo, quando a proporção de v7 for majoritária — o índice vai se reorganizar naturalmente com os novos valores monotônicos na ponta.
4. Monitorar pg_stat_user_indexes pra confirmar que o tamanho do índice estabiliza ou diminui após o reindex.

Quem usa versões anteriores ao PostgreSQL 18 pode criar uma função PL/pgSQL que implementa a geração, ou simplesmente gerar na aplicação e passar o valor explicitamente no INSERT. O artigo sobre diferenças entre v4 e v7 detalha os formatos de bits de cada versão.

Armadilhas que a documentação não destaca

• Cursor-based pagination com v7 parece mágica, mas tem edge case. Se dois registros forem criados no mesmo milissegundo, a ordem entre eles depende dos bits aleatórios. Pra paginação com garantia estrita de ordem, combine id com created_at como tiebreaker — ou use um sub-milissegundo counter (algumas implementações de v7 já fazem isso).
• `ORDER BY id` não substitui `ORDER BY created_at`. Embora v7 seja cronológico, a resolução é de milissegundos. Se o timestamp importa pra regra de negócio (SLA, auditoria, billing), mantenha a coluna created_at com timestamptz — não dependa do ID pra isso.
• ORMs podem validar versão. Prisma, TypeORM e Drizzle usam bibliotecas de validação de UUID que podem rejeitar v7 se estiverem verificando a version nibble. Teste antes de migrar e atualize as dependências se necessário.
• Replicação lógica ordena por LSN, não por PK. Se a arquitetura usa CDC (Change Data Capture) ou replicação lógica, a ordem dos eventos não depende do UUID — depende do Write-Ahead Log. A monotonicidade do v7 ajuda o índice local, não o pipeline de replicação.

Para quem está otimizando queries e índices além da PK, o guia de performance com índices SQL cobre estratégias complementares — partial indexes, covering indexes e análise de pg_stat_user_tables.