Design de Tabelas PostgreSQL

Use esta habilidade quando

• Projetando um schema para PostgreSQL
• Selecionando tipos de dados e restrições
• Planejando índices, partições ou políticas RLS
• Revisando tabelas para escalabilidade e manutenibilidade

Não use esta habilidade quando

• Você está visando um banco de dados não-PostgreSQL
• Você só precisa de otimização de consultas sem alterações de schema
• Você precisa de um guia de modelagem agnóstico de banco de dados

Instruções

1. Capture entidades, padrões de acesso e alvos de escala (linhas, QPS, retenção).
2. Escolha tipos de dados e restrições que imponham invariantes.
3. Adicione índices para caminhos de consulta reais e valide com EXPLAIN.
4. Planeje particionamento ou RLS onde exigido por escala ou controle de acesso.
5. Revise o impacto da migração e aplique alterações com segurança.

Segurança

• Evite DDL destrutivo em produção sem backups e um plano de reversão.
• Use migrações e validação em staging antes de aplicar alterações de schema.

Regras Principais

• Defina uma CHAVE PRIMÁRIA para tabelas de referência (usuários, pedidos, etc.). Nem sempre é necessária para dados de série temporal/evento/log. Quando usada, prefira BIGINT GENERATED ALWAYS AS IDENTITY; use UUID apenas quando a unicidade global/opacidade for necessária.
• Normalize primeiro (para 3NF) para eliminar redundância de dados e anomalias de atualização; desnormalize apenas para leituras medidas, de alto ROI, onde o desempenho de junções se provou problemático. A desnormalização prematura cria um fardo de manutenção.
• Adicione NOT NULL onde for semanticamente exigido; use DEFAULTs para valores comuns.
• Crie índices para caminhos de acesso que você realmente consulta: PK/único (automático), colunas FK (manual!), filtros/ordenações frequentes e chaves de junção.
• Prefira TIMESTAMPTZ para tempo de evento; NUMERIC para dinheiro; TEXT para strings; BIGINT para valores inteiros, DOUBLE PRECISION para floats (ou NUMERIC para aritmética decimal exata).

“Armadilhas” do PostgreSQL

• Identificadores: sem aspas → minúsculas. Evite nomes entre aspas/com maiúsculas e minúsculas. Convenção: use snake_case para nomes de tabelas/colunas.
• Unique + NULLs: UNIQUE permite múltiplos NULLs. Use UNIQUE (...) NULLS NOT DISTINCT (PG15+) para restringir a um NULL.
• Índices FK: O PostgreSQL não indexa automaticamente colunas FK. Adicione-os.
• Sem coerções silenciosas: estouros de comprimento/precisão geram erros (sem truncamento). Exemplo: inserir 999 em NUMERIC(2,0) falha com erro, ao contrário de alguns bancos de dados que truncam ou arredondam silenciosamente.
• Sequências/identidade têm lacunas (normal; não "corrija"). Rollbacks, falhas e transações concorrentes criam lacunas nas sequências de ID (1, 2, 5, 6...). Este é um comportamento esperado — não tente tornar os IDs consecutivos.
• Armazenamento Heap: sem PK clusterizada por padrão (ao contrário de SQL Server/MySQL InnoDB); CLUSTER é uma reorganização única, não mantida em inserções subsequentes. A ordem das linhas no disco é a ordem de inserção, a menos que explicitamente clusterizada.
• MVCC: atualizações/exclusões deixam tuplas mortas; o vacuum as gerencia — projete para evitar churn de linhas largas e quentes.

Tipos de Dados

• IDs: BIGINT GENERATED ALWAYS AS IDENTITY preferível (GENERATED BY DEFAULT também é bom); UUID ao mesclar/federar/usar em um sistema distribuído ou para IDs opacos. Gere com uuidv7() (preferível se usar PG18+) ou gen_random_uuid() (se usar uma versão mais antiga do PG).
• Inteiros: prefira BIGINT a menos que o espaço de armazenamento seja crítico; INTEGER para intervalos menores; evite SMALLINT a menos que seja restrito.
• Floats: prefira DOUBLE PRECISION a REAL a menos que o espaço de armazenamento seja crítico. Use NUMERIC para aritmética decimal exata.
• Strings: prefira TEXT; se limites de comprimento forem necessários, use CHECK (LENGTH(col) <= n) em vez de VARCHAR(n); evite CHAR(n). Use BYTEA para dados binários. Strings/binários grandes (> 2KB de limite padrão) são armazenados automaticamente em TOAST com compressão. Armazenamento TOAST: PLAIN (sem TOAST), EXTENDED (comprimir + fora de linha), EXTERNAL (fora de linha, sem compressão), MAIN (comprimir, manter em linha se possível). O padrão EXTENDED geralmente é ótimo. Controle com ALTER TABLE tbl ALTER COLUMN col SET STORAGE strategy e ALTER TABLE tbl SET (toast_tuple_target = 4096) para o limite. Insensível a maiúsculas/minúsculas: para tratamento de localidade/acentos, use collations não determinísticas; para ASCII puro, use índices de expressão em LOWER(col) (preferível, a menos que a coluna precise de PK/FK/UNIQUE insensível a maiúsculas/minúsculas) ou CITEXT.
• Dinheiro: NUMERIC(p,s) (nunca float).

…