Regras de Nomenclatura e Estilo

Nomenclatura SQL consistente reduz a carga cognitiva entre migrações, ORMs, ferramentas de BI e sessões de grep de plantão. Escolha convenções uma vez, documente em um ADR, aplique na revisão.

Receita

-- Convenções preferenciais (exemplo de ADR da equipe)
CREATE SCHEMA app;
 
CREATE TABLE app.order (          -- escolha singular de tabela no ADR
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id bigint NOT NULL REFERENCES app.customer (id),
  placed_at timestamptz NOT NULL DEFAULT now(),
  status text NOT NULL CHECK (status IN ('open', 'shipped', 'cancelled'))
);
 
CREATE INDEX idx_order_customer_placed
  ON app.order (customer_id, placed_at DESC);

Quando usar isso: Inicialização de novo serviço, configuração de linter (SQLFluff) ou refatoração de esquemas legados em camelCase.

Exemplo de Trabalho

-- Nomenclatura de restrições (constraints)
ALTER TABLE app.order
  ADD CONSTRAINT fk_order_customer
  FOREIGN KEY (customer_id) REFERENCES app.customer (id);
 
ALTER TABLE app.order
  ADD CONSTRAINT ck_order_status
  CHECK (status IN ('open', 'shipped', 'cancelled'));
 
-- Nomenclatura de views
CREATE VIEW app.v_order_summary AS
SELECT customer_id, count(*) AS order_count
FROM app.order
GROUP BY customer_id;

Trecho do guia de estilo:

Aprofundamento

Tabelas Singulares vs. Plurais

Singular (order, customer):

• Alinha-se com a classe de entidade ORM Order
• FK lê naturalmente: order.customer_id

Plural (orders, customers):

• Corresponde ao SQL falado ("select from orders")
• Popular em ecossistemas Rails

Regra: Qualquer um é válido - nunca misture em um banco de dados. Legado existente escolhe o ADR; equipes novas escolhem e documentam.

snake_case em Tudo

-- Evitar
CREATE TABLE app.OrderItems (orderItemId bigint);
 
-- Preferir
CREATE TABLE app.order_item (order_item_id bigint);  -- se ADR singular

• O PostgreSQL converte identificadores não citados para minúsculas - citar "camelCase" é uma armadilha permanente.
• snake_case funciona sem identificadores citados em todos os clientes.

Colunas de Timestamp e Dinheiro

placed_at timestamptz NOT NULL   -- instantes
amount_cents bigint NOT NULL     -- dinheiro como unidades monetárias menores inteiras
currency_code char(3) NOT NULL   -- ISO 4217

• Nunca timestamp without time zone para eventos do mundo real.
• amount_cents é melhor que float para dinheiro.

Documentação com Comentários

COMMENT ON TABLE app.order IS 'Cabeçalho de compra do cliente; escopo de tenant via RLS';
COMMENT ON COLUMN app.order.status IS 'open|shipped|cancelled; expandir via migração';

• Comentários aparecem no pgAdmin/DBeaver e \d+.
• Documente valores CHECK semelhantes a enum quando não usar o tipo ENUM do PostgreSQL.

Armadilhas

• Identificadores de caixa mista citados - Requerem aspas para sempre em cada consulta. Correção: Renomear em migração de expansão/contração para snake_case.
• Palavras reservadas como nomes - user, order precisam de aspas ou renomeação (app_user, sales_order). Correção: Prefixe ou sufixe nomes reservados.
• Sopa de abreviações - cust_ord_ln economiza digitação, perde legibilidade. Correção: Prefira palavras completas com menos de 30 caracteres.
• Nomes de índice inconsistentes - orders_customer_id_idx vs idx_order_customer. Correção: Um modelo na configuração do SQLFluff.
• Schema public para tudo - Risco de colisão e segurança. Correção: Schema de aplicação app com search_path explícito.

Alternativas

FAQs

Relacionados

• Checklist de Regras do Projeto Postgres - regras 1-5
• Noções Básicas de Migrações - SQL no git
• Codificação e Localidade do Cliente - escolhas de collation

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.