Gerador CUID

O que é CUID?

CUID (Identificador Único Resistente a Colisões) é um algoritmo de código aberto para gerar IDs únicos que funcionam bem em sistemas distribuídos sem um coordenador central. Ao contrário de um UUID simples, um CUID é projetado para ser horizontalmente escalável — múltiplos servidores ou abas do navegador podem gerar IDs de forma independente com risco mínimo de colisão.

Todo CUID começa com a letra minúscula c, tornando o formato imediatamente reconhecível de relance. Os caracteres restantes são todos alfanuméricos em minúsculas (base36), portanto um CUID é seguro para URLs e pode ser usado diretamente como segmento de caminho URL ou chave primária de banco de dados sem codificação adicional.

A especificação original do CUID (v1) foi criada por Eric Elliott e popularizada através do pacote npm cuid. Agora foi substituída pelo CUID v2, que fornece segurança criptográfica. Esta página — e o gerador acima — produz IDs CUID v1, o formato clássico ainda amplamente encontrado em bases de código em produção.

Estrutura do CUID

Um CUID v1 tem aproximadamente 25 caracteres de comprimento e é composto por cinco segmentos concatenados, cada um carregando um tipo diferente de entropia:

Os segmentos são simplesmente concatenados — não há separadores. O comprimento total varia ligeiramente dependendo do valor atual do timestamp, mas permanece em aproximadamente 25 caracteres.

Como o CUID Previne Colisões

A resistência a colisões vem de superpor fontes independentes de entropia de modo que mesmo em cenários de pior caso (milhares de IDs gerados por milissegundo em muitas máquinas) a probabilidade de dois IDs idênticos permaneça extremamente pequena.

CUID vs UUID v4

Tanto o CUID quanto o UUID v4 são amplamente usados para geração de IDs no lado do cliente. Eles adotam abordagens diferentes para o mesmo problema:

UUID v4 é a escolha mais segura para cenários sensíveis à segurança porque não revela informações de tempo. CUID tem a vantagem quando você quer IDs vagamente ordenáveis, mais curtos e sem hífens — útil para uso em URLs, nomes de arquivo ou logs onde você quer identificar rapidamente quando um registro foi criado.

CUID v1 vs CUID2

A especificação CUID foi revisada significativamente. Entender as diferenças ajuda a escolher a versão certa para o seu projeto:

Para novos projetos, CUID v2 é a escolha recomendada. Sua construção baseada em SHA-3 significa que a saída é opaca — nenhum timestamp, contador ou impressão digital pode ser engenharia reversa do ID. Use CUID v1 apenas quando precisar de compatibilidade retroativa com um conjunto de dados existente ou quiser uma implementação sem dependências.

Casos de Uso

Exemplos de Código

Instale o pacote oficial CUID v2 (recomendado) ou escreva uma implementação mínima de v1 sem dependências:

// npm install @paralleldrive/cuid2  (recommended — CUID v2)
import { createId } from '@paralleldrive/cuid2'

const id = createId()
// → 'tz4a98xxat96iws9zmbrgj3a'

// Custom length
import { init } from '@paralleldrive/cuid2'
const createShortId = init({ length: 10 })
createShortId() // → 'zxp1l6mf4c'

Se preferir uma implementação Node.js sem dependências do algoritmo v1:

// Pure Node.js — CUID v1 style (no dependencies)
let counter = 0

function pad(str, size) {
  return str.padStart(size, '0').slice(-size)
}

function fingerprint() {
  const os = require('os')
  const source = [process.pid, os.hostname().length].join('')
  let hash = 0
  for (const c of source) {
    hash = ((hash << 5) - hash) + c.charCodeAt(0)
    hash |= 0
  }
  return pad(Math.abs(hash).toString(36), 4)
}

function cuid() {
  const timestamp = Date.now().toString(36)
  const cnt       = pad((counter++ & 0xffff).toString(36), 4)
  const fp        = fingerprint()
  const rnd       = pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
              + pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
  return 'c' + timestamp + cnt + fp + rnd
}

console.log(cuid()) // → 'clrc4gkwz001ag2hs3k7f9m2q'

Usando CUID como chave primária de banco de dados com Prisma e PostgreSQL:

-- Use CUID as a primary key in PostgreSQL
CREATE TABLE users (
  id   TEXT        PRIMARY KEY DEFAULT gen_cuid(),
  name TEXT        NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Prisma schema (auto-generates CUID by default)
model User {
  id        String   @id @default(cuid())
  name      String
  createdAt DateTime @default(now())
}

Perguntas Frequentes