Visão Geral das Regras do PostgreSQL

Esta seção parece uma lista de instruções arbitrárias: use snake_case, execute EXPLAIN antes de fazer o merge, defina lock_timeout em migrações, nunca conecte o aplicativo como superusuário.

Cada uma delas é, na verdade, o resíduo comprimido de algo que já deu errado uma vez, generalizado em uma instrução barata o suficiente para ser seguida sem reaprender o incidente original.

Resumo

Uma regra de PostgreSQL é um modo de falha específico e previamente aprendido, transformado em uma instrução que o próximo engenheiro pode seguir sem redescobrir o problema por conta própria.
Por que Importa: Tratar cada regra como igualmente arbitrária ou igualmente obrigatória perde a questão real, que é o custo real de uma violação específica se ela ocorrer.
Conceitos Chave: regra vs. preferência, nível de aplicação, verificabilidade, ADR (Architecture Decision Record), decaimento de regras (rule rot).
Quando Usar: Decidir se uma nova convenção merece uma regra escrita, escolher o quão estritamente aplicar uma, ou avaliar se uma regra antiga ainda justifica seu lugar.
Limitações / Trade-offs: Regras trocam o julgamento individual por consistência, e um documento de regras que apenas cresce e nunca é revisitado se torna atrito em vez de proteção.
Tópicos Relacionados: convenções de nomenclatura e estilo, segurança de migração, padrões de índice e consulta, endurecimento de segurança.

Toda regra duradoura nesta seção começa no mesmo lugar: uma consulta derrubou uma tabela, uma migração ficou presa atrás de um lock, ou um esquema atingiu uma ambiguidade que ninguém havia resolvido com antecedência.

A instrução que se segue, "execute EXPLAIN antes de fazer o merge de uma nova consulta" ou "defina lock_timeout em cada migração", é mais barata de declarar e seguir do que o incidente custou para ser vivenciado, que é o objetivo de escrever regras.

Essa moldura separa uma regra de uma preferência de estilo, mesmo que ambas possam viver no mesmo documento e parecer igualmente sucintas na página.

Uma preferência de estilo, como nomes de tabelas no singular versus plural, não tem nenhum modo de falha por trás dela; nada quebra de qualquer maneira, então o único custo da inconsistência é a legibilidade e o atrito de busca em todo o codebase.

Uma regra, no sentido que esta seção usa a palavra, existe porque errar nela tem um custo real e descritível, uma interrupção, uma brecha de segurança ou uma migração de várias horas que deveria ter levado segundos.

Uma analogia útil: um documento de regras é o tecido cicatricial do codebase tornado legível, cada cicatriz marcando um lugar onde a equipe foi realmente ferida, ainda protegendo contra uma repetição muito depois que o corte original foi esquecido.

Mecânicas e Interações

Nem toda regra merece a mesma força de aplicação, e combinar a aplicação com o custo real é a maior parte do que separa um documento de regras útil de uma lista que ninguém lê.

As regras nesta seção situam-se em um espectro aproximado, de convenção documentada, esperada na revisão, mas não verificada mecanicamente, a aplicada em revisão de código, onde espera-se que um humano a capture, a aplicada em CI, onde uma regra de lint ou um teste falha a build automaticamente.

incidente acontece
      │
      ▼
lição escrita          ── convenção documentada
      │  (padrão recorre, é verificável)
      ▼
revisores observam       ── aplicada em revisão de código
      │  (uma ferramenta pode expressá-la)
      ▼
portão mecânico bloqueia   ── aplicada em CI

Uma regra geralmente começa no topo dessa cadeia, porque alguém acabou de aprender a lição e a escreveu, e ganha seu caminho para baixo em direção a um portão de CI apenas quando a equipe confirma duas coisas: o padrão realmente recorre e é o tipo de coisa que uma verificação mecânica pode detectar de forma confiável.

Forçar uma regra dependente de julgamento diretamente em um portão de CI antes que ela seja confiavelmente verificável produz falsos positivos, e falsos positivos ensinam os engenheiros a contornar o portão em vez de confiar nele.

