UUID: o que é, formato, versões e chance de colisão
UUID, o que é: o formato de 128 bits, como ler versão e variante, v4 ou v7 em chaves de banco, a chance real de colisão e código em JS, Python e SQL.
Um UUID (universally unique identifier, ou identificador único universal) é um número de 128 bits usado para rotular alguma coisa, como uma linha de banco de dados ou um arquivo, de modo que dois rótulos não se choquem, sem que nenhuma autoridade central precise distribuí-los. Ele é escrito como 32 dígitos hexadecimais em cinco grupos separados por hífens, como f81d4fae-7dec-11d0-a765-00a0c91e6bf6. Resumindo: um número enorme que qualquer um pode gerar e esperar que seja único.
O padrão atual é a RFC 9562, publicada em maio de 2024. Ela substituiu a RFC 4122, manteve as versões antigas e acrescentou três novas (6, 7 e 8). Também confirma que GUID, o nome usado nos produtos da Microsoft, se refere à mesma coisa.
Como um UUID é organizado
A forma em texto tem sempre 36 caracteres: 32 dígitos hexadecimais mais 4 hífens, agrupados em 8-4-4-4-12. Cada dígito hexadecimal carrega 4 bits, então 32 dígitos somam 128 bits, ou 16 bytes. Maiúsculas e minúsculas são igualmente válidas.
A maior parte desses bits muda de acordo com a versão, mas dois campos pequenos ficam no mesmo lugar em todo UUID padrão:
- A versão é o 13º dígito hexadecimal, o primeiro do terceiro grupo. Ela diz como o UUID foi gerado.
- A variante é o 17º dígito hexadecimal, o primeiro do quarto grupo. Nos UUIDs que seguem a RFC 9562 ele é sempre 8, 9, a ou b, porque os dois bits mais altos são fixos em binário 10.
Veja o exemplo da documentação do PostgreSQL, 019535d9-3df7-79fb-b466-fa907fa17f9e. O terceiro grupo começa com 7, então é um UUID versão 7. O quarto grupo começa com b, que é a variante padrão. E como a versão 7 coloca um timestamp Unix nos primeiros 48 bits, dá para decodificar os 12 primeiros dígitos hexadecimais (019535d93df7) como 1.740.365.184.503 milissegundos, que correspondem a 02:46:24,503 UTC de 24 de fevereiro de 2025. O exemplo do início desta página tem um 1 na posição da versão e um a na posição da variante, então é um UUID versão 1.
Como a versão e a variante ocupam 6 bits, um UUID aleatório fica com 122 bits para a aleatoriedade.
As versões de UUID e para que serve cada uma
A RFC 9562 define oito versões. As que você mais vai encontrar são a v4 e a v7, a v1 em sistemas antigos, e as outras só de vez em quando.
| Versão | Como é gerado | Uso típico |
|---|---|---|
| 1 | Timestamp de 60 bits contado em passos de 100 nanossegundos desde 1582, mais uma sequência de relógio e um ID de nó de 48 bits (muitas vezes o endereço MAC) | Sistemas legados |
| 2 | Reservada para o DCE Security; não detalhada na RFC | Rara |
| 3 | Hash MD5 de um namespace e um nome | A mesma entrada sempre dá o mesmo UUID |
| 4 | 122 bits aleatórios | IDs de uso geral |
| 5 | Hash SHA-1 de um namespace e um nome | Como a v3, e preferível a ela |
| 6 | Os campos da versão 1 reordenados para ordenar por tempo | Sistemas que já usam v1 |
| 7 | Timestamp Unix de 48 bits em milissegundos, seguido de bits aleatórios | Chaves de banco de dados e tudo que deva ser ordenado pela data de criação |
| 8 | Layout personalizado; só a versão e a variante são fixas | Formatos proprietários ou experimentais |
Existem ainda dois valores especiais: o Nil UUID, todo em zeros, e o Max UUID, todo em uns (todos os dígitos hexadecimais são f). Eles são úteis como marcadores de “sem valor” ou “limite superior”.
A RFC é direta sobre a versão 1. Endereços MAC trazem problemas de privacidade, e o padrão diz que as implementações devem usar a versão 7 no lugar da 1 ou da 6 sempre que puderem.
Qual é a chance de um UUID repetido?
Um UUID versão 4 tem 122 bits aleatórios, o que dá 2¹²² valores possíveis, cerca de 5,3 × 10³⁶. As duplicatas seguem o paradoxo do aniversário: a chance de colisão cresce com o quadrado da quantidade gerada, então sobe mais rápido do que se espera, mas a partir de uma base minúscula.
Usando a aproximação padrão, p ≈ 1 − exp(−n²/2N) com N = 2¹²², seriam necessários cerca de 2,71 × 10¹⁸ UUIDs (2,7 quintilhões) para ter 50% de chance de uma única repetição. Gerando um bilhão por segundo, isso leva uns 86 anos.
| UUIDs gerados | Chance de pelo menos uma repetição |
|---|---|
| 1 milhão | cerca de 1 em 10²⁵ (9,4 × 10⁻²⁶) |
| 1 bilhão | 9,4 × 10⁻²⁰ |
| 1 trilhão | 9,4 × 10⁻¹⁴ |
| 1 quatrilhão | 9,4 × 10⁻⁸ |
| 2,71 × 10¹⁸ | 50% |
A conta parte de uma boa fonte de aleatoriedade. Duplicatas reais vêm de geradores fracos ou mal inicializados, ou de alguém colando o mesmo ID em dois lugares. Colisões aleatórias não merecem preocupação; bugs merecem, e é por isso que uma restrição de unicidade na coluna continua sendo uma boa ideia.
Único não é o mesmo que secreto. A RFC 9562 diz que não se deve presumir que UUIDs são difíceis de adivinhar e que eles não podem ser usados como credenciais de segurança. Para um link de redefinição de senha ou uma chave de API, use um token aleatório próprio para isso; o gerador de senhas é um ponto de partida melhor para qualquer coisa que precise continuar privada.
UUID v4 ou v7 em chaves de banco de dados
Esta é a decisão que importa na prática. Os dois têm 128 bits e, na prática, os dois estão a salvo de colisões. A diferença é a ordem.
Chaves v4 aleatórias caem em pontos aleatórios de um índice B-tree, então cada inserção pode mexer numa página diferente. A RFC 9562 diz que o custo de desempenho disso em B-trees “pode ser dramático” e que valores ordenados por tempo podem fazer uma diferença de uma ordem de grandeza ou mais. A versão 7 começa com o timestamp, então chaves criadas em sequência ficam lado a lado e se ordenam corretamente tanto como bytes quanto como texto.
Minha opinião: use v7 nas chaves primárias de tabelas novas. Escolha v4 quando o ID for público e você não quiser que ele revele quando o registro foi criado, porque qualquer pessoa consegue ler o timestamp de um UUID v7, como o exemplo acima mostrou. Seja qual for a escolha, guarde o valor numa coluna UUID nativa ou binária de 16 bytes, e não como texto. A RFC lembra que a forma em texto ocupa 288 bits para guardar um valor de 128 bits.
Como gerar um UUID em JavaScript, Python e PostgreSQL
JavaScript
No navegador, crypto.randomUUID() devolve uma string de versão 4 com 36 caracteres, vinda de um gerador criptograficamente seguro. O MDN observa que ela só funciona em contextos seguros (HTTPS ou localhost). O Node.js tem a mesma função no módulo crypto desde as versões 14.17.0 e 15.6.0, e a documentação do Node.js lista crypto.randomUUIDv7() a partir da versão 26.1.0.
const id = crypto.randomUUID();
Python
O módulo uuid da biblioteca padrão tem uuid.uuid4() para UUIDs aleatórios. O Python 3.14 acrescentou uuid.uuid7(), que embute um timestamp de 48 bits e usa um contador para manter os IDs em ordem dentro do mesmo milissegundo. Dá para conferir a versão de qualquer UUID com o atributo .version.
import uuid; uuid.uuid4(); uuid.uuid7()
PostgreSQL
gen_random_uuid() vem embutida desde o PostgreSQL 13 e devolve um UUID versão 4. O PostgreSQL 18 acrescentou uuidv4(), um apelido para a mesma coisa, e uuidv7() para chaves ordenadas por tempo.
CREATE TABLE orders (id uuid PRIMARY KEY DEFAULT uuidv7());
Gere UUIDs sem escrever código
Se você só precisa de alguns IDs para dados de teste, um arquivo de configuração ou um ajuste rápido, o gerador de UUID cria até 1.000 de uma vez, como v4 aleatórios ou v7 ordenados por tempo, com ou sem hífens e em maiúsculas ou minúsculas. Ele usa o gerador aleatório seguro do seu navegador, nada é enviado para servidor e é grátis, sem cadastro. Antes de colar um lote num script de seed, confira o 13º caractere: se você pediu v7 e vê um 4, gerou UUIDs versão 4 por engano.
Trabalhando com IDs dentro de JSON? O formatador de JSON deixa payloads longos cheios de UUIDs muito mais fáceis de ler.
Também pode ajudar: Gerador de hash · Codificar e decodificar Base64 · URL encode e decode
Perguntas frequentes
GUID é a mesma coisa que UUID?
É. GUID (globally unique identifier) é o nome usado pela Microsoft, e a RFC 9562 trata os dois termos como a mesma coisa: um valor de 128 bits escrito como 32 dígitos hexadecimais. Uma diferença que vale saber: o COM da Microsoft grava alguns campos em ordem de bytes little-endian quando salva GUIDs em binário.
Dois UUIDs podem ser iguais?
Em teoria, sim. Um UUID versão 4 tem 122 bits aleatórios, então seriam necessários cerca de 2,7 quintilhões deles para ter 50% de chance de uma única repetição. Na prática, duplicatas vêm de geradores de números aleatórios com defeito ou de código copiado, não de azar.
Como sei qual é a versão de um UUID?
Olhe o primeiro dígito do terceiro grupo, o 13º dígito hexadecimal. Um 4 indica aleatório, um 7 indica ordenado por tempo e um 1 indica o formato antigo com hora e endereço MAC. O primeiro dígito do quarto grupo deve ser 8, 9, a ou b num UUID padrão.
Devo usar UUID v4 ou v7 como chave primária?
Em tabelas novas, o v7 costuma ser a melhor escolha. Ele começa com um timestamp em milissegundos, então as chaves novas ficam agrupadas e as inserções no índice continuam eficientes. Use o v4 quando não quiser que o ID revele quando o registro foi criado.
UUIDs são seguros o bastante para usar como token secreto?
Não. A RFC 9562 diz que as implementações não devem presumir que UUIDs são difíceis de adivinhar e não podem usá-los como credenciais de segurança, ou seja, identificadores cuja simples posse dá acesso. Para links de redefinição de senha ou chaves de API, use um token aleatório feito para isso.