Structuring and Formatting SQL Statements — The Cluster Path

Published May 17, 2018 · Updated Jun 2, 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 2017+ or Postgres 12+ — SSMS remains the 2018 reference editor, but the principles 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. Otherwise the style pass destroys the reviewability of the functional diff.

Even in 2026 the built-in formatter in SSMS — and in most other SQL editors — is just a layout aid, not a style guide. 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:

  • 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 JOIN order 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, but they build on each other:

  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 can only be laid 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.

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 official cross-platform SQL editor. 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 and real-time refactoring.
  • 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 multi-dialect formatters:

  • 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 Postgres-specific formatter (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 do: define the style. They produce layout according to a configuration — the configuration itself (comma position, JOIN indentation, alias casing) remains a team decision. The four axes are therefore not obsolete; they’re enforced via tooling.

“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.

Take-Away

  • SQL formatting is a team responsibility, not a personal preference — divergent styles in one file are a concrete maintainability problem.
  • 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 indents and aligns — the writer doesn’t. When formatting manually, you read each line, build the mental model of the table relationships and notice where a JOIN doesn’t fit. 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. Each axis builds on the previous one: identifier conventions need a working block-selection editor, statement structure needs 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, JOIN order. 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.

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.

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 identifier conventions are stricter in the Postgres snake_case default than in SQL Server. The structuring arguments apply 1:1 in both worlds.

The four cluster deep-dives in reading order:

Upstream: The Functional Aesthetics of SQL (Theme 001) — the why of SQL formatting (structured code is faster to read, review and change). Theme 001 provides the motivation, Theme 009 provides the path.