O Checklist de Regras do Projeto Postgres é a versão concreta e em camadas dessa ideia aplicada em escala de projeto: seus 25 itens são agrupados por quão bloqueadores de lançamento eles são, o que por si só é uma aplicação de "nem toda regra merece a mesma urgência".

Considerações Avançadas e Aplicações

Um processo de exceção é o que impede que uma regra mecanicamente aplicada se torne burocracia inflexível na primeira vez que encontra um caso extremo legítimo que não antecipou.

Sem um, uma equipe ou quebra a regra silenciosamente, minando-a para todos que confiaram no portão, ou bloqueia uma mudança genuinamente válida, minando a confiança no próprio processo.

O Modelo ADR para Postgres existe exatamente para essa situação: um Architecture Decision Record torna um desvio da regra padrão visível e deliberado em vez de invisível.

As regras também acumulam um tipo específico de decaimento que vale a pena nomear diretamente, decaimento de regras (rule rot), onde uma instrução continua sendo aplicada muito depois que a situação que a justificou mudou.

Uma regra de uso de índice verificada manualmente escrita antes que pg_stat_statements fosse padrão em todos os ambientes pode não valer mais a pena quando a revisão automatizada de consultas é executada em cada PR, não porque a regra estava errada, mas porque ferramentas melhores agora cobrem o mesmo objetivo subjacente.

Regras que nomeiam a falha específica que previnem envelhecem melhor do que regras declaradas como instrução pura, porque uma equipe que revisita "por que fazemos isso" pode realmente julgar se essa falha ainda é um risco real antes de decidir manter, relaxar ou automatizar a regra ainda mais.

Nível de aplicação	Força	Fraqueza	Melhor Ajuste
Convenção documentada	Barata de escrever; preserva o julgamento para casos extremos genuínos	Depende da memória e da cultura; se deteriora sob pressão de prazo	Decisões dependentes de contexto que um linter não pode avaliar
Aplicada em revisão de código	Captura nuances que uma verificação mecânica perderia	Inconsistente entre revisores e tempo de revisão disponível	Regras que exigem muito julgamento com riscos altos o suficiente para precisar de um segundo revisor
Portão aplicado em CI	Aplica-se uniformemente a todos os contribuidores, todas as vezes	Só funciona para padrões genuinamente verificáveis; falsos positivos minam a confiança	Violações de alto custo e claramente detectáveis, como índices ausentes ou papéis de superusuário para aplicativos

Conceitos Equivocados Comuns

"As regras desta seção são apenas preferências de estilo com passos extras." Uma escolha de estilo como nomes de tabelas no plural não tem modo de falha; uma regra como "nenhum papel de superusuário para aplicativos" existe especificamente porque violá-la tem um custo real e descritível.
"Escrever uma regra é o mesmo que aplicá-la." Uma regra não aplicada vale apenas enquanto cada engenheiro se lembrar e escolher segui-la, que é exatamente a lacuna que os níveis de aplicação existem para fechar.
"Toda regra nesta seção deve eventualmente se tornar um portão de CI." Apenas padrões genuinamente verificáveis pertencem lá; uma regra dependente de julgamento forçada em um portão mecânico produz falsos positivos que ensinam os engenheiros a contornar ou desconfiar do portão.
"Uma regra sem exceções é uma regra mais forte." Uma regra absoluta sem uma saída de emergência apenas realoca a exceção de "visível e deliberada" para "silenciosamente violada", o que é pior para quem auditar o esquema mais tarde.
"Regras antigas nesta lista sempre valem a pena ser seguidas exatamente como escritas." Uma regra pode sobreviver à situação que a justificou, especialmente quando ferramentas melhores a substituem, razão pela qual a revisão periódica pertence ao mesmo processo que criou a regra.

FAQs

Qual é a diferença real entre uma "regra" e uma "preferência de estilo" nesta seção?

Uma preferência de estilo, como nomes de tabelas no singular versus plural, não tem modo de falha; uma regra existe especificamente porque errar nela tem um custo real e descritível, como uma interrupção ou uma brecha de segurança.

