Pular para o conteúdo
Setup do Dev
Guias

UUID v4 ou v7 como chave primária no PostgreSQL: o que muda no índice

Testamos as duas versões no PostgreSQL 18 com 3 milhões de linhas: o v7 inseriu 20 vezes mais rápido e deixou o índice 27% menor. E o que ele não garante.

Por Setup do Dev
5 min de leitura
Compartilhar
Capa do Setup do Dev em cinza-azulado com grade: "UUID v4 ou v7 como chave primária", com um UUIDv7 de exemplo, o logo do PostgreSQL e barras comparando 311 s do v4 com 15,6 s do v7

Usar UUID como chave primária resolve problemas reais. O id pode nascer na aplicação, antes de a linha chegar ao banco; dados de vários lugares se juntam sem colisão; e quem vê /pedidos/1042 não descobre quantos pedidos a loja teve. O preço vem no índice. O UUID mais usado, o v4, é aleatório, e cada linha nova cai num ponto qualquer da árvore.

O PostgreSQL 18, lançado em 25 de setembro de 2025, trouxe a função uuidv7(), que põe o horário na frente do identificador. Para ver quanto isso muda na prática, medimos as duas versões num PostgreSQL 18.4, com até 3 milhões de linhas.

O que tem dentro de um UUIDv7

O formato é do RFC 9562, de maio de 2024, que substituiu o antigo RFC 4122. Dos 128 bits, os 48 primeiros guardam o horário Unix em milissegundos; depois vêm 4 bits de versão, 2 de variante e 74 que podem ser aleatórios ou servir de contador. O PostgreSQL usa parte deles para uma fração de milissegundo, segundo a documentação, e o resto é aleatório.

Dá para ver o horário a olho. Os 12 primeiros dígitos hexadecimais são os milissegundos:

SELECT uuidv7();
-- 01a16a3d-1736-7540-97f0-f34953640bec

SELECT uuid_extract_timestamp('01a16a3d-1736-7540-97f0-f34953640bec');
-- 2026-10-23 16:29:10.966-03

SELECT uuid_extract_version(uuidv4()), uuid_extract_version(uuidv7());
-- 4 | 7

A função aceita um intervalo para deslocar o horário (uuidv7(interval '-1 day') gera um id com a data de ontem), e a documentação avisa que o horário extraído não é necessariamente o da geração. O uuidv4() também é novo: é um nome mais claro para o gen_random_uuid(), que continua existindo.

Como usar numa tabela

CREATE TABLE pedidos (
  id         uuid PRIMARY KEY DEFAULT uuidv7(),
  cliente_id uuid NOT NULL,
  total      numeric(12,2) NOT NULL,
  criado_em  timestamptz NOT NULL DEFAULT now()
);

A coluna é do tipo uuid, que ocupa 16 bytes. Guardar o mesmo valor como text gasta mais que o dobro, e o RFC recomenda o valor binário de 128 bits. Numa tabela que já usa v4, basta trocar o padrão com ALTER TABLE pedidos ALTER COLUMN id SET DEFAULT uuidv7();: as linhas novas passam a chegar em ordem, e as antigas continuam onde estão.

Interior de um servidor de rack aberto, com dissipador de cobre, pentes de memória e ventoinhas
Foto: Tobias Maier / Wikimedia Commons (licença CC0)

O teste

Criamos tabelas temporárias só com a chave primária e inserimos valores já gerados, para separar o custo de gerar do custo de pôr no índice. Gerar um milhão de UUIDs levou cerca de 0,8 segundo nas duas versões, então a diferença está toda na inserção. Rodamos dois cenários num computador com Windows: um milhão de linhas com o índice cabendo na memória e 3 milhões com só 8 MB de memória para as tabelas temporárias, o que obriga o banco a ir ao disco.

  • Índice na memória, 1 milhão de linhas: o v4 levou 7,7 s e o v7, 3,5 s. O índice ficou com 37,9 MB no v4 e 30,1 MB no v7.
  • Índice maior que a memória, 3 milhões de linhas: o v4 levou 311 s e o v7, 15,6 s, cerca de 20 vezes menos. O índice ficou com 123,4 MB no v4 e 90,3 MB no v7, 27% menor.
  • Para comparar: com bigint gerado pelo banco, um milhão de linhas entraram em 0,87 s, com um índice de 21,4 MB. A chave de 8 bytes continua sendo a mais barata.

Os números de tempo variam com a máquina e com a carga dela, e tabelas temporárias não escrevem no WAL, então uma tabela comum paga um pouco mais nos dois casos. A proporção é o que importa.

Por que o v4 pesa tanto

O índice de chave primária é uma árvore B, com as chaves em ordem. Com o v7, cada id novo é maior que o anterior e vai para a última página da árvore, que já está na memória. Com o v4, cada inserção cai numa página diferente: enquanto o índice cabe na memória, isso custa pouco; quando não cabe, quase toda inserção precisa ler uma página do disco. As páginas também se dividem no meio quando enchem, e ficam com espaço sobrando, por isso o índice do v4 é maior.

A ordem aparece até na tabela. Na estatística do PostgreSQL, a correlação entre a ordem física das linhas e a ordem da chave deu 1 no v7, a mesma ordem, e praticamente zero no v4. Na prática, uma consulta pelas linhas mais recentes de uma tabela com v7 lê páginas vizinhas.

Um disco rígido Maxtor sobre uma mesa de madeira
Foto: hystiff / Wikimedia Commons (licença CC0)

O que o UUIDv7 não garante

Ordem estrita só vale dentro de um mesmo gerador. No nosso teste, 100 mil ids gerados na mesma consulta saíram todos em ordem, espalhados por 99 milissegundos. Entre servidores diferentes, ou depois de um acerto no relógio, não há essa garantia. O texto de Robert Alexander que circulou no Hacker News nesta semana mostra casos assim e resume que a única propriedade firme é a unicidade.

O id também revela quando a linha foi criada. Num endereço como /perfil/01a16a3d-…, qualquer pessoa descobre a data de cadastro da conta, mesmo que a página não a mostre. O RFC chama isso de superfície de ataque pequena, mas recomenda o v4 quando o UUID tem papel de segurança, e lembra que nenhum UUID deve servir de senha de acesso.

Qual escolher

Para id interno de um banco só, o bigint com GENERATED ALWAYS AS IDENTITY continua sendo o menor e o mais rápido. Quando o id precisa nascer fora do banco ou aparecer em endereços, o v7 é o padrão sensato para chave primária no PostgreSQL 18. O v4 fica para os casos em que o momento da criação não pode vazar. E token de acesso, link de redefinição de senha e afins merecem um valor aleatório próprio, fora da chave primária.

Fontes: Documentação do PostgreSQL 18: funções de UUID, Notas de lançamento do PostgreSQL 18.0, RFC 9562, Robert Alexander: UUIDv7 doesn’t have the properties you think it does

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. O que tem dentro de um UUIDv7
  2. Como usar numa tabela
  3. O teste
  4. Por que o v4 pesa tanto
  5. O que o UUIDv7 não garante
  6. Qual escolher

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.