O que é o UUIDv7

O UUIDv7 e a versão 7 do identificador único universal (UUID), criada para gerar valores que são, ao mesmo tempo, únicos e ordenáveis por tempo. Ele foi padronizado na RFC 9562, publicada pela IETF em maio de 2024, que substituiu a antiga RFC 4122 e oficializou três novas versões: 6, 7 e 8.

A ideia surgiu de um problema prático que todo desenvolvedor de backend já sentiu na pele. O UUIDv4, totalmente aleatório, e ótimo para evitar colisões, mas péssimo como chave primaria de banco de dados: por não ter ordem nenhuma, ele espalha as gravações pelo índice e degrada a performance ao longo do tempo.

O UUIDv7 resolve isso embutindo o horário de criação nos primeiros bits do identificador. Assim você ganha o melhor dos dois mundos: a unicidade global de um UUID e a ordenação sequencial de um id incremental, sem precisar de um servidor central coordenando a geração.

Como funciona

Um UUID tem sempre 128 bits (16 bytes), normalmente exibidos como 36 caracteres no formato 8-4-4-4-12. No UUIDv7, esses bits são organizados de forma específica para garantir a ordenação.

Os 48 bits mais significativos guardam um timestamp Unix em milissegundos. Como esses bits ficam no início, dois IDs gerados em momentos diferentes já saem em ordem cronológica quando comparados como texto ou como número. Em seguida vem 4 bits que identificam a versão (o número 7), depois bits de variante e, por fim, bits aleatórios que garantem a unicidade dentro do mesmo milissegundo.

Pense numa analogia: o UUIDv4 e como jogar 128 moedas para o alto e anotar o resultado. O UUIDv7 e como escrever a data e a hora atual e só depois jogar as moedas restantes. O resultado continua praticamente impossível de repetir, mas agora ele "sabe" quando nasceu.

Principais recursos

O grande diferencial do UUIDv7 e ser k-sortable, ou seja, ordenável pelo tempo de geração. Isso traz uma série de benefícios diretos para quem trabalha com bancos de dados e sistemas distribuídos.

  • Localidade de índice: inserções em árvores B-tree acontecem perto umas das outras, reduzindo fragmentação e quebras de página.
  • Ordenação gratuita: ordenar por id já e praticamente ordenar por data de criação, sem precisar de uma coluna extra.
  • Geração distribuída: qualquer serviço pode criar IDs sem consultar o banco ou um gerador central, o que ajuda em microservicos.
  • Compatibilidade total: continua sendo um UUID de 128 bits, então cabe em qualquer coluna ou campo que já aceita UUID.

Esses pontos fazem o UUIDv7 ser especialmente atraente para quem já usava UUIDv4 como chave primaria e sofria com a queda de desempenho conforme a tabela crescia.

Como começar a usar

A boa noticia e que você quase nunca precisa montar os bits na mao. A maioria das linguagens e bancos modernos já oferece geração de UUIDv7 pronta, seja na biblioteca padrão, seja em pacotes muito conhecidos.

No JavaScript e TypeScript, o pacote uuid no npm já inclui a versão 7. No Go, a biblioteca oficial google/uuid expõe a função NewV7. No .NET, versões recentes trazem o método Guid.CreateVersion7. E no PostgreSQL, versões recentes incluem a função nativa uuidv7 para usar direto em DEFAULT de coluna.

O passo a passo geral e simples: primeiro escolha onde o ID vai ser gerado (na aplicação ou no banco), depois ajuste a coluna para o tipo UUID e, por fim, troque a chamada de geração do v4 pelo v7. Como o formato e idêntico, o resto do seu código costuma nem perceber a diferença.

Exemplo prático

Vamos a um caso concreto em Node.js. Imagine que você esta criando registros de pedidos e quer que cada pedido tenha um id único e ordenável. Usando o pacote uuid, fica assim:

import { v7 as uuidv7 } from 'uuid';

const pedido = {
  id: uuidv7(),
  cliente: 'Mariana Souza',
  total: 149.90,
};

console.log(pedido.id);
// exemplo: 0190a4c2-3f9b-7c1a-9d2e-8f1b2c3d4e5f

Repare que os primeiros blocos do id mudam pouco entre dois pedidos criados na mesma janela de tempo, porque representam o timestamp. Se você gerar vários e ordenar por id, eles saem na mesma ordem em que foram criados.

