SQL Formatter

SQL formatting is the practice of writing queries with consistent, deliberate use of whitespace, line breaks and keyword casing so that the structure of the query is visible at a glance. A formatted SELECT statement puts each major clause on its own line, indents conditions under WHERE, aligns JOIN conditions and uppercases reserved keywords so they stand out from identifiers. The goal isn't aesthetics for its own sake — it's making the query's shape legible, so a reader can see what it does before they read a single word.

The reason formatting matters more in SQL than in most languages is that SQL queries grow organically. A query that starts as a three-line SELECT picks up joins, subqueries, conditional aggregation and CTEs until it's a wall of text several hundred lines long. Without formatting discipline, the query's structure — which tables join to which, which conditions filter what, how the nesting composes — becomes invisible, and invisible structure is where bugs hide. Formatting is the difference between reading a query and archaeology.

A SQL query is a stack of clauses that execute in a fixed logical order that differs from the order they're written: FROM and JOINs determine the data set, WHERE filters rows, GROUP BY aggregates them, HAVING filters groups, SELECT picks columns, ORDER BY sorts, and LIMIT truncates. This gap between written order and execution order is the single biggest source of SQL confusion, and good formatting reinforces the logical structure — putting FROM and JOIN at the top of the statement, so the reader sees the data foundation before the transformations applied to it.

Nesting compounds the problem. Subqueries, CTEs and CASE expressions each introduce their own scope and their own logical structure, and a query mixing several levels of nesting without indentation becomes genuinely difficult to reason about — it's hard to tell which WHERE clause belongs to which subquery, or where a CASE expression ends. Formatting each nested level with consistent indentation turns an opaque block into a visual hierarchy that mirrors the query's actual scope structure.

The conventions most teams converge on: keywords in UPPERCASE (SELECT, FROM, WHERE, JOIN) to distinguish them from table and column names; one clause per line, so FROM, WHERE, GROUP BY, HAVING, ORDER BY each start a new line; lists of columns one per line when there are more than a couple; AND/OR conditions indented under WHERE; and JOIN conditions kept on the same line as the JOIN or indented beneath it. The specific choices matter far less than consistency — a codebase where every query follows the same rules is readable even if the rules differ from another codebase's.

Indentation is the backbone: nested content indents by one level (typically two or four spaces) from its parent, so subqueries and CASE branches visually sit inside their enclosing statement. Consistent indent width is part of the convention — mixed two-space and four-space indentation in the same file is worse than either choice applied uniformly, because it breaks the visual alignment that makes structure scannable. This is why formatters expose indent width as a setting: the value is a team decision, but the consistency is non-negotiable.

A common worry is that formatting changes how a query runs. It doesn't. Whitespace, line breaks and keyword case are lexically insignificant to the SQL parser — a query and its formatted version are the same query, producing the same execution plan and the same performance. The database engine normalizes whitespace before it ever plans the execution; the prettiest and ugliest formatting of a statement are, to the optimizer, byte-for-byte identical in meaning.

The real readability/performance tradeoff isn't about whitespace at all — it's about what formatting makes visible. A formatted query makes it easy to spot the performance red flags that hide in dense SQL: a WHERE clause that will prevent index use, a cross join that was meant to be an inner join, a correlated subquery executing per row, a SELECT * pulling far more columns than the query uses. Formatting doesn't make the query faster; it makes the query inspectable, and inspectable queries get optimized. The time spent formatting is repaid the first time a slow query is found in review rather than in production.

SQL is a family of dialects, not a single language. PostgreSQL, MySQL, SQL Server, Oracle and SQLite each extend the core with their own syntax — different string concatenation operators, different LIMIT/OFFSET vs TOP vs FETCH FIRST pagination, different date functions, different quoting rules for identifiers. A formatter that understands dialect differences avoids mangling constructs it doesn't recognize, and can adapt keyword lists and function formatting to the target platform. The core formatting principles are dialect-independent, but the details matter when a query uses dialect-specific syntax.

In practice, formatting pays off most in code reviews and documentation. In review, a consistently formatted query can be assessed on its logic rather than decoded first — the reviewer sees the joins, filters and aggregations directly instead of reconstructing them from a dense block. In documentation and runbooks, formatted SQL is the difference between a query a colleague can adapt and one they'll rewrite from scratch. Formatting is a communication tool: the query is read by humans far more often than it's written, and every formatting choice should serve those future readers.