PostgreSQL JSONB vs colunas normais: quando convém cada opção

Publicado em 2026-10-26 por frfrand

Modelagem SQL e consultas a campos flexíveis sem perder desempenho

PostgreSQL JSONB vs colunas normais: quando convém cada opção

Em uma API é tentador salvar todo um objeto JSON em uma coluna e esquecer do esquema. PostgreSQL permite usar JSONB e é muito útil, mas quando cada consulta começa a filtrar dentro de documentos enormes talvez valha a pena repensar.

A ideia é resolver um problema de dados ou implantação que aparece em aplicações reais. Vamos ver o conceito sem rodeios, um exemplo de implementação e o que verificar antes de levá-lo para produção.

O que JSONB faz vs colunas normais

JSONB armazena documentos binários consultáveis e indexáveis, com operadores específicos. Colunas relacionais oferecem tipos, chaves e restrições mais diretas para dados que você sempre precisa filtrar, relacionar ou agregar. Não é uma escolha absoluta; podem coexistir.

Não basta repetir uma receita se você não entende quem lê os dados, de qual processo e com quais permissões. Em uma aplicação com reservas, faturas ou usuários, uma condição de corrida ou uma política de acesso mal feita pode ser mais grave que uma API lenta.

Um exemplo concreto

CREATE TABLE eventos (
  id bigserial PRIMARY KEY,
  cliente_id bigint NOT NULL,
  tipo text NOT NULL,
  metadata jsonb NOT NULL DEFAULT '{}'::jsonb
);
SELECT id, metadata->>'origen'
FROM eventos
WHERE tipo = 'reserva' AND metadata @> '{"origen":"web"}';
-- Evaluar índices según las consultas reales

Os nomes, tabelas e chaves deste exemplo são ilustrativos. Teste primeiro em um banco ou ambiente de homologação e adapte permissões, índices e versões. Quando houver operações de gravação, não execute consultas de amostra sobre dados de clientes sem revisar o que modificam.

Passo a passo

Identifique campos estáveis do negócio como cliente, data, valor e status.
Coloque esses campos em colunas tipadas quando precisar de restrições e junções.
Use JSONB para metadados flexíveis que mudam entre eventos.
Meça consultas reais com EXPLAIN e adicione índices adequados apenas quando ajudarem.
Documente o formato e as validações do JSON para não terminar com cem variantes incompatíveis.

No final, não fique com «o SQL não deu erro». Verifique o efeito real pela API e com testes de concorrência ou permissões, conforme o caso. Em bancos de dados, há erros que só aparecem quando dois usuários fazem algo ao mesmo tempo.

Exemplo de projeto de trabalho

Uma plataforma de reservas guarda cliente_id, horario_id e status como colunas e usa JSONB para atributos opcionais de origem de campanha ou preferências. Assim, não sacrifica a integridade das reservas pela flexibilidade.

Esse cenário ajuda a distinguir desempenho de consistência. Acelerar uma consulta não serve se permitir criar duas reservas para uma única vaga, nem um banco enorme resolve o fato de o backend permitir consultar dados de outro cliente.

O erro típico

JSONB não substitui automaticamente chaves estrangeiras e restrições sobre todo o documento. Tampouco todas as consultas com JSONB se tornam rápidas porque existe um índice GIN.

Também convém ter um plano de recuperação. Antes de tocar esquema, usuários ou políticas, guarde uma cópia verificável ou migração reversível e comprove que o aplicativo possa continuar funcionando durante a mudança.

Como resolveria com ArduMaker?

Quando administra PostgreSQL no ArduMaker, misturar tipos SQL e JSONB com critério permite adaptar o banco sem sacrificar consultas frequentes da API.

O ArduMaker permite implantar serviços a partir do Git e trabalhar com bancos e processos dentro do VPS. O painel não substitui a lógica do seu aplicativo: transações, permissões e validações devem permanecer corretamente projetadas no código e no banco de dados.

Três verificações antes de publicar

Integridade: se uma solicitação se repetir ou falhar no meio do caminho, os dados terminam em um estado válido?

Segurança: um usuário autenticado pode acessar apenas suas informações, e a API utiliza uma identidade de banco com permissões mínimas?

Recuperação: sabe restaurar os dados e reverter a versão de código compatível se uma atualização der errado?

Se puder responder a essas três perguntas com provas, seu backend está bastante mais preparado do que quando apenas olhou se o endpoint devolvia 200.

Recursos para aprofundar

Para encerrar: escolha a solução mais simples que permita manter dados corretos, seguros e recuperáveis. O desempenho vem depois de medir.