SQL style guide: formatting queries for review

The most valuable rule is also the simplest: start every major clause on a new line. SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY and LIMIT each get their own line, and the content of the clause is indented beneath it. A reader can then scan down the left edge and see the structure of the query before reading any detail.

This layout also produces better diffs. When someone adds a filter, the change appears as one new line under WHERE instead of a modification in the middle of a 300-character line. Reviewers see exactly what changed, and version control can merge two unrelated edits to the same query without a conflict.

List one column per line once the select list has more than two or three items. A vertical list makes it obvious when a column is duplicated, when an alias is missing, or when an aggregate has slipped into a list that should only contain grouping keys.

Trailing commas, placed at the end of each line, are the most common style and read naturally. Leading commas, placed at the start of the next line, look odd at first but have a practical advantage: you can comment out or append the last column by touching a single line, and a forgotten comma is visible in the left margin. Both are fine; what matters is that a whole codebase uses one of them. TidySQL can produce either.

Write every join on its own line with the join type spelled out: INNER JOIN, LEFT JOIN, never a comma-separated list of tables in FROM with the join conditions buried in WHERE. Explicit joins keep the relationship between two tables next to the tables themselves, which is where a reviewer looks for it.

In WHERE and ON clauses, put each condition on its own line and start continuation lines with AND or OR. Leading boolean operators make the logic scannable and expose precedence mistakes: a line starting with OR among several AND lines is a strong hint that parentheses are missing. Be explicit with parentheses whenever AND and OR are mixed, even if you know the precedence rules.

Uppercase keywords are a convention from the days before syntax highlighting, when capital letters were the only way to separate SQL words from table and column names. They are still common and still useful in plain-text contexts such as logs, tickets and emails. Lowercase keywords are popular in codebases where editors highlight SQL anyway. Pick one and apply it everywhere; mixed case is the only wrong answer.

For identifiers, lowercase snake_case avoids the need for quotes in almost every database. PostgreSQL folds unquoted names to lowercase, so a table created as "OrderItems" must be quoted forever after. Keep table aliases short but meaningful, such as o for orders and oi for order_items, and avoid single letters that have no relation to the table name.

Two or four spaces both work; tabs work if everyone's editor agrees on their width. The real rule is that nesting in the text must follow nesting in the query. A subquery in FROM or WHERE is indented one level deeper than the clause that contains it, and its closing parenthesis returns to the outer level.

When a subquery grows beyond a few lines, consider moving it into a common table expression with WITH. A CTE gives the intermediate result a name, lets you read the query top to bottom, and is formatted exactly like a top-level SELECT. Most modern engines, including PostgreSQL 12 and later, optimise simple CTEs as well as inline subqueries.

Style rules that depend on people remembering them drift within weeks. The reliable approach is to agree on a handful of settings — dialect, keyword case, indent width, comma position — and run every query through the same formatter before it is committed or shared. Debates in code review then move from whitespace to logic.

TidySQL exposes exactly those settings. Paste a query, choose the options your team agreed on, and the output is the same every time for the same input. Because it runs in the browser, it is also safe for queries that contain production table names or literal customer data.