No PostgreSQL, da para deixar o próprio banco gerar o valor na inserção, evitando lógica extra na aplicação:

CREATE TABLE pedidos (
  id    uuid PRIMARY KEY DEFAULT uuidv7(),
  total numeric(10,2) NOT NULL
);

INSERT INTO pedidos (total) VALUES (149.90);
SELECT id FROM pedidos ORDER BY id;

Comparação com alternativas

Para escolher bem, vale comparar o UUIDv7 com as opções mais comuns de chave primaria.

O UUIDv4 e totalmente aleatório. Ele é perfeito quando você só precisa de unicidade e não se importa com ordem, mas vira um problema de performance como chave primaria em tabelas grandes. O id incremental (auto-increment) e sequencial e rápido no índice, mas depende de um único ponto de geração e expõe quantos registros você tem, o que pode ser um vazamento de informação.

Existe ainda o ULID, um formato muito parecido com o UUIDv7 na ideia (timestamp na frente, aleatório atrás), mas que usa uma representação de texto diferente, de 26 caracteres em base32. A vantagem do UUIDv7 sobre o ULID e ser um padrão oficial da IETF e usar o mesmo formato de 16 bytes que os bancos já conhecem como UUID.

Pontos positivos e limitações

Os pontos fortes já ficaram claros: ordenação por tempo, boa performance de índice, geração descentralizada e compatibilidade com o ecossistema UUID existente.

Mas e preciso ser honesto sobre as limitações. A principal e a privacidade: como o UUIDv7 carrega o horário de criação, qualquer pessoa que veja o id consegue saber, com precisão de milissegundos, quando aquele registro nasceu. Para um pedido isso pode ser irrelevante, mas para um recurso sensível pode ser indesejável.

Outra limitação e que ele não esconde a sequência de criação. Se você expõe esses IDs publicamente em URLs, alguém pode inferir a ordem dos registros. Nesses casos, o UUIDv4 ainda faz mais sentido justamente por ser opaco e sem ordem.

Casos de uso reais

O UUIDv7 brilha em vários cenários do dia a dia de quem desenvolve sistemas.

  • APIs e microservicos: cada serviço gera seus próprios IDs sem coordenação, e mesmo assim os registros mantem ordem global de criação.
  • Sistemas de eventos e logs: ordenar eventos por id já entrega a linha do tempo, útil em filas e auditoria.
  • Bancos com tabelas enormes: equipes que migraram de UUIDv4 para v7 costumam relatar menos fragmentação de índice em tabelas que crescem rápido.
  • Aplicações offline-first: o cliente cria o id localmente e sincroniza depois, sem risco de colisão com o servidor.

Em todos esses casos, o ganho vem da combinação rara de unicidade global com ordem temporal, algo que nenhuma das alternativas entrega de forma tao direta.

Dicas e boas práticas

Quem já usa UUIDv7 em produção costuma seguir alguns cuidados que evitam dor de cabeça.

O primeiro e armazenar como tipo nativo. Em bancos que tem o tipo uuid, use a coluna uuid de verdade, e não um campo de texto. Guardar o UUID como string consome mais espaço e perde parte da otimização de índice. O segundo cuidado e não expor o id em contextos onde o horário de criação seja sensível; nesses pontos, prefira um identificador opaco separado.

O erro mais comum de iniciantes e tratar o UUIDv7 como aleatório puro e usa-lo como token de segurança ou senha de acesso. Ele não foi feito para isso: parte do seu valor e previsível por design. Para segredos, use geradores criptográficos específicos. Use o UUIDv7 para o que ele faz bem, que é ser uma chave primaria identificável e ordenada.

Vale a pena?

Para a maioria dos sistemas novos que usam UUID como chave primaria, a resposta e um sim convicto. O UUIDv7 entrega a mesma unicidade do UUIDv4 com um ganho real de performance e ordenação, e por ser padrão oficial tem suporte crescente em linguagens e bancos.

Ele não e bala de prata. Se a privacidade do horário de criação for crítica, ou se você precisa de IDs totalmente opacos em URLs públicas, o UUIDv4 continua sendo a escolha certa. A decisão final depende de pesar performance contra previsibilidade no seu contexto.

O próximo passo e simples e barato: em um projeto de teste, troque a geração de v4 por v7 na sua linguagem favorita, rode uma carga de inserções e compare. Ver o comportamento do índice com seus próprios olhos costuma ser o argumento que faltava para adotar de vez.