Understanding SQL formatting
Reading a query, line by line.
A formatted SQL query reveals its structure at a glance. That's the whole point.
The standard layout.
One major clause per line — SELECT, FROM, JOIN, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT — each starting at the left margin. Selected columns indent under SELECT; join conditions indent under theirJOIN; AND/OR predicates align under WHERE. The result reads top-to-bottom in the order the database executes the query.
Keyword case.
Two camps exist: ALL CAPS keywords (the formatter's choice, and the most common in legacy tooling) or lowercase keywords (popular in modern codebases for quieter reading). The formatter uppercases keywords because they're the structural anchor of the query — casing them makes the eye lock onto where each clause begins.
Dialect tolerance.
SQL is standardised at the surface — every database speaks the SELECT/FROM/WHERE core — and dialect-specific underneath. Window functions, common table expressions (WITH), RETURNING clauses, JSON operators, dialect-specific casts — the formatter handles the common subset and gracefully passes through anything dialect-specific without choking on the syntax.
Subqueries and CTEs.
Inline subqueries indent under their outer clause. CTEs (WITH name AS (…)) live at the top of the query, each one on its own line, separated by commas. CTEs almost always read better than the equivalent inline subquery — they let you name an intermediate result and reference it later. The formatter doesn't rewrite subqueries into CTEs, but the formatted layout makes the difference visible at a glance.
What this isn't.
A SQL formatter is not a query optimiser. The formatted output is functionally identical to the input — same tables, same joins, same execution plan. Performance tuning is a different exercise: indexes, query plans, materialised views. The formatter just makes the input legible enough that the tuning work is easier to do.