← Back to blog

Oct 26, 2026 · Updated Nov 16, 2026 · 7 min read

Gerador de UUID: v4, v7 ou ULID como chave primária

Gerador de UUID na prática: compare v4, v7 e ULID como chave primária, veja o impacto no índice e gere identificadores no navegador.

Blocos de identificadores alinhados, uns aleatórios e outros ordenados no tempo.
Photo: Ontoom

Quase todo projeto novo chega nessa decisão: a tabela de pedidos vai ter id inteiro ou id UUID? Eu uso um gerador de UUID no navegador, o da Ontoom, quando preciso de massa de teste. Neste guia, comparo v4, v7 e ULID, o impacto no índice e o que eu testei ao escolher o tipo da coluna.

O inteiro autoincremental é pequeno e rápido, mas expõe volume: o pedido 1042 diz quantos pedidos você tem. Também exige que o banco gere o valor e complica fusões de bases. O UUID resolve isso: qualquer serviço gera o ID sozinho, antes de falar com o banco. A página da Wikipédia sobre UUID descreve o formato de 128 bits e as versões.

Só que “usar UUID” esconde uma segunda decisão, que pesa mais no desempenho: qual versão. Desde a RFC 9562, de 2024, que atualizou a antiga RFC 4122, as opções práticas são a v4 (aleatória) e a v7 (ordenada por tempo). Fora da RFC, o ULID ocupa um espaço parecido com a v7.

Como cada formato é montado

Ilustração da seção “Como cada formato é montado”
Como cada formato é montado
  • UUID v4: 122 bits aleatórios e 6 bits fixos de versão e variante. Dois IDs gerados em sequência não têm relação entre si.
  • UUID v7: os primeiros 48 bits são o horário Unix em milissegundos; o resto, descontando versão e variante, é aleatório. IDs gerados depois ficam maiores na ordenação.
  • ULID: também 128 bits, com 48 bits de tempo e 80 aleatórios, escrito em Base32 de Crockford com 26 caracteres. Não é um UUID, embora caiba numa coluna de 16 bytes.

Todos têm 128 bits. Com um gerador criptográfico, a chance de colisão é desprezível, no sentido descrito na Wikipédia. A diferença prática está na ordem, não no “espaço acabar”.

Por que a ordem importa para o índice

Ilustração da seção “Por que a ordem importa para o índice”
Por que a ordem importa para o índice

Bancos relacionais guardam a chave primária num índice B-tree. No MySQL com InnoDB, o próprio registro é organizado pela chave primária (índice clusterizado). Quando a chave cresce na mesma direção, como um autoincremento ou uma v7, cada inserção vai para a última página do índice: as páginas ficam cheias, o cache aproveita bem e quase não há divisão de páginas. Essa é a lógica usual dos índices em árvore, também resumida em materiais de banco e na discussão pública sobre UUID no PostgreSQL no GitHub.

Com a v4, cada novo ID cai num ponto aleatório da árvore. Com milhões de linhas, isso significa páginas divididas, índice maior, mais escrita em disco e pior uso do cache. Em tabelas pequenas a diferença é irrelevante. Em tabelas de eventos, logs ou pedidos com muitas escritas, ela aparece no benchmark e na conta do servidor.

No PostgreSQL a tabela não é clusterizada pela chave, mas o índice da chave primária sofre o mesmo efeito, e o WAL cresce mais com inserções espalhadas. Eu testei o raciocínio em uma tabela de eventos de homologação: a v4 não “quebrou” nada em volume baixo; o aviso vale para quando a escrita escala.

Armazenamento: 16 bytes, não 36

Ilustração da seção “Armazenamento: 16 bytes, não 36”
Armazenamento: 16 bytes, não 36

Um erro comum é salvar o UUID como texto. A forma com hífens tem 36 caracteres. Num VARCHAR(36), a comparação é mais lenta e o índice fica bem maior. Use o tipo nativo uuid do PostgreSQL ou BINARY(16) no MySQL. No MySQL, UUID_TO_BIN e BIN_TO_UUID convertem nos dois sentidos.

