Padrões de Nomenclatura e Documentação

Nomenclatura consistente e documentação no banco de dados reduzem o tempo de onboarding e previnem migrações incompatíveis entre equipes. Diagramas ER no git permanecem versionados com o schema que descrevem.

Receita

Cartão de referência rápida - pronto para copiar e colar.

COMMENT ON TABLE orders IS 'Cabeçalho de compra do cliente; particionado por created_at trimestralmente.';
COMMENT ON COLUMN orders.status IS 'open|paid|shipped|closed; ver orders_status_enum.';
 
COMMENT ON COLUMN orders.legacy_total IS
  'DEPRECATED 2026-03: use total_cents. Remover após release 4.2.';

# Exportar diagrama de schema em CI (exemplo: schemaspy, dbml-cli)
dbml2sql schema.dbml -o docs/erd/orders.dbml.sql
git add docs/erd/orders.dbml

Quando usar isso: Inicialização de um novo serviço, integração de aquisição ou mandato do conselho para cobertura de documentação.

Exemplo de Trabalho

Nova tabela subscriptions enviada com comentários e PR de ERD.

CREATE TABLE subscriptions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id uuid NOT NULL REFERENCES tenants(id),
  plan_code text NOT NULL,
  started_at timestamptz NOT NULL DEFAULT now(),
  ends_at timestamptz
);
 
COMMENT ON TABLE subscriptions IS 'Assinaturas de faturamento ativas por tenant.';
COMMENT ON COLUMN subscriptions.plan_code IS 'FK para plans.code; não uuid para ferramentas de suporte humano.';

// docs/erd/billing.dbml
Table subscriptions {
  id uuid [pk]
  tenant_id uuid [ref: > tenants.id]
  plan_code text
}

O que isso demonstra:

Comentários explicam por que, não apenas qual o tipo da coluna.
Datas de depreciação em COMMENT ON COLUMN para rastreamento de fase de contrato.
DBML (ou similar) no git para diffs de ERD revisáveis.

Análise Detalhada

Regras de Nomenclatura

Objeto	Convenção	Exemplo
Tabela	snake_case plural	`invoice_line_items`
Coluna	snake_case	`created_at`
Índice	`{tabela}_{colunas}_{sufixo}`	`orders_tenant_created_idx`
Restrição	`{tabela}_{descrição}_{tipo}`	`orders_total_positive_chk`
Tipo Enum	`{domínio}_{campo}_enum`	`order_status_enum`

Evite abreviações exceto id, url, uuid.

Documentação Obrigatória

Toda tabela pública: COMMENT ON TABLE.
Toda coluna não óbvia: significado de negócio ou referência de enum.
Relacionamentos FK visíveis no ERD e aplicados no DDL.
Mudanças disruptivas anotadas em comentário antes da remoção.

Fluxo de Trabalho de ERD no Git

1. Autor atualiza schema.dbml no branch de feature
2. PR mostra imagem de diff de ERD via CI
3. SQL de migração gerado ou sincronizado manualmente para corresponder
4. Ordem de merge: ADR (se necessário) → ERD → migração

Armadilhas

Comentários se desviam da realidade - Ninguém atualiza após renomear. Correção: O PR de migração deve atualizar o comentário no mesmo commit.
ERD apenas no Lucidchart - Não em revisão. Correção: DBML/Mermaid no repositório; link do README.
Notação húngara - strCustomerName em SQL. Correção: Lint na checklist de revisão de SQL.
Nomes genéricos - colunas data, value, info. Correção: Exigir termo de domínio no nome da coluna.
Enums não documentados - Constantes apenas no app. Correção: ENUM do Postgres ou constraint de verificação documentado em comentário.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
ENUM do Postgres	Conjunto fechado estável	Valores mudam semanalmente
Constraint de verificação	Validação flexível	Necessidade de exportar tipo para ORM
Catálogo de dados externo	Metadados corporativos	Overhead de equipe pequena
Apenas OpenAPI	Serviço API-first	DB é ponto de integração

FAQs

Comentários são visíveis para ORMs?

Algumas ferramentas os leem; o público principal são humanos e exportadores de catálogo de dados.

DBML vs pgModeler?

DBML difere bem no git; escolha a ferramenta que exporta formato de texto.

Limite de comprimento do comentário?

PostgreSQL permite strings longas; mantenha abaixo de 500 caracteres para legibilidade.

Documentar views e MVs?

Sim; inclua o cronograma de atualização no comentário para materialized views.

Nomes de coluna não em inglês?

Inglês canônico no schema; localize na camada de aplicação.

Gerar comentários automaticamente a partir do ORM?

O significado de negócio escrito à mão ainda é necessário; a geração de código sozinha é insuficiente.

Documentos de coluna sensível?

Comente "PII - sujeito à política de retenção" sem valores de exemplo.

Quem aprova exceções de nomenclatura?

Conselho de banco de dados com ADR para nomes de tabela não padrão.

Diff de schema em PR?

Use migra ou atlas schema diff contra um snapshot de staging.

O que devo ler em seguida?

Veja Regras de Nomenclatura do PostgreSQL.

Relacionados

Noções Básicas de Governança - visão geral do programa
Regras de Nomenclatura e Estilo - regras da equipe
Modelo de ADR para Postgres - exceções
Noções Básicas de Git para Trabalho com Banco de Dados - schema versionado

