SQL Academy · Aula

Modelagem: quando JSONB supera a normalização

Decida entre uma coluna JSONB e uma tabela separada — atributos flexíveis ou esquemas rígidos.

Modelagem: quando JSONB supera a normalização é uma aula grátis de SQL Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de SQL Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de SQL Academy inclui 4 aulas no total.

A escolha

Para cada dado que você pode armazenar: coluna ou chave JSONB? A resposta orienta o projeto do esquema, o desempenho das consultas e a facilidade de manutenção.

Quando as colunas são melhores

Use colunas reais quando os dados forem:

Conhecidos e estáveis
Consultados com frequência usando índices
Validados por restrições CHECK ou FK
Usados em relatórios ou junções

Quando JSONB é melhor

Use JSONB quando:

A estrutura variar por linha (campos definidos pelo locatário, metadados de plug-ins)
O esquema evoluir rapidamente (para evitar migrações)
Leituras e escritas do documento inteiro forem a norma
For necessário armazenar cargas úteis opacas (corpos de webhooks)

O padrão híbrido

O melhor dos dois: colunas estruturadas para o núcleo estável e JSONB para a parte variável:

CREATE TABLE events (
  id BIGSERIAL PRIMARY KEY,
  ts TIMESTAMPTZ NOT NULL,
  event_type TEXT NOT NULL,
  user_id BIGINT,
  data JSONB NOT NULL DEFAULT '{}'::JSONB
);

Armadilha do EAV

O modelo clássico de "entidade-atributo-valor" — uma tabela com linhas de (chave, valor) — costumava ser a única opção para dados esparsos. JSONB substitui EAV por uma única coluna de documento:

-- Old EAV:
CREATE TABLE user_attrs (
  user_id BIGINT,
  attr TEXT,
  val TEXT
);

-- Modern:
ALTER TABLE users ADD COLUMN attrs JSONB NOT NULL DEFAULT '{}';

-- JSONB queries are faster and easier than the EAV joins.

Estratégia de migração

Adicionar uma coluna a uma tabela muito acessada → 5 minutos de indisponibilidade em uma tabela grande. Com JSONB, adicionar um campo é apenas uma alteração no código da aplicação.

Restrições em JSONB

Adicione restrições CHECK para impor uma estrutura mínima:

ALTER TABLE events
  ADD CONSTRAINT data_has_type CHECK (data ? 'type'),
  ADD CONSTRAINT type_is_string CHECK (jsonb_typeof(data->'type') = 'string');

Promova os campos mais acessados

Se um campo JSONB passar a ser consultado com frequência, promova-o para uma coluna real. Um script de UPDATE + um novo índice + uma nova coluna tornam o acesso rápido.

Operações de atualização do JSONB

Atualize um único campo:

UPDATE users
SET attrs = jsonb_set(attrs, '{plan}', '"pro"')
WHERE id = 1;

Não armazene dinheiro em JSONB

Valores financeiros precisam de tipos NUMERIC exatos e restrições. Use sempre colunas reais.

Quando JSONB prejudica o desempenho

Se você extrai e converte a mesma chave JSONB em todas as consultas, isso indica que ela deveria ser uma coluna. O custo acumulado de (data->>'k')::INT em milhões de linhas se torna significativo.

Documentação do esquema

Colunas JSONB são fáceis de escrever, mas difíceis de documentar. Mantenha um esquema externo (JSON Schema, código da aplicação) para que os colaboradores saibam o que esperar.

Recapitulação

JSONB é uma ferramenta poderosa — use-o para as partes variáveis e colunas reais para o núcleo estável. Promova os campos mais acessados quando surgirem padrões.

Verificação rápida

Você está armazenando eventos de auditoria. O tipo de evento está sempre presente; alguns eventos têm um vetor de "atores" cuja estrutura varia. Como você o modelaria?

Perguntas Frequentes

A aula “Modelagem: quando JSONB supera a normalização” é grátis?

Sim — o texto completo de “Modelagem: quando JSONB supera a normalização” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de SQL Academy, atualize para CoddyKit PRO. O curso de SQL Academy inclui 4 aulas no total.

O que vou aprender em “Modelagem: quando JSONB supera a normalização”?

Decida entre uma coluna JSONB e uma tabela separada — atributos flexíveis ou esquemas rígidos. Você pratica SQL Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar SQL Academy?

Nenhuma experiência prévia é necessária. SQL Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Modelagem: quando JSONB supera a normalização”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de SQL Academy?

Sim. Cada aula de SQL Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

JSONB vs JSON: quando usar cada um
Operadores de caminho: -> ->> @>
Indexação de JSONB com GIN
Modelagem: quando JSONB supera a normalização

← Voltar para SQL Academy