UUID v4 ou v7: qual usar como chave primária
Os dois têm 128 bits e parecem iguais, mas guardam coisas diferentes: o v4 é todo aleatório, o v7 começa com o momento em que foi criado. Essa diferença decide como o índice do banco se comporta e o que qualquer pessoa consegue ler nos seus IDs.
Como os bits são organizados
Um UUID é um número de 128 bits escrito como 32 dígitos hexadecimais em grupos de 8-4-4-4-12. O RFC 9562, de maio de 2024, que substituiu o RFC 4122, define as duas versões assim (o bit 0 é o mais à esquerda):
| Bits (qtd.) | v4 | v7 |
|---|---|---|
| 0–47 (48) | aleatório | tempo Unix (ms) |
| 48–51 (4) | versão 0100 | versão 0111 |
| 52–63 (12) | aleatório | aleat./contador |
| 64–65 (2) | variante 10 | variante 10 |
| 66–127 (62) | aleatório | aleatório |
O v4 tem 122 bits aleatórios; o v7 tem 48 bits de tempo e 74 para o resto. No texto, o primeiro dígito do terceiro grupo é a versão, e o primeiro dígito do quarto grupo é sempre 8, 9, a ou b, porque os dois bits da variante são 10. A data de um v7 sai direto dos 12 primeiros dígitos:
01a1fbd4-f500-7c3a-9e21-5b8d40f1a6c7
0x01a1fbd4f500 = 1795226400000 ms
= 21/11/2026 02:00:00 UTC
= 20/11/2026 23:00 em Brasília
Esse número é um timestamp Unix em milissegundos; o guia de timestamp Unix explica como ler um.
Por que o v7 ajuda o índice
A chave primária costuma ficar num índice B-tree, que mantém as chaves em ordem. No InnoDB do MySQL, as próprias linhas da tabela são gravadas na ordem da chave primária. A seção 2.1 do RFC 9562 aponta o problema do v4: valores criados em sequência não ficam próximos no índice, então cada linha nova cai numa página aleatória. Páginas cheias se dividem, páginas pela metade se multiplicam, e a parte do índice que precisa ficar na memória se aproxima do índice inteiro.
Um v7 criado depois é sempre maior que um criado num milissegundo anterior, então as linhas novas vão para a borda direita do índice, como num auto-incremento. A diferença é que a aplicação gera o ID antes de falar com o banco, por exemplo para colocá-lo numa fila ou usá-lo como chave de idempotência. A ordem dos bytes e a ordem do texto hex em minúsculas são a mesma, então ordenar o texto também funciona.
Dentro de um mesmo milissegundo, a ordem depende da implementação. A seção 6.2 do RFC oferece três métodos: um contador depois do timestamp, dados aleatórios que também servem de contador, ou precisão extra abaixo do milissegundo. O Python usa um contador de 42 bits, o PostgreSQL usa a fração de milissegundo, e a documentação do Node.js avisa que o randomUUIDv7() não tem garantia de ser estritamente crescente.
Chance de colisão
Para n UUIDs versão 4, a chance de dois serem iguais é de aproximadamente n² ÷ (2 × 2122):
| Quantidade de v4 | Chance de repetição |
|---|---|
| 1 milhão | 9,4 × 10−26 |
| 1 bilhão | 9,4 × 10−20 |
| 1 trilhão | 9,4 × 10−14 |
| 2,7 × 1018 | 50% |
Um v7 só colide com outro v7 do mesmo milissegundo. Com 74 bits aleatórios, mil UUIDs por milissegundo vindos de geradores separados dão uma chance de cerca de 2,6 × 10−17 por milissegundo, ou uns 8 × 10−7 depois de um ano inteiro nesse ritmo. Geradores que gastam bits com contador têm menos bits aleatórios, mas o contador impede colisões dentro do mesmo gerador. Tudo isso supõe bits vindos de um gerador criptograficamente seguro, como pede a seção 6.9 do RFC. UUIDs montados com Math.random não entram nessa conta.
Quando não expor um v7
Quem vê um v7 lê a data de criação com precisão de milissegundo, como no exemplo acima. Em IDs de conta, pedido ou documento que aparecem em URLs públicas, isso revela quando a conta foi aberta ou quando a compra foi feita. A seção 8 do RFC chama o timestamp embutido de superfície de ataque muito pequena, mas acrescenta que UUIDs não devem ser considerados difíceis de adivinhar nem usados como credencial, ou seja, algo cuja simples posse dá acesso. Uma divisão sensata: v7 como chave primária interna e v4 no ID que aparece para fora. Links de redefinição de senha e de convite precisam de um token aleatório próprio, não de um UUID.
Gerando UUIDs no código
JavaScript. No navegador, crypto.randomUUID() só existe em páginas HTTPS. Do Node.js 14.17 ao 18, importe de node:crypto, porque o objeto global crypto só ficou disponível sem flag no Node.js 19.
// v4: navegador (HTTPS), Node.js 19+
crypto.randomUUID();
// v7: Node.js 24.16+ ou 26.1+
import { randomUUIDv7 }
from 'node:crypto';
randomUUIDv7();
// v7 no navegador: pacote npm uuid 10+
import { v7 } from 'uuid';
v7();
Python. O uuid7() chegou no Python 3.14, e o atributo time de um v7 traz os milissegundos Unix.
import uuid
uuid.uuid4()
uuid.uuid7() # Python 3.14+
uuid.uuid7().time # ms Unix
PostgreSQL. Guarde os IDs numa coluna uuid (16 bytes), não como texto de 36 caracteres. O gen_random_uuid() está no núcleo desde a versão 13 e o uuidv7() desde a 18. O uuid_extract_timestamp() apareceu na 17 só para v1; a 18 acrescentou o v7.
SELECT gen_random_uuid(); -- v4, PG 13+
SELECT uuidv7(); -- PG 18+
CREATE TABLE pedidos (
id uuid PRIMARY KEY DEFAULT uuidv7(),
total numeric NOT NULL
);
SELECT uuid_extract_timestamp(id)
FROM pedidos; -- v7: PG 18+
Gerando e analisando no swift.id
- Abra o Gerador e validador de UUID e escolha Versão 4 (aleatória) ou Versão 7 (ordenada por tempo).
- Preencha Quantidade (1-1000) e, se precisar, ajuste o Formato: Maiúsculas, Sem hifens ou Chaves { }. Mil v7 gerados de uma vez saem em ordem, porque a ferramenta usa um contador de 12 bits.
- Toque em Copiar ou Baixar .txt, ou em Gerar novos para trocar todos.
- Cole qualquer UUID em Analisar um UUID para ver versão e variante e, nos v1, v6 e v7, a data de criação, inclusive os Milissegundos Unix, que você confere no Conversor de timestamp Unix.
Perguntas frequentes
v4 e v7 podem ficar na mesma coluna?
uuid aceita qualquer versão. As linhas antigas continuam espalhadas pelo índice; só as novas entram em ordem.Um v7 é mais fácil de adivinhar que um v4?
Por que v7 gerados em dois servidores não ficam perfeitamente em ordem?
Quanto espaço um UUID ocupa no banco?
uuid do PostgreSQL ocupa 16 bytes. Como texto, a forma padrão de 36 caracteres precisa de mais que o dobro, e o índice cresce junto.