Structuring and Formatting SQL Statements — The Cluster Path

Published May 17, 2018 · Updated Aug 27, 2026
by

A complex SQL statement is hard enough to read on its own — shifting coding styles in the same file turn every line into an extra re-orientation task. SQL formatting is therefore a team responsibility, not a personal matter of taste.

At a glance:

  • Coding style is a team responsibility, not a personal preference — divergent styles in one file are a concrete maintainability problem.
  • Four readability axes with their own deep dives: editor configuration, identifiers and delimiters, statement structure, commenting.
  • Auto-formatters complement, but don’t replace the learning effect of manual formatting.
  • 2026 framing: multi-editor world, sqlfluff and pgFormatter as linters, manual re-formatting as a lever for understanding AI-generated code.

Prerequisites: SQL Server or Postgres — the series was written in 2018 with SSMS as its reference editor; the principles are version-independent and apply to any SQL editor with block selection.

Contents

Backstory: 2,000 Lines, Three Styles

Some time ago I revised a substantial procedure with nearly 2,000 lines of code — three developers had worked on it in sequence. It contained statements for about 30 tables, all essentially doing the same job. The per-table statements could all have looked similar. In practice, they differed between developers — and even within a single developer’s contributions — in ways that pressed down on readability and maintainability to varying degrees:

  • Were object names quoted with delimiters?
  • What about upper/lower case for keywords and function names?
  • Were inline comments added at table or entity changes?
  • Temp tables or table variables?
  • …

In the past 20 years of my work as a consultant, many attempts to establish rules for code formatting and structuring have failed or been accompanied by heated debate. Whoever has developed personal preferences over a developer’s career rarely accepts new conventions willingly — the human as a creature of habit tends to be overwhelmed.

The Reformat Trap

While reviewing another procedure — written by a colleague whose work I genuinely respected — I didn’t like its structuring and formatting at all. Without thinking about the consequences, I quickly reformatted the procedure during the review. Functionally it was correct and bug-free. But the check-in marked it as changed — and after the heavy reformatting, the diff no longer made it clear whether anything had also been functionally altered.

The criticism I caught for that was well earned. Reformat commits belong on their own — never mixed with substance edits. In concrete terms: one commit “Reformat to team style”, and separately one commit “Fix: customer-history join”. Otherwise the style pass destroys the reviewability of the functional diff.

Even in 2026, the same holds for the built-in formatter in SSMS as for other SQL editors: it produces layout according to given rules, but it doesn’t decide which rules should apply. Defining the style remains a team responsibility.

The Four Axes of SQL Readability

This article series breaks down the four core axes of SQL code readability — one deep-dive article per axis, summarised here as a path overview. The axes deliberately sit on different levels, from the working environment to documentation. Only together do they produce readable code:

  • Axis 1 — Editor Configuration. The ground everything else stands on: tab vs. space, line numbers, word wrap, block selection. Without those fundamentals, the following axes become tedious.
  • Axis 2 — Identifiers, Delimiters, Aliases. The vocabulary layer: T01 or CustomerHist, [brackets] or none, comma before or after the column.
  • Axis 3 — Statement Structure: SELECT, WHERE, FROM, JOIN. The grammar layer: how to lay out SELECT clauses, WHERE conditions and JOINs so the data structure shows.
  • Axis 4 — Commenting. The meta layer: inline and block comments inside 2,000-line statements so the next review doesn’t start from zero.

The Cluster Path in Order

The four axes can be studied separately. As a reading order, this path has proven itself:

  1. Editor first. Identifier conventions are painful without a working editor that supports block selection — nobody wants to copy-paste five lines one at a time.
  2. Identifiers next. Statement structure is easier to lay out consistently once the identifier conventions (aliases, delimiters, comma position) are settled.
  3. Statement structure third. Investing in clean commenting only pays off once the individual statements are readable — otherwise comments hide the underlying structure instead of explaining it.
  4. Commenting last. The meta layer wins only when the statement itself is clear enough about what it does — comments then address the why.

That is the reading order for the individual reader. When a team introduces a style guide, the logic flips: agree on the conventions first, then automate, then adjust editor practice — see the “Auto-Formatters Complement, They Don’t Replace” section below.

Formatting in 2026

The Multi-Editor World

SSMS remains the Microsoft default, but by 2026 the SQL editor landscape has widened considerably:

  • VS Code with the mssql extension — since Azure Data Studio’s retirement, Microsoft’s recommended cross-platform route for SQL development. Provides multi-cursor, excellent source-control integration, and built-in Schema Compare / Schema Designer / GitHub Copilot.
  • Azure Data Studio — Microsoft’s cross-platform alternative to SSMS, retired on February 28, 2026. Existing installations keep working but no longer receive updates or security patches. Microsoft recommends migrating to the VS Code mssql extension (a built-in migration toolkit ports connections and settings).
  • DataGrip (JetBrains) for multi-engine DBA work — commercial, with a strong SQL parser, dialect-specific code styles and refactoring features.
  • DBeaver as an open-source multi-engine tool — the free Community Edition is enough for most cases.
  • pgAdmin for Postgres-centric stacks.

What they share: multi-cursor and block selection as the modern counterpart to SSMS column selection — ALT+Click in VS Code, Ctrl+Alt+Click in DataGrip. The block-selection argument from Axis 1 applies multi-tool in 2026, not SSMS-only.

