Design de Tabelas PostgreSQL

Quando Usar

• Ao projetar um novo esquema PostgreSQL, ou ao revisar um antes que ele seja implementado.
• Ao escolher tipos de coluna, chaves, restrições ou índices especificamente para PostgreSQL.
• Ao decidir se e como particionar uma tabela grande, ou como armazenar dados semiestruturados.
• Ao planejar uma alteração de esquema em um banco de dados ativo sem tempo de inatividade.

As regras e pontos de decisão para um esquema PostgreSQL. O catálogo completo de tipos de dados, padrões de carga de trabalho (com muitas atualizações, muitas inserções, upsert, evolução de esquema), extensões, indexação JSONB e exemplos de DDL trabalhados estão em references/details.md; abra-o quando uma seção abaixo apontar para lá.

Regras Principais

• Defina uma CHAVE PRIMÁRIA para tabelas de referência (usuários, pedidos, etc.). Nem sempre é necessária para dados de séries temporais/eventos/logs. Quando usada, prefira BIGINT GENERATED ALWAYS AS IDENTITY; use UUID apenas quando a unicidade global/opacidade for necessária.
• Normalize primeiro (para 3FN) para eliminar redundância de dados e anomalias de atualização; desnormalize apenas para leituras medidas, de alto ROI, onde o desempenho de junção se provou problemático.
• 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 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 misturadas; use snake_case.
• Único + 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 erro (sem truncamento). Inserir 999 em NUMERIC(2,0) falha, ao contrário de bancos de dados que truncam ou arredondam silenciosamente.
• Sequências/identidade têm lacunas (normal; não "consertar"). Rollbacks, falhas e transações concorrentes deixam lacunas (1, 2, 5, 6...).
• Armazenamento Heap: sem PK clusterizado por padrão; CLUSTER é uma reorganização única, não mantida em inserções posteriores.
• MVCC: atualizações/exclusões deixam tuplas mortas; o vacuum cuida delas — projete para evitar churn de linha larga quente.

Tipos de Dados

• IDs: BIGINT GENERATED ALWAYS AS IDENTITY; UUID para IDs distribuídos ou opacos, gerados com uuidv7() (PG18+) ou gen_random_uuid().
• Números: BIGINT, a menos que o armazenamento seja crítico; DOUBLE PRECISION em vez de REAL; NUMERIC(p,s) para dinheiro e decimais exatos.
• Strings: TEXT, com CHECK (LENGTH(col) <= n) quando um limite é necessário; BYTEA para binários. Consultas insensíveis a maiúsculas/minúsculas: índice de expressão em LOWER(col), ou CITEXT quando uma restrição deve ser insensível a maiúsculas/minúsculas.
• Tempo: TIMESTAMPTZ, DATE, INTERVAL. now() é o início da transação; clock_timestamp() é o relógio de parede.
• Booleanos: BOOLEAN NOT NULL, a menos que seja necessário um tri-estado.
• Enums: CREATE TYPE ... AS ENUM apenas para conjuntos pequenos e estáveis; valores de negócios em evolução recebem TEXT + CHECK ou uma tabela de consulta.
• JSONB em vez de JSON, indexado com GIN, apenas para atributos opcionais/semiestruturados.
• Tipos de array, intervalo, rede, geométricos, full-text, domínio, composto e vetor, além de armazenamento TOAST e controle de collation: veja references/details.md.

Tipos a evitar

Restrições

• PK: UNIQUE + NOT NULL implícito; cria um índice B-tree.
• FK: especifique ON DELETE/UPDATE (CASCADE, RESTRICT, SET NULL, SET DEFAULT). Indexe a coluna referenciadora. Use DEFERRABLE INITIALLY DEFERRED para dependências circulares verificadas no commit.
• UNIQUE: cria um índice B-tree; permite múltiplos NULLs, a menos que NULLS NOT DISTINCT (PG15+). Prefira NULLS NOT DISTINCT, a menos que NULLs duplicados sejam desejados.
• CHECK: local da linha; NULL passa (lógica de três valores). Combine com NOT NULL: price NUMERIC NOT NULL CHECK (price > 0).
• EXCLUDE: impede sobreposições com operadores, por exemplo, EXCLUDE USING gist (room_id WITH =, booking_period WITH &&) impede reservas duplas. Requer um tipo compatível com GiST.

Indexação

…