UUID v4 ou v7: por que adotar IDs ordenáveis em 2026

Se você ainda usa SERIAL como chave primária em tabelas de alta escrita, este artigo é pra você. Mas mesmo se já migrou para UUID v4, existe uma razão pragmática para considerar v7 agora — e ela tem a ver com índices de banco, não com burocracia de RFC.

O problema com UUID v4 em índices

UUID v4 é completamente aleatório. Isso significa que cada INSERT em uma tabela com índice B-tree no UUID precisa inserir a chave em uma posição aleatória na árvore. Com volume suficiente de escrita, isso causa fragmentação severa e hot pages no índice — o banco fica constantemente lendo e escrevendo em páginas que não estão em cache.

Em tabelas de baixo volume, você não nota. Em tabelas com milhões de inserções por dia, isso aparece no tempo de resposta e no I/O de disco.

O que UUID v7 resolve

UUID v7 (RFC 9562, publicado em 2024) embute um timestamp de 48 bits nos primeiros bytes do UUID. Isso garante que UUIDs gerados próximos no tempo sejam próximos no índice. Inserções sequenciais no tempo → inserções sequenciais no índice → sem fragmentação.

UUID v4 (aleatório):
4a8e12f3-b7c1-4d2e-9f3a-1c5e8b2d7f9a

UUID v7 (timestamp + aleatório):
01960000-0000-7xxx-xxxx-xxxxxxxxxxxx
└─ timestamp ─┘    └──── random ────┘

A parte aleatória ainda existe — garantindo unicidade mesmo com múltiplos geradores simultâneos. A diferença é que a parte de tempo vem primeiro.

Compatibilidade

UUID v7 é um UUID válido no formato padrão de 36 chars. Colunas UUID em PostgreSQL, MySQL e SQLite aceitam v7 sem nenhuma mudança. ORMs que tratam UUIDs como strings opacos também funcionam sem modificação.

O que muda é apenas o gerador. No Node.js:

import { uuidv7 } from 'uuidv7';
const id = uuidv7(); // '01960b2a-4f7e-7d3c-8f1a-2c4e6b8d0f2a'

Em Python:

import uuid_utils
id = str(uuid_utils.uuid7())

Quando NÃO migrar

• Se sua tabela tem menos de ~100k inserções por dia, o ganho é marginal
• Se você já usa ULID (que resolve o mesmo problema de outra forma), não há motivo para migrar
• Se os UUIDs são expostos publicamente e você precisa que sejam completamente opacos — v7 vaza timing information (quando o registro foi criado, aproximadamente)

Migrando de v4 para v7

Você não precisa migrar os IDs existentes. Só precisa trocar o gerador. IDs novos serão v7, IDs antigos permanecem v4. O índice vai melhorar gradualmente à medida que novos registros dominam a distribuição.

Para gerar e inspecionar UUIDs de qualquer versão, o Gerador de UUID do Quick Tools suporta v4 e v7 com visualização do timestamp embutido.

Use v7, ponto.

Como adotar UUID v7 com baixo risco

A migração mais segura é trocar apenas o gerador para novos registros. Você não precisa reescrever IDs antigos nem alterar o tipo da coluna se ela já aceita UUID padrão. O banco passa a receber novos IDs ordenáveis por tempo, enquanto registros antigos continuam válidos.

Antes de mudar, confirme se alguma parte do sistema assume que UUIDs são totalmente aleatórios. Logs, auditoria e integrações raramente se importam, mas sistemas que tratam timing como informação sensível podem preferir v4. UUID v7 revela aproximadamente quando o ID foi criado.

Checklist de migração

Teste ordenação, índices e serialização em todos os serviços que geram IDs. Verifique também fixtures, mocks e validações de frontend. Algumas regex antigas aceitam qualquer UUID, mas outras podem travar a versão em 4 no terceiro grupo.

Depois de publicar, monitore fragmentação de índice, tempo de insert e tamanho de índice ao longo das semanas. O ganho aparece gradualmente conforme IDs novos passam a representar uma parte maior da tabela.

Use o Gerador de UUID para comparar v4 e v7 lado a lado e explicar a mudança para o time antes de alterar o gerador oficial.

Como explicar para o time

A melhor forma de vender UUID v7 não é citar a RFC, mas mostrar o efeito operacional: inserts mais amigáveis para índice e IDs ainda compatíveis com o tipo UUID. Quando o time entende que a mudança é local ao gerador, a adoção deixa de parecer uma migração arriscada.

Ponto de decisão

UUID v7 faz mais sentido quando a tabela cresce continuamente e o ID participa de índice primário ou ordenação operacional. Se o sistema é pequeno, a mudança pode esperar. Se o volume é alto, trocar cedo evita otimizações mais caras depois.