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.
//
Busque em todas as páginas da documentação
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.
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.
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 CIUma 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".
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 |
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.
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.
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.
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.
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.
É 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.
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.
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.
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.
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.
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.
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.
Versões do Stack: Esta página é conceitual e não está vinculada a uma versão específica do stack.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026