PostgreSQL Rules Overview

This section reads like a list of arbitrary instructions: use snake_case, run EXPLAIN before merging, set lock_timeout in migrations, never connect the application as superuser.

Each one is really the compressed residue of something that already went wrong once, generalized into an instruction cheap enough to follow without relearning the original incident.

Summary

• Core Idea: A PostgreSQL rule is a specific, previously-learned failure mode, turned into an instruction the next engineer can follow without rediscovering the problem firsthand.
• Why It Matters: Treating every rule as equally arbitrary or equally mandatory misses the real question, which is how much a specific violation actually costs if it happens.
• Key Concepts: rule vs. preference, enforcement tier, checkability, ADR (Architecture Decision Record), rule rot.
• When to Use: Deciding whether a new convention deserves a written rule, choosing how strictly to enforce one, or evaluating whether an old rule still earns its place.
• Limitations / Trade-offs: Rules trade individual judgment for consistency, and a rules document that only grows and is never revisited becomes friction instead of protection.
• Related Topics: naming and style conventions, migration safety, index and query standards, security hardening.

Foundations

Every durable rule in this section starts from the same place: a query took down a table, a migration hung behind a lock, or a schema hit an ambiguity nobody had settled in advance.

The instruction that follows, "run EXPLAIN before merging a new query" or "set lock_timeout in every migration," is cheaper to state and follow than the incident was to live through, which is the entire point of writing rules down at all.

That framing separates a rule from a style preference, even though both can live in the same document and look similarly terse on the page.

A style preference, like singular versus plural table names, has no failure mode behind it at all; nothing breaks either way, so the only cost of inconsistency is readability and search friction across the codebase.

A rule, in the sense this section uses the word, exists because getting it wrong has a real, describable cost, an outage, a security gap, or a multi-hour migration that should have taken seconds.

A useful analogy: a rules document is a codebase's scar tissue made legible, each scar marking a place the team was actually injured, still protecting against a repeat long after the original cut is forgotten.

Mechanics & Interactions

Not every rule deserves the same amount of enforcement force, and matching enforcement to actual cost is most of what separates a useful rules document from a list nobody reads.

Rules in this section sit on a rough spectrum from documented convention, expected in review but not mechanically checked, to code-review-enforced, where a human is expected to catch it, to CI-enforced, where a lint rule or test fails the build automatically.

incident happens
      │
      ▼
lesson written down          ── documented convention
      │  (pattern recurs, is checkable)
      ▼
reviewers watch for it       ── code-review-enforced
      │  (a tool can express it)
      ▼
mechanical gate blocks it    ── CI-enforced

A rule generally starts at the top of that chain, because someone just learned the lesson and wrote it down, and earns its way down toward a CI gate only once the team confirms two things: the pattern genuinely recurs, and it is the kind of thing a mechanical check can detect reliably.

Forcing a judgment-dependent rule straight into a CI gate before it is reliably checkable produces false positives, and false positives teach engineers to route around the gate rather than trust it.

The Postgres Project Rules Checklist is the concrete, tiered version of this idea applied at project scale: its 25 items are grouped by how launch-blocking they are, which is itself an application of "not every rule deserves the same urgency."

Advanced Considerations & Applications

An exception process is what keeps a mechanically-enforced rule from becoming brittle bureaucracy the first time it meets a legitimate edge case it did not anticipate.

Without one, a team either breaks the rule silently, undermining it for everyone who trusted the gate, or blocks a genuinely valid change, undermining trust in the process itself.

The ADR Template for Postgres exists for exactly this situation: an Architecture Decision Record makes a deviation from the default rule visible and deliberate instead of invisible.

Rules also accumulate a specific kind of decay worth naming directly, rule rot, where an instruction keeps being enforced well after the situation that justified it has changed.

A hand-checked index-usage rule written before pg_stat_statements was standard in every environment might no longer earn its keep once automated query review runs on every PR, not because the rule was wrong, but because better tooling now covers the same underlying goal.

Rules that name the specific failure they prevent age better than rules stated as pure instruction, because a team revisiting "why do we do this" can actually judge whether that failure is still a live risk before deciding to keep, relax, or automate the rule further.

Common Misconceptions

• "This section's rules are just style preferences with extra steps." A style choice like plural table names has no failure mode behind it; a rule like "no superuser application role" exists specifically because violating it has a real, describable cost.
• "Writing a rule down is the same as enforcing it." An unenforced rule holds only as long as every engineer remembers and chooses to follow it, which is precisely the gap enforcement tiers exist to close.
• "Every rule in this section should eventually become a CI gate." Only genuinely checkable patterns belong there; a judgment-dependent rule forced into a mechanical gate produces false positives that teach engineers to distrust the gate.
• "A rule without exceptions is a stronger rule." An absolute rule with no escape hatch just relocates the exception from "visible and deliberate" to "silently violated," which is worse for anyone auditing the schema later.
• "Old rules in this list are always still worth following exactly as written." A rule can outlive the situation that justified it, especially once better tooling supersedes it, which is why periodic review belongs in the same process that created the rule.

FAQs

Related

• Postgres Project Rules Checklist - the concrete, tiered 25-rule audit this model underlies
• Naming & Style Rules - where style preference and rule intersect
• Index & Query Rules - a concrete, high-enforcement rule set
• Migration Safety Rules - lock and statement timeout conventions
• ADR Template for Postgres - how exceptions to a rule get recorded deliberately

Stack versions: This page is conceptual and not tied to a specific stack version.