Cuidado com a função UUID() do MySQL: ela gera a versão 1, baseada em tempo e no endereço da máquina, com os bits de tempo numa ordem que não favorece o índice. UUID_TO_BIN(UUID(), 1) reorganiza esses bits. Se você vai mudar de estratégia, gerar v7 na aplicação costuma ser mais simples.

Como usar um gerador de UUID no dia a dia

Ilustração da seção “Como usar um gerador de UUID no dia a dia”
Como usar um gerador de UUID no dia a dia

PostgreSQL: gen_random_uuid() gera v4 desde a versão 13, sem extensão. O PostgreSQL 18 trouxe uuidv7() nativo; em versões anteriores, gere a v7 na aplicação.

JavaScript: crypto.randomUUID() gera v4 em navegadores e no Node recente. Para v7, o pacote uuid no GitHub oferece v7().

Python: uuid.uuid4() está na biblioteca padrão; uuid.uuid7() chegou em versões recentes da linguagem.

Para seeds, fixtures e dados de exemplo, onde a ordem não importa, um lote de v4 basta. O gerador da Ontoom cria vários de uma vez no navegador, sem enviar os valores a um servidor. Eu uso esse lote em testes e em demos, no mesmo espírito dos CPFs sintéticos.

O custo escondido da v7: ela revela quando o registro nasceu

Os primeiros dígitos hexadecimais de uma v7 carregam um horário. Quem vê o ID de um usuário numa URL pode estimar quando a conta foi criada e, comparando IDs, o ritmo de cadastros. Para muitos sistemas isso é aceitável. Para prontuários, denúncias ou contas de clientes, pode não ser.

Um desenho comum é usar dois identificadores: uma v7 (ou um inteiro) como chave primária interna, boa para o índice, e uma v4 como identificador público, exposto em URLs e APIs. Se esse público viajar num token, combine com o cuidado descrito no guia de JWT.

Resumo para decidir

  • Tabela pequena ou média, sem muita escrita: v4 resolve e é o mais simples.
  • Tabela com muitas inserções e UUID como chave primária: prefira v7.
  • Precisa de ID curto e legível em URL: ULID (26 caracteres) ou v7 em Base32.
  • O ID aparece para o usuário e a data de criação é sensível: v4 no identificador público.
  • Em qualquer caso: tipo nativo de 16 bytes, não texto.

Não existe uma resposta única, mas existe um padrão: a ordem dos IDs importa mais para o banco do que a escolha entre UUID e inteiro. Eu começo pela pergunta “esse ID vai para a URL?” e só depois escolho a versão.

Perguntas frequentes

Qual versão o gerador de UUID da Ontoom cria?

O gerador da Ontoom cria UUID v4 no navegador, útil para massa de teste, seeds e identificadores públicos. Para v7 em produção, gere na aplicação ou use a função nativa do banco, quando ela existir. Eu uso o gerador da Ontoom quando a ordem no índice não está em jogo e eu só preciso de valores prontos para colar no teste.

UUID v4 é uma má escolha como chave primária?

Não em tabela pequena ou média. O ponto frágil aparece com muita escrita: a v4 espalha inserções no índice B-tree, o que pode aumentar divisão de páginas e escrita em disco. Se a tabela de eventos crescer rápido, avalie v7 como chave interna. Meça no seu volume; o problema não aparece em cem linhas de homologação.

ULID é a mesma coisa que UUID v7?

Não. Os dois misturam tempo e aleatoriedade em 128 bits, mas ULID não é um UUID da RFC 9562 e se escreve em Base32, com 26 caracteres. Ele cabe em 16 bytes se você gravar o valor binário, não a string. Eu só escolho ULID quando quero um identificador curto e legível; caso contrário, fico no UUID, que as bibliotecas e os bancos entendem direto.

Devo gravar o UUID como texto com hífens?

Evite. O texto com hífens tem 36 caracteres e deixa o índice maior e a comparação mais lenta. Use o tipo nativo uuid no PostgreSQL ou BINARY(16) no MySQL. Exiba a forma com hífens só na API ou no log, se isso ajudar o time a ler o valor.

Fontes

Gerar UUID v4 no navegador

Gerador de UUID na prática: compare v4, v7 e ULID como chave primária, veja o impacto no índice e gere identificadores no navegador.

Gerar UUID v4 no navegador