Auto-Formatters Complement, They Don’t Replace

While in 2018 every style pass had to run by hand, in 2026 there are established formatters and linters for multiple SQL dialects:

  • sqlfluff — linter and formatter for T-SQL, Postgres, Snowflake, BigQuery, DuckDB and other dialects. Configurable via a .sqlfluff file, CI-friendly, with dbt integration.
  • pgFormatter — a formatter specialising in Postgres and PL/pgSQL (Perl-based), available as CLI and online tool.
  • sql-formatter and Prettier plugins for SQL (prettier-plugin-sql, prettier-plugin-sql-cst) — for SQL snippets in web stacks (frontend/backend mixed repos).

What these tools don’t take off your hands: the style decision. A formatter can capture and enforce a large share of the team conventions — which convention goes into the configuration (comma position, JOIN indentation, alias casing) is still up to the team. The four axes are therefore not obsolete; they’re enforced via tooling. The order matters: settle the team rules first, then configure the formatter to match. Otherwise the formatter configuration itself becomes the next style dispute.

“Formatting Is Learning” in the Age of AI

The thesis is old: manual formatting forces you to read in full and to build a mental model of the data and table structure. Indenting, aligning aliases and placing brackets only works if you know which table joins to which, and which columns belong together.

In 2026 that weighs twice as much, because generated SQL code from Copilot, Cursor and LLM tools often looks technically correct without actually answering the business question. A statement that hits the right tables but uses LEFT JOIN instead of INNER JOIN yields syntactically correct results with a semantically wrong row count. Whoever manually reformats the generated code — aligning columns, examining JOIN conditions, checking aliases — understands the statement in a place where the pure copy-paste-from-LLM-to-editor-and-run pattern never would.

Auto-formatters don’t replace the learning effect. Manual re-formatting is a low-friction learning lever, including in code reviews, where the reviewer walks through unfamiliar code structurally while reformatting it. It does not, however, replace functional review or tests: structural inspection shows how a statement is built, not whether it answers the right question.

The four axes of this series haven’t stood still either: what is written here as a style guide for human readers can now be wired into AI tools like Claude Code as a rules file — the assistant then generates code in the team convention from the start, instead of someone reformatting after the fact. How such a rules file is derived from existing code is shown in Deriving SQL Conventions with Claude Code — the Generate-Refine-Derive Loop. How the conventions of this series live on as a PL/pgSQL rulebook is shown in PL/pgSQL Procedures You Can Still Read in Two Years.

Take-Away

  • SQL style guides don’t standardise taste — they lower review and maintenance costs. That’s why SQL formatting is a team responsibility.
  • The four axes — editor, identifiers, statement structure, commenting — belong together, can be studied separately, and build on each other.
  • Auto-formatters like sqlfluff and pgFormatter produce layout but don’t replace the learning effect of manual formatting.
  • In the age of AI, manual re-formatting is a low-friction lever for actually understanding generated code — layout pass as comprehension pass.

FAQ

Why format manually if sqlfluff does it automatically?

Because producing layout and absorbing what the code does are different things. sqlfluff solves the consistency problem, but not the comprehension problem: when formatting manually, you read each line, build the mental model of the table relationships and notice where a JOIN looks suspicious. Auto-formatters are a layout aid, not a learning tool — see the “Formatting Is Learning” section above.

In which order should I read the four sub-articles?

Editor → identifiers → statement structure → commenting. The order is a reading recommendation, not a hard dependency — but each axis benefits from the previous one: identifier conventions from a working block-selection editor, statement structure from stable aliases, and commenting only pays off once the statement itself is clear enough. See the “Cluster Path in Order” section above.

What’s the difference between structuring and formatting?

Formatting is the layout — indentation, comma position, aliases, the arrangement of JOINs. Structuring is the higher-level architecture — how to split a 2,000-line procedure into readable sub-statements, where to factor out helper functions, how comment headers mark the big picture. Formatting is the vocabulary layer, structuring is the essay layer. Important in practice: formatting doesn’t solve the structure problem — it makes structure visible.

How do I establish a coding style guide in a team that has worked without one for years?

In three steps. First: take an existing multi-style file as an example and show the divergent styles — that makes the problem concrete. Second: walk through each style point and let the team decide, rather than ruling from above. Third: pin down a sqlfluff configuration as an anchor and wire it into CI, so new code reviews stop arguing about layout. Important: always run the reformat pass on existing code in a separate commit without substance edits — see the “Reformat Trap” section above. Once the formatter then runs automatically before every review, formatting stops being a point of contention there: the review belongs to semantics.

Do these recommendations also work for Postgres, or only SQL Server?

Both. The four axes are dialect-neutral. Concrete tool recommendations differ (sqlfluff for multi-dialect, pgFormatter for Postgres-specific), and in Postgres, consistent snake_case is the prevailing convention: it fits the lowercase folding the engine applies to unquoted identifiers. The structuring arguments apply 1:1 in both worlds.

The four cluster deep-dives in reading order:

Upstream:

  • The Functional Aesthetics of SQL — the why of SQL formatting (structured code is faster to read, review and change). It provides the motivation; this article provides the path.

Downstream: