UUID v4 ou v7: qual é a diferença?

A resposta curta

Escolha o UUID v7 para novas chaves de banco de dados, IDs de eventos, registros de log e nomes de arquivo que você quer em ordem cronológica. Os valores v7 novos são sempre maiores que os antigos, então entram no fim do índice como um número auto incremento, e mesmo assim você pode gerá-los em qualquer servidor ou no navegador sem pedir nada ao banco de dados.

Escolha o UUID v4 para tokens, identificadores públicos em que a data de criação é privada e sistemas que já usam essa versão. Um valor v4 não revela nada e, para a maioria das aplicações que não guardam milhões de linhas, a ordem aleatória custa pouco. As duas versões estão definidas na RFC 9562, publicada em 2024, que substituiu a antiga RFC 4122 e acrescentou as versões 6, 7 e 8.

Como um UUID é formado

Todo UUID tem 128 bits, escritos como 32 dígitos hexadecimais em cinco grupos: 8-4-4-4-12, num total de 36 caracteres contando os hífens. Dois campos são fixos em todo UUID moderno. O primeiro dígito do terceiro grupo é a versão, então dá para ler de relance: 4 para aleatório, 7 para tempo Unix. O primeiro dígito do quarto grupo é a variante e é sempre 8, 9, a ou b nos UUIDs padrão.

Exemplo de v4: 9b2f4c1e-3a7d-4e8b-a5c2-0f6d1e9a3b47. Exemplo de v7: 019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b. No exemplo v7, os primeiros 12 dígitos hexadecimais (019a2b3c4d5e) são o momento de criação em milissegundos, e é por isso que IDs gerados com um segundo de diferença compartilham quase todo o começo.

Por que o v7 é mais rápido como chave primária

A maioria dos bancos de dados guarda a chave primária em um índice B-tree, ordenado pela chave. Com chaves v4 aleatórias, cada inserção cai em um ponto qualquer dessa árvore. Quando o índice fica maior que a memória, as inserções passam a ler páginas antigas do disco, as páginas se dividem pela metade e o índice cresce mais do que precisa. No InnoDB (MySQL e MariaDB) a própria tabela é gravada na ordem da chave primária, então a tabela inteira sofre, não só o índice.

Com chaves v7, as linhas novas vão para a borda direita do índice, as páginas mais usadas ficam na memória e as páginas são preenchidas por completo. Benchmarks de fabricantes de bancos de dados e de usuários costumam mostrar inserções bem mais rápidas e índices menores do que com o v4 em tabelas grandes, embora o ganho exato dependa do motor, do tamanho da linha e do hardware. Consultas por intervalo, como os 100 pedidos mais recentes, também ficam mais baratas, porque as linhas recentes ficam lado a lado.

Guarde os UUIDs em um tipo nativo de 16 bytes quando ele existir (uuid no PostgreSQL, BINARY(16) no MySQL, uniqueidentifier no SQL Server), e não como texto de 36 caracteres. Chaves em texto ocupam mais que o dobro e são mais lentas para comparar.

Notas por banco de dados: PostgreSQL, MySQL, SQL Server, .NET

• PostgreSQL: o tipo uuid ordena byte a byte, então a ordem do v7 é mantida. O PostgreSQL 18 trouxe a função nativa uuidv7(); nas versões anteriores o valor pode vir da aplicação.
• MySQL e MariaDB: guarde como BINARY(16) com UUID_TO_BIN(valor) sem a flag de troca, o que mantém a ordem do v7. A função UUID() do próprio MySQL cria a versão 1, não a v7.
• SQL Server: o uniqueidentifier compara primeiro o último grupo de bytes, então lá os valores v7 não ficam gravados em ordem de tempo. Se você precisa de chaves sequenciais no SQL Server, NEWSEQUENTIALID() ou uma coluna bigint identity costumam ser a opção mais simples.
• .NET: Guid.NewGuid() devolve v4. Desde o .NET 9, Guid.CreateVersion7() devolve v7.
• JavaScript: crypto.randomUUID() nos navegadores e no Node.js devolve v4; para o v7 é preciso uma biblioteca ou uma pequena função, como a que está por trás do gerador desta página.

Chance de colisão em números reais

Com 122 bits aleatórios, uma colisão de v4 é um problema do aniversário. Você precisaria de cerca de 2,7 quintilhões (2,7 x 10^18) de UUIDs para ter 50 por cento de chance de uma única repetição, o que equivale a um bilhão de IDs novos por segundo durante uns 86 anos. Geradores aleatórios com defeito, snapshots de máquinas virtuais copiados e bugs que reaproveitam um valor são causas de duplicidade muito mais realistas do que o acaso.

Um valor v7 tem menos bits aleatórios, mas eles só precisam ser únicos dentro do mesmo milissegundo. Mesmo um serviço que gera um milhão de IDs em um milissegundo não corre nenhum risco prático. Os geradores também mantêm um contador dentro do milissegundo, como este faz, então IDs criados em um lote rápido continuam em ordem estrita.

Mesmo assim, mantenha sempre uma restrição de unicidade (unique) na coluna. Não custa nada e transforma um evento impossível em um erro claro em vez de dados corrompidos.

UUID ou GUID, e as outras versões

GUID (identificador global único) é o nome que a Microsoft dá ao UUID. É o mesmo valor de 128 bits; as ferramentas do Windows costumam escrevê-lo em maiúsculas e às vezes entre chaves, como {3F2504E0-4F89-41D3-9A0C-0305E82C3301}. As opções de formato do gerador (Maiúsculas, Hífens, Chaves { }) cobrem esses estilos.

A versão 1 combina um timestamp com o endereço da placa de rede e hoje raramente é recomendada, porque pode identificar a máquina. A versão 6 é a versão 1 reorganizada para ordenar por tempo. As versões 3 e 5 são derivadas de um nome com MD5 ou SHA-1, então a mesma entrada sempre gera o mesmo UUID. A versão 8 é livre para formatos personalizados. O ULID é um formato popular fora do padrão UUID com a mesma ideia do v7, mas o v7 cabe em qualquer coluna uuid existente.

Quando o v7 é a escolha errada

• IDs públicos em que a data de criação é sensível: um v7 em uma URL revela quando uma conta, um pedido ou um documento foi criado.
• Tokens, links de convite e códigos de redefinição de senha: use v4 ou um token aleatório mais longo, nunca algo que dê para adivinhar pelo horário.
• Sistemas que ordenam ou comparam IDs como texto ou com outra ordem de bytes, como o uniqueidentifier do SQL Server.
• Tabelas existentes cheias de chaves v4: misturar versões funciona, mas você só ganha o benefício no índice para as linhas novas.