Most teams that write one don't actually have a SQL style guide problem. They have an enforcement problem wearing a style guide's clothes. The guide exists, it's reasonable, someone even linked it in the onboarding doc, and six months later half the queries in the codebase don't follow it anyway, and nobody quite remembers when it stopped mattering.
Photo by Luis Quintero on Pexels
The guide is a suggestion, and suggestions decay
A style guide that lives in a wiki page or a README has no mechanism forcing anyone to check it before writing code. New team members don't read onboarding docs closely enough to internalize keyword-case preferences from page four of a style guide, especially in their first week when there are a dozen more urgent things competing for attention. Existing team members forget it exists the moment they're deep in a debugging session and just want the query to work. Neither group is being careless. The guide simply has no teeth, and documentation without enforcement decays at a predictable rate regardless of how well it was written.
Manual review catches maybe half of it
Reviewers are supposed to be the backstop, but reviewers are humans looking at logic, not whitespace police. A reviewer who's focused on whether a join is correct will let inconsistent casing slide because flagging it feels like nitpicking, and nobody wants to be the person who blocks a PR over select versus SELECT when the actual logic is sound. So it slides, repeatedly, until the guide is more theoretical than real, and the gap between "documented standard" and "actual codebase" widens every sprint.
There's also a social cost reviewers are implicitly weighing that rarely gets said out loud: flagging style issues repeatedly on the same person's PRs reads as nitpicking even when it's technically correct, and most reviewers would rather preserve the working relationship than win every formatting argument.
The fix isn't a stricter guide, it's removing the human step
The teams that actually maintain consistent SQL formatting long-term almost always have one thing in common: a formatter running automatically, either in a pre-commit hook or a CI check, so the convention gets applied without anyone deciding to apply it. The style guide becomes documentation of what the automated tool already enforces, rather than the primary enforcement mechanism itself, which is a meaningfully different (and much more durable) role for it to play.
This matters because it removes the social cost of enforcement entirely. Nobody has to be the person nagging a teammate about casing in a PR comment. The tool just does it, silently, every time, and the conversation about style only comes up once, when the team decides what the automated config should say, instead of recurring on every single pull request forever.
A pattern worth recognizing in other parts of your stack
This isn't a SQL-specific problem, it's a general pattern about any written standard that lacks automated enforcement. API design guidelines, commit message conventions, and naming standards for cloud resources all suffer from the exact same decay curve: documented once with good intentions, followed closely for a few weeks, then quietly abandoned as soon as the initial enthusiasm fades and nobody's actively checking. If your team has other written standards that feel similarly unenforced, the same diagnosis probably applies, and the same fix (automate the check, stop relying on memory) is probably the right move there too.
Recognizing this pattern is useful because it reframes the SQL formatting problem as not really about SQL at all. It's about the general principle that a standard without an automated check is really just a suggestion, no matter how carefully it was written or how good the reasoning behind it is.
What this looks like in practice
Format on save in the editor, a pre-commit hook that blocks a commit if formatting doesn't match, or a CI step that fails the build. Any of the three works, and most teams end up with some combination of at least two for redundancy. What doesn't work is a written guide with no automated check behind it, because the guide is only as strong as someone's memory in the moment they're writing code, and memory under deadline pressure is not a reliable enforcement mechanism.
Getting from "guide nobody follows" to "convention that sticks"
If your team is at the "we have a guide nobody follows" stage, the fastest unstick is picking a formatter, running it against a few real queries to confirm the output matches what your team actually wants, and then wiring it into whichever step (save, commit, or CI) your team is most likely to actually respect given how your workflow already operates.
https://evvytools.com/tools/dev-tech/sql-formatter/ is a fast way to preview what a given convention produces before you commit your team to it, with no setup required to just see the output on a real query. The reasoning behind why different formatters default to different conventions in the first place is covered in more depth in this piece on SQL formatter keyword case and indent style.
For how other language communities solved the same enforcement problem, Go's gofmt documentation and the Prettier project are both worth studying, since they turned "the style guide" into "the tool" for their respective ecosystems and largely ended the recurring debate that SQL teams are still having today. The Black documentation is another good reference point for how Python's community made the same transition from written convention to automated enforcement.
Why SQL lagged behind other languages on this
It's worth asking why application languages solved this years before most SQL codebases did. Part of the answer is tooling maturity: Go shipped gofmt as part of the language's own toolchain from very early on, which meant there was never really a period where teams had to choose to adopt formatting discipline, it was just there by default from day one. SQL has no single toolchain in that sense. It's a query language embedded across dozens of different application stacks, ORMs, migration tools, and BI platforms, each with its own conventions and none of them treating a shared formatter as a first-class default the way go build does.
That fragmentation is exactly why the problem persists longer in SQL-heavy codebases than in, say, a pure Go or Python repo. There's no single obvious tool everyone already has installed. Picking one, configuring it, and wiring it into your specific stack is a deliberate decision a team has to make, rather than something that comes for free with the language. That extra friction is real, but it's also a one-time cost, and it's considerably smaller than the ongoing cost of a style guide nobody follows.
The signal that tells you it's time to fix this
If your team has had the same "can we agree on SQL formatting" conversation more than once, that's the signal. A style question that keeps resurfacing despite being nominally settled isn't actually settled, it's just quiet for a while between flare-ups. That pattern is the clearest sign that documentation alone isn't going to solve it, and that the fix has to be structural rather than another round of writing the guide down more clearly.
Top comments (0)