Why format SQL queries?
Raw SQL queries — especially those generated by ORMs, copied from log files, or written quickly during debugging — are often a single unreadable line. Formatting transforms them into structured, indented code that's dramatically easier to understand, review, and debug.
Well-formatted SQL makes the query's logical structure immediately visible: which tables are joined, what conditions filter the results, and how the output is grouped and sorted. In code reviews, formatted SQL catches logic errors that would be invisible in a dense one-liner. For complex queries with subqueries, CTEs, or window functions, formatting isn't optional — it's the difference between comprehensible code and a wall of text.
SQL formatting conventions
Uppercase keywords is the most widely adopted convention: SELECT, FROM, WHERE, JOIN, ORDER BY. This visually separates SQL syntax from table and column names, making queries scannable at a glance. Some teams prefer lowercase for a less "shouty" style — consistency within a project matters more than the choice itself.
One column per line in SELECT clauses makes it easy to add, remove, or comment out columns. It also produces cleaner diffs in version control — a single-column change shows as one line, not a rewrite of the entire SELECT list.
Indentation for subqueries and CTEs reveals the nesting structure. Each level of subquery should be indented one additional level, with the closing parenthesis aligned to the opening keyword. Common Table Expressions (CTEs) benefit from consistent indentation of their internal queries.
Leading commas (placing the comma at the start of the next line rather than at the end of the current line) is gaining popularity because it makes it trivial to comment out the last item in a list without causing a syntax error. Both styles are valid — pick one and stick with it.