Versões da 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+.

Padrões de Nomenclatura e Documentação

Receita

Cartão de referência rápida - pronto para copiar e colar.

COMMENT ON TABLE orders IS 'Cabeçalho de compra do cliente; particionado por created_at trimestralmente.';
COMMENT ON COLUMN orders.status IS 'open|paid|shipped|closed; ver orders_status_enum.';
 
COMMENT ON COLUMN orders.legacy_total IS
  'DEPRECATED 2026-03: use total_cents. Remover após release 4.2.';

# Exportar diagrama de schema em CI (exemplo: schemaspy, dbml-cli)
dbml2sql schema.dbml -o docs/erd/orders.dbml.sql
git add docs/erd/orders.dbml

Quando usar isso: Inicialização de um novo serviço, integração de aquisição ou mandato do conselho para cobertura de documentação.

Exemplo de Trabalho

Nova tabela subscriptions enviada com comentários e PR de ERD.

CREATE TABLE subscriptions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id uuid NOT NULL REFERENCES tenants(id),
  plan_code text NOT NULL,
  started_at timestamptz NOT NULL DEFAULT now(),
  ends_at timestamptz
);
 
COMMENT ON TABLE subscriptions IS 'Assinaturas de faturamento ativas por tenant.';
COMMENT ON COLUMN subscriptions.plan_code IS 'FK para plans.code; não uuid para ferramentas de suporte humano.';

// docs/erd/billing.dbml
Table subscriptions {
  id uuid [pk]
  tenant_id uuid [ref: > tenants.id]
  plan_code text
}

O que isso demonstra:

Comentários explicam por que, não apenas qual o tipo da coluna.
Datas de depreciação em COMMENT ON COLUMN para rastreamento de fase de contrato.
DBML (ou similar) no git para diffs de ERD revisáveis.

Análise Detalhada

Regras de Nomenclatura

Objeto	Convenção	Exemplo
Tabela	snake_case plural	`invoice_line_items`
Coluna	snake_case	`created_at`
Índice	`{tabela}_{colunas}_{sufixo}`	`orders_tenant_created_idx`
Restrição	`{tabela}_{descrição}_{tipo}`	`orders_total_positive_chk`
Tipo Enum	`{domínio}_{campo}_enum`	`order_status_enum`

Evite abreviações exceto id, url, uuid.

Documentação Obrigatória

Toda tabela pública: COMMENT ON TABLE.
Toda coluna não óbvia: significado de negócio ou referência de enum.
Relacionamentos FK visíveis no ERD e aplicados no DDL.
Mudanças disruptivas anotadas em comentário antes da remoção.

Fluxo de Trabalho de ERD no Git

1. Autor atualiza schema.dbml no branch de feature
2. PR mostra imagem de diff de ERD via CI
3. SQL de migração gerado ou sincronizado manualmente para corresponder
4. Ordem de merge: ADR (se necessário) → ERD → migração

Armadilhas

Comentários se desviam da realidade - Ninguém atualiza após renomear. Correção: O PR de migração deve atualizar o comentário no mesmo commit.
ERD apenas no Lucidchart - Não em revisão. Correção: DBML/Mermaid no repositório; link do README.
Notação húngara - strCustomerName em SQL. Correção: Lint na checklist de revisão de SQL.
Nomes genéricos - colunas data, value, info. Correção: Exigir termo de domínio no nome da coluna.
Enums não documentados - Constantes apenas no app. Correção: ENUM do Postgres ou constraint de verificação documentado em comentário.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
ENUM do Postgres	Conjunto fechado estável	Valores mudam semanalmente
Constraint de verificação	Validação flexível	Necessidade de exportar tipo para ORM
Catálogo de dados externo	Metadados corporativos	Overhead de equipe pequena
Apenas OpenAPI	Serviço API-first	DB é ponto de integração

FAQs

Comentários são visíveis para ORMs?

Algumas ferramentas os leem; o público principal são humanos e exportadores de catálogo de dados.

DBML vs pgModeler?

DBML difere bem no git; escolha a ferramenta que exporta formato de texto.

Limite de comprimento do comentário?

PostgreSQL permite strings longas; mantenha abaixo de 500 caracteres para legibilidade.

Documentar views e MVs?

Sim; inclua o cronograma de atualização no comentário para materialized views.

Nomes de coluna não em inglês?

Inglês canônico no schema; localize na camada de aplicação.

Gerar comentários automaticamente a partir do ORM?

O significado de negócio escrito à mão ainda é necessário; a geração de código sozinha é insuficiente.

Documentos de coluna sensível?

Comente "PII - sujeito à política de retenção" sem valores de exemplo.

Quem aprova exceções de nomenclatura?

Conselho de banco de dados com ADR para nomes de tabela não padrão.

Diff de schema em PR?

Use migra ou atlas schema diff contra um snapshot de staging.

O que devo ler em seguida?

Veja Regras de Nomenclatura do PostgreSQL.

Relacionados

Noções Básicas de Governança - visão geral do programa
Regras de Nomenclatura e Estilo - regras da equipe
Modelo de ADR para Postgres - exceções
Noções Básicas de Git para Trabalho com Banco de Dados - schema versionado

Versões da 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+.

Padrões de Nomenclatura e Documentação

Buscar na documentação

Padrões de Nomenclatura e Documentação