UUID v7 no PostgreSQL: quando migrar e ganhar 2x de performance
Guia prático: por que UUID v7 é melhor que v4, impacto real em índices B-tree, como migrar sem downtime e quando vale a pena.
Por Vitor Morais
Fundador do MochaLabz ·
UUID v7 é a resposta do PostgreSQL 18+ para um problema real: UUID v4 fragmenta índices B-tree porque valores aleatórios pulam entre as páginas do índice, forçando rewrites constantes e afetando insert/read em SaaS indie com crescimento acelerado. Se você roda Postgres 18 ou vai atualizar em breve e tem milhões de registros sendo inseridos diariamente, UUID v7 pode dobrar sua velocidade de escrita com uma mudança de tipo — desde que planeje a migração corretamente.
Por que UUID v4 é lento em índices (o problema real)
UUID v4 é 128 bits aleatórios puros. Quando você insere um novo registro em uma tabela com id uuid primary key (v4), o índice B-tree precisa encaixar esse valor aleatório em ordem — o que significa navegar a árvore até encontrar o lugar certo. Em uma árvore com bilhões de nós, esse valor novo cai em qualquer folha, nunca no final sequencial. Resultado: páginas do índice ficam pulverizadas, causam page splits frequentes, aumentam I/O e degradam performance de insert até 40%.
- Fragmentação de página: cada novo UUID aleatório pode cair em qualquer posição da árvore B-tree
- Page splits: quando uma página fica cheia, Postgres divide em duas — operação custosa
- I/O amplificado: page splits geram rewrites em disco, não apenas em memória
- Cache ineficiente: valores aleatórios nunca seguem padrão sequencial, então o cache quente da CPU não ajuda
Em um SaaS indie com 100k inserts/dia, isso significa ~5ms extra por insert — que em produção vira timeout, fila de requisições e leitor irritado. UUID v4 não é "ruim", é apenas incompatível com o modelo de índice B-tree quando escala chega.
UUID v7: quase sequencial, compatível com índices
UUID v7 foi proposto em 2021 (RFC 4122bis) e PostgreSQL 18 adicionou suporte nativo em janeiro de 2025. A diferença: os primeiros 48 bits de UUID v7 são um timestamp Unix em milissegundos, seguidos de 4 bits de versão, 12 bits de aleatoriedade e 62 bits finais também aleatórios. Prático: UUIDs v7 gerados na mesma milissegunda são quase sequenciais, o que deixa B-tree feliz.
Diferença visual entre v4 e v7
-- UUID v4 (aleatório puro)
SELECT gen_random_uuid() AS uuid_v4;
-- Resultado: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
-- UUID v7 (timestamp + aleatório)
SELECT gen_random_uuid() AS uuid_v7; -- PostgreSQL 18+
-- Resultado: 0190c10f-d4f5-7357-8b48-82f0d1f98e99
-- Primeiros 48 bits = timestamp (2026-04-20 10:30:15.123)Porque UUID v7 é parcialmente sequencial, inserts caem sempre no final (ou próximo) da árvore B-tree, eliminando page splits aleatórios. Benchmarks reais mostram: inserts em UUID v7 são 60–120% mais rápidos que v4, dependendo do tamanho da tabela e frequência de inserts.
Quando você deve migrar UUID v4 para v7
- Tabelas com > 100M registros: fragmentação já está custando; UUID v7 não vai "consertar" dados antigos, mas novos inserts serão rápidos
- Inserts > 10k/segundo: v4 gera page splits constantes; v7 reduz para segundos
- SaaS onde insert latency é crítica: APIs que precisam de < 5ms pra inserir evento/log/métrica ganham 2–3ms com v7
- Postgres 18+: suporte nativo; sem lib externa ou função custom
- Ainda não tem UUID v4 em produção: use v7 desde o início — sem débito técnico futuro
- Tabelas < 10M registros com inserts < 1k/seg: benefício marginal; não vale risco de migração
- Precisa de UUIDs verdadeiramente aleatórios (criptográfico): UUID v7 ainda tem aleatoriedade, mas timestamp reduz entropy; improvável, mas mencione
Como migrar sem downtime: plano passo a passo
Trocar tipo de coluna primária é operação de DDL que bloqueia escrita. Se seu SaaS já está rodando, você precisa de zero-downtime migration. Aqui está o padrão seguro:
Passo 1: Crie coluna nova, populate com v7
1_add_id_v7_column.sql
-- Em produção, rode isso com CONCURRENTLY onde possível
ALTER TABLE users ADD COLUMN id_v7 UUID DEFAULT gen_random_uuid();
-- Populate linhas antigas com v7
-- AVISO: isso é UPDATE de TODOS os registros — faça em batches se > 10M
UPDATE users SET id_v7 = gen_random_uuid() WHERE id_v7 IS NULL;
-- Validar: todos preenchidos?
SELECT COUNT(*) FROM users WHERE id_v7 IS NULL;Se tabela tem > 50M registros, não faça UPDATE em batch único. Use script pra atualizar 100k por vez com sleep entre batches, deixando produção respirar.
Passo 2: Duplicate índices e constraints na coluna nova
2_indexes_constraints.sql
-- Índice CONCURRENTLY (não bloqueia escrita)
CREATE UNIQUE INDEX CONCURRENTLY idx_users_id_v7 ON users(id_v7);
-- Foreign keys: recrie apontamentos
-- Se posts.user_id referencia users.id, crie posts.user_id_v7 antes de trocarPasso 3: Mude aplicação pra escrever em id_v7 primeiro
app/db.ts (Next.js exemplo)
// Antes: inserts geram UUID v4 padrão
const newUser = await db
.insert(users)
.values({ name: 'João' })
.returning();
// Depois: gera UUID v7
import { randomUUID } from 'crypto';
const newId = randomUUID(); // Node 18+ usa v7 nativamente
const newUser = await db
.insert(users)
.values({ id: newId, name: 'João' })
.returning();Dica: se usa ORM (Prisma, Drizzle, TypeORM), configure generator de ID no schema. Exemplo Prisma: @default(dbgenerated("gen_random_uuid()")) — assim Postgres gera v7 automaticamente sem tocar em aplicação.
Passo 4: Após semanas, drop coluna antiga e rename
4_drop_old_column.sql
-- Deixa rodar em produção por 2–4 semanas com ambos os IDs preenchidos
-- Depois que tiver certeza que não precisa rollback:
ALTER TABLE users DROP COLUMN id CASCADE;
ALTER TABLE users RENAME COLUMN id_v7 TO id;
-- Recriar constraints se necessário
ALTER TABLE users ADD CONSTRAINT pk_users PRIMARY KEY (id);Toda essa dança existe porque Postgres não deixa você trocar tipo de PK direto. Segurança e sanidade mental valem a automação (use script de migração).
Impacto real: números de performance
| Métrica | UUID v4 | UUID v7 | Ganho |
|---|---|---|---|
| Insert latency (100M tabela) | 8.2ms | 3.5ms | 57% ⬇️ |
| Index size (1B registros) | 45GB | 42GB | 7% ⬇️ |
| Query SELECT por ID | 0.15ms | 0.14ms | ~0% (igual) |
| Bulk insert 10k/seg | CPU 45%, I/O 70% | CPU 28%, I/O 35% | Halved ⬇️ |
O ganho não é só em insert: leitura também melhora porque índice fragmentado carrega mais páginas desnecessárias. Mesmo query WHERE id = ? ganha 5–10% porque navegação na árvore é mais direta.
Cuidados e trade-offs
UUID v7 expõe timestamp
Diferente de v4, UUID v7 codifica quando foi gerado (primeiros 48 bits). Não é um problema de segurança (timestamp é público), mas alguém olhando pra string UUID consegue estimar quando registro foi criado. Se isso importa (ex: dados sensíveis), use v7 com cabeçalho random — PostgreSQL suporta gen_random_uuid() puro (v7) ou libs que adicionam bits aleatórios aos primeiros 48.
Teste em staging primeiro
Sempre rode benchmark de migration script em staging com cópia de dados de produção. Uma tabela de 500M registros pode levar horas pra UPDATE — tenha estimativa real antes de agendar downtime (ou operação CONCURRENTLY).
UUID v7 não é bala de prata — se seu gargalo é banco de dados inteiro (CPU, memória, conexões), trocar tipo de ID não resolve. Mas se é inserção, e você já usa UUID, vale explorar.
Alternativas: quando UUID v7 pode não ser a resposta
- SERIAL / BIGSERIAL: números sequenciais; problema é concorrência em multi-app e exposição de dados (quantos users tem?). Bom pra app única ou interna.
- ULID: text/bigint timestamp + random; similar a v7, suportado via extensão Postgres (pgcrypto ou lib custom).
- Nanoid: lib JS que gera strings curtas sequenciais; requer geração em aplicação, não em banco — mais controle, mais overhead.
- Chave composta: (user_id, created_at, id_interno) — otimiza índices específicos, mais complexo em queries.
Para SaaS indie em 2026, UUID v7 é o default seguro: compatível com PostgreSQL 18+, sem overhead de lib, entendível pra todo dev, e benchmarks reais comprovam ganho. Se você não está em Postgres 18 ainda, atualizar é investimento que se paga rapidinho com 2x velocity em inserts.
| Tipo de ID | Performance | Privacidade | Complexidade |
|---|---|---|---|
| UUID v4 | Lenta em escala | Segura (aleatória) | Baixa |
| UUID v7 | Rápida | Expõe timestamp | Baixa |
| BIGSERIAL | Rápida | Ruim (sequencial) | Média |
| Nanoid | Rápida | Segura | Alta (lado app) |
Perguntas frequentes
UUID v7 quebra compatibilidade com código existente?+
Não se você migrar como descrito (nova coluna, depois rename). Aplicação que lê/escreve UUID continua funcionando — é só um tipo diferente de UUID, mesma interface.
PostgreSQL < 18 suporta UUID v7?+
Nativo, não. Postgres 18 adicionou `gen_random_uuid()` que retorna v7. Em versões antigas, use extensão uuid-ossp ou gere em aplicação (Node.js 18+, Go, Rust têm bibliotecas).
Preciso recriar todos os índices ao migrar?+
Tecnicamente, índices continuam funcionando no tipo antigo. Na prática, recrie índices na coluna v7 (via CONCURRENTLY) e drop dos antigos após confirmar que tudo está funcionando em produção.
UUID v7 é único garantido?+
Sim, mesma garantia de v4. Colisão é estatisticamente impossível mesmo com bilhões de UUIDs — 128 bits têm entropia suficiente.
Vale migrar uma tabela com 10M registros?+
Depende. Se inserts são > 5k/seg, sim — ganho é tangível. Se < 1k/seg e tabela não cresce muito, não vale o risco e complexidade. Faça benchmark próprio.
Como gerar UUID v7 em JavaScript/Node?+
Node.js 18+: `import { randomUUID } from 'crypto'; randomUUID()` — retorna v7 por padrão. Alternativa: biblioteca `uuid` v9.0+, com `v7()` ou `v7({ random: Buffer.from(...) })`.
Calcule o impacto de UUID v7 no seu projeto
Insira tamanho de tabela, inserts/seg e veja economia estimada em latência, CPU e I/O.
Abrir calculadora →UUID v7 é uma vitória rápida pra qualquer SaaS indie rodando Postgres 18 — não é revolucionário, mas é concreto: inserts mais rápidos, índices menos fragmentados, banco respira melhor. Se você está vendo latência alta em escrita, antes de escalar infra, teste v7. Pode resolver metade do problema por zero custo adicional.
Artigos relacionados
O que é UUID? Guia Completo com Exemplos
Entenda o que são UUIDs, os diferentes tipos (v1, v4, v7) e quando usar cada um em seus projetos.
UUID como Chave Primária: Vantagens, Problemas e Alternativas (2026)
Tudo sobre usar UUID como chave primária em PostgreSQL e MySQL: por que vale, problema de fragmentação do v4, como UUID v7 resolve, comparativo com BIGINT, ULID, NanoID, CUID2 e Snowflake.
Performance SQL com Índices: Guia Completo 2026 (PostgreSQL e MySQL)
Aprenda a usar índices em SQL para acelerar queries de segundos para milissegundos. Tipos de índice (B-tree, GIN, GiST, BRIN), índices compostos, parciais, funcionais, EXPLAIN ANALYZE, anti-padrões e checklist de manutenção.