Melhores Práticas de Regras PostgreSQL

Como fazer com que as regras do projeto Postgres sejam seguidas: automatize o linting, incorpore verificações em CI e mantenha a revisão humana para o que as máquinas não podem julgar.

Como Usar Esta Lista

• Comece com automação (seção A) antes de escrever mais regras em prosa.
• Alinhe os modelos de PR com os itens de verificação da seção B.
• Audite a deriva das regras trimestralmente usando a seção C.

A - Automação

• SQLFluff (ou sql-lint) em db/migrations/** em CI. Falhar PR em violações de análise e layout.
• Lint personalizado: exigir SET lock_timeout em arquivos de migração. Verificação de regex ou AST no pipeline.
• Scripts de smoke test pgTAP ou psql após migração. Asserções de esquema automatizadas.
• Convenções de nomenclatura do SQLFluff correspondem ao ADR. snake_case, prefixo de índice idx_.
• Hook de pré-commit localmente espelha o CI. Desenvolvedores veem falhas antes do push.

B - Portões de Revisão

• Checkbox do modelo de PR: EXPLAIN anexado para novas consultas de alto tráfego. Link para a saída de EXPLAIN (ANALYZE, BUFFERS).
• Revisão de DBA necessária para tabelas com mais de 10 milhões de linhas ou DDL ACCESS EXCLUSIVE. CODEOWNERS na pasta de migrações.
• Revisão de segurança quando RLS, BYPASSRLS ou SECURITY DEFINER são tocados. Sem carimbo de borracha em mudanças de política.
• ADR arquivado para mudanças de topologia, tenancy ou engine. Não para cada adição de coluna.
• Alternativas rejeitadas anotadas no ADR. Equipes futuras entendem os trade-offs.

C - Padrões Vivos

• Executar trimestralmente o Checklist de Regras do Projeto Postgres. Acompanhar a tendência de aprovação/falha.
• Atualizar regras em até 5 dias úteis após um incidente. Incidentes ensinam o que os checklists perderam.
• Documento de integração vincula regras + noções básicas de psql + menor privilégio. Um caminho para novos engenheiros.
• Incrementar a versão do documento de regras ao atualizar versões principais do PostgreSQL. Mudanças de comportamento (DDL, planejador) exigem atualização das regras.
• Aposentar regras que a automação impõe. Substituir marcadores manuais por IDs de regras do linter na documentação.

D - Exemplos de Ferramentas

# Exemplo de SQLFluff CI
sqlfluff lint db/migrations --dialect postgres
 
# Verificação personalizada do cabeçalho de migração
grep -L "lock_timeout" db/migrations/V*.sql && exit 1 || true

# Trecho de CODEOWNERS
/db/migrations/  @data-platform-team
/docs/adr/       @staff-engineers @dba-team

• Fixar a versão do SQLFluff no CI para resultados de lint reproduzíveis.
• Documentar supressões com -- noqa: RULE e justificativa de PR apenas.

E - Cultura

• Regras são guardrails, não burocracia - explique o porquê em uma linha cada. A retenção na integração melhora.
• Horário de expediente com especialistas para perguntas sobre regras. Reduz o trabalho de contorno de TI oculto.
• Celebrar detecções em CI. Reforça o investimento em automação.
• Nenhuma exceção em produção sem emenda de ADR com prazo. Exceções se deterioram em padrões.
• Sincronizar regras com IDs de controle de segurança/conformidade. Auditores SOC2 mapeiam verificações para evidências.

FAQs

Relacionados

• Checklist de Regras do Projeto Postgres - 25 itens de auditoria
• Regras de Nomenclatura e Estilo - Entrada de configuração do SQLFluff
• Noções Básicas de Git para Trabalho com Banco de Dados - Fluxo de trabalho de PR

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