Por que esta seção se preocupa em explicar "por que" uma regra existe em vez de apenas listar a regra?

Uma regra declarada apenas como comportamento exigido é seguida ou silenciosamente descartada sem que ninguém possa julgar se ela ainda se aplica; nomear a falha que ela previne permite que um futuro engenheiro realmente avalie isso.

Como uma convenção passa de "documentada" para "aplicada em CI"?

Ela ganha essa promoção quando o padrão genuinamente recorre e uma verificação mecânica pode detectá-lo de forma confiável, sem falsos positivos; regras que ainda precisam de julgamento real permanecem no nível de aplicação de revisão de código.

Por que não tornar imediatamente cada regra importante um portão de CI rígido?

Porque portões de CI só funcionam bem para padrões que uma ferramenta pode verificar de forma confiável, e forçar uma regra dependente de julgamento em um portão produz falsos positivos que ensinam os engenheiros a ignorá-lo ou desconfiar dele.

Qual é o propósito de um processo de exceção, como um ADR, para uma regra?

Ele oferece a um caso extremo legítimo um caminho visível e deliberado para contornar o padrão, em vez de forçar uma violação silenciosa ou bloquear uma mudança genuinamente válida.

O que é "decaimento de regras" (rule rot) e por que ele importa para um documento de regras de PostgreSQL?

É quando uma regra continua sendo aplicada após a situação que a justificou ter mudado, como uma regra manual de revisão de índices substituída pelo monitoramento automatizado de pg_stat_statements, e ela se acumula como atrito sem um benefício correspondente.

Cada regra nesta seção deve se aplicar com a mesma urgência a todos os projetos?

Não necessariamente - o Checklist de Regras do Projeto Postgres agrupa as regras por quão bloqueadoras de lançamento elas são, pois uma regra de segurança e uma regra de maturidade operacional não carregam o mesmo risco se deixadas sem atenção.

Quem decide se uma nova convenção se torna uma regra oficial da equipe?

Na prática, quem quer que seja o responsável pelo incidente ou pelo custo recorrente do padrão, mas a decisão deve ser documentada e visível em vez de deixada na memória de um engenheiro.

Como uma convenção de nomenclatura como snake_case difere de uma regra como "indexar antes de fazer o merge"?

A nomenclatura é uma escolha de estilo pura sem modo de falha; "indexar antes de fazer o merge" existe porque uma consulta de produção sem índice causou diretamente interrupções, razão pela qual uma pertence a um linter e a outra à revisão.

Ter um grande documento de regras significa que uma equipe de engenharia é mais madura?

Somente se cada regra ainda nomear uma falha real e atual e tiver a aplicação correspondente ao seu custo real; um documento que apenas cresce e nunca é revisitado é a versão burocrática do mesmo artefato.

Uma regra pode ser relaxada depois que as ferramentas que a tornaram necessária melhoram?

Sim, e ela deve ser revisada em vez de deixada em vigor indefinidamente - uma regra que foi substituída por ferramentas automatizadas melhores é candidata à aposentadoria, não à aplicação permanente.

Onde as regras específicas de segurança se encaixam em relação ao resto desta seção?

Elas geralmente se situam na mais alta urgência de aplicação, pois uma regra de segurança violada (como um papel de superusuário para aplicativos) tende a carregar um custo desproporcional e difícil de reverter em comparação com uma inconsistência de estilo ou nomenclatura.

Relacionados

Checklist de Regras do Projeto Postgres - a auditoria concreta e em camadas de 25 regras em que este modelo se baseia
Regras de Nomenclatura e Estilo - onde a preferência de estilo e a regra se cruzam
Regras de Índice e Consulta - um conjunto de regras concreto e de alta aplicação
Regras de Segurança de Migração - convenções de timeout de lock e statement
Modelo ADR para Postgres - como as exceções a uma regra são registradas deliberadamente

Versões do Stack: Esta página é conceitual e não está vinculada a uma versão específica do stack.