O que é um UUID?
UUID (Universally Unique Identifier), também chamado de GUID, é um identificador de 128 bits projetado para ser único sem precisar de um servidor central que coordene a numeração. Por isso é tão usado como chave primária em bancos de dados, ID de objetos em APIs, nomes de arquivos e rastreamento de eventos — dois sistemas podem gerar IDs ao mesmo tempo, offline, com chance praticamente nula de colisão.
O v4 é totalmente aleatório (122 bits de entropia) e é o padrão para a maioria dos casos. O v7 é mais novo: começa com um carimbo de tempo em milissegundos, então os IDs gerados ficam ordenados cronologicamente — ótimo para chaves de banco, porque melhora a localidade de índice (ao contrário do v4, que espalha as inserções). Aqui a geração usa crypto.getRandomValues, o gerador criptográfico do navegador.
Anatomia de um UUID
Um UUID tem 32 dígitos hexadecimais divididos em 5 grupos no formato 8-4-4-4-12. Dois desses dígitos não são aleatórios: eles identificam a versão e a variante do identificador.
O primeiro dígito do terceiro grupo indica a versão; o primeiro dígito do quarto grupo indica a variante (no padrão atual, sempre 8, 9, a ou b). Os demais dígitos são aleatórios — ou, no v7, os primeiros carregam o carimbo de tempo.
Versões de UUID
| Versão | Base | Ordenável? | Quando usar |
|---|---|---|---|
| v1 | Tempo + endereço MAC | Parcial | Legado. Pode vazar o MAC e o horário da máquina. |
| v3 / v5 | Hash de um nome (MD5 / SHA-1) | Não | Quando o mesmo nome deve gerar sempre o mesmo UUID (determinístico). |
| v4 | Aleatório (122 bits) | Não | Padrão geral: IDs de API, tokens, registros, arquivos. |
| v7 | Tempo (ms) + aleatório | Sim | Chave primária de banco — ordenação cronológica e melhor índice. |
Onde usar UUID
- Chaves primárias em bancos distribuídos, sem depender de um
AUTO_INCREMENTcentral. - IDs em APIs REST e mensagens, evitando expor a sequência de registros.
- Idempotência: um request ID único para não processar a mesma operação duas vezes.
- Nomes de arquivos e objetos em storage (S3, etc.) sem risco de colisão.
- Correlação de logs e tracing entre microsserviços.
Como gerar UUID em código
PostgreSQL
-- v4 nativo (sem extensão, Postgres 13+)
SELECT gen_random_uuid();MySQL
-- v1 (string) e armazenamento compacto em BINARY(16)
SELECT UUID();
SELECT UUID_TO_BIN(UUID(), 1);JavaScript (navegador / Node 19+)
const id = crypto.randomUUID(); // UUID v4Python
import uuid
uuid.uuid4() # v4 aleatórioLinha de comando (Linux/macOS)
uuidgen # macOS / util-linux
cat /proc/sys/kernel/random/uuid # LinuxPerguntas frequentes
UUID v4 ou v7, qual usar?
Para a maioria dos casos, use v4 (totalmente aleatório). Se o UUID for chave primária de banco de dados e você quiser inserções ordenadas por tempo — o que melhora a localidade de índice e o desempenho de escrita — prefira v7, que começa com um carimbo de tempo e é ordenável cronologicamente.
Qual a diferença entre UUID e GUID?
Nenhuma na prática. GUID (Globally Unique Identifier) é o nome que a Microsoft usa para o mesmo identificador de 128 bits definido pelo padrão UUID (RFC 4122/9562). São intercambiáveis; a diferença costuma ser só de formatação (a Microsoft às vezes usa maiúsculas e chaves: {ABC...}).
Posso usar UUID como chave primária no MySQL ou PostgreSQL?
Sim. No PostgreSQL use o tipo nativo uuid (gere com gen_random_uuid() para v4). No MySQL, armazene como CHAR(36) ou, para economizar espaço e melhorar o índice, BINARY(16) com UUID_TO_BIN(). Para chaves primárias com muitas inserções, o v7 (ordenável) tende a fragmentar menos o índice que o v4.
Qual a chance de dois UUIDs serem iguais?
Desprezível. O v4 tem 122 bits aleatórios — seria preciso gerar bilhões de UUIDs por segundo durante décadas para ter uma chance real de colisão. Por isso é seguro gerar IDs de forma distribuída, offline e sem coordenação central.
A geração é segura e aleatória de verdade?
Sim. Usamos crypto.getRandomValues, o gerador de números aleatórios criptográfico do navegador, em vez de Math.random (que não é adequado para fins de segurança).
Os UUIDs gerados são enviados para vocês?
Não. Tudo é gerado localmente no seu navegador, em JavaScript. Nenhum UUID trafega pela rede nem é armazenado em nossos servidores.