How to Format SQL: A Guide to Readable, Reviewable Queries

Why SQL formatting matters

A SQL query that returns the right rows can still be a problem. Databases do not care about whitespace or capitalisation — select id from users where active=1 runs identically to a neatly indented version. But people care. Most of the cost of a query happens after it works: someone reviews it in a pull request, someone debugs it six months later, someone copies it into a runbook. All of that is reading, and unformatted SQL is hard to read.

The classic offender is the one-line query. A SELECT with five columns, two JOINs, a WHERE with three conditions, and a GROUP BY crammed onto a single line forces the reader to mentally parse where each clause begins and ends. Formatting solves this by giving structure a visual shape: each major clause starts a new line, and the things that belong to a clause are indented under it. Once your eye learns that shape, you can scan a query and find the JOIN conditions or the filters instantly.

If you just want clean SQL right now, paste it into the free SQL Formatter and copy the result. The rest of this guide explains the conventions it applies, so you understand why the output looks the way it does.

The core conventions

One major clause per line

The single most valuable rule is to put each top-level clause on its own line:

SELECT id, name
FROM users
WHERE active = 1
ORDER BY name

The clauses SELECT, FROM, WHERE, JOIN, GROUP BY, ORDER BY, HAVING, LIMIT, and UNION are the skeleton of almost every query. When each one starts a fresh line, the reader can see the whole shape at a glance — which tables, which filters, which ordering — without reading a word of the actual columns.

Indent what belongs to a clause

The second rule is indentation. The columns in a SELECT, the conditions after a JOIN ... ON, and the predicates joined by AND/OR all belong to a clause, so they sit indented underneath it:

SELECT
  u.id,
  u.name,
  o.total
FROM users u
INNER JOIN orders o
  ON u.id = o.user_id
WHERE u.active = 1
  AND o.total > 100
ORDER BY o.total DESC

Now the relationship is obvious: o.total > 100 is clearly a filter, the ON clause clearly belongs to the join, and the three selected columns line up so you can scan them vertically. This is exactly the layout the SQL Formatter produces, with your choice of two spaces, four spaces, or a tab as the indent unit.

Consistent keyword casing

SQL keywords are case-insensitive, so SELECT, select, and Select are all valid. The convention most teams follow is uppercase keywords, because capitalised SELECT/FROM/WHERE stand out against lowercase table and column names, making the structure pop. Some modern style guides prefer all-lowercase for a calmer look. Neither is wrong — the only mistake is mixing them within a codebase. A formatter lets you pick one and enforce it on every query, so you never argue about it in review again.

What a formatter must not change

Here is the subtle part. A naive formatter that just searches for the word “select” and uppercases it will eventually corrupt a query. Consider this:

SELECT 'select all rows' AS note FROM logs -- select the latest

The word select appears three times, but only the first is a keyword. The second is inside a string literal ('select all rows') and the third is inside a comment. A correct formatter must leave both of those completely untouched — changing the casing of text inside a string would change the data your query produces, and rewriting a comment is just rude.

The way to get this right is to tokenise the SQL before formatting it. Tokenising means scanning the raw text once and classifying every piece into a type: keyword, identifier, string literal, number, operator, punctuation, or comment. Once each piece is labelled, the formatter only re-cases tokens labelled “keyword” and only reflows whitespace between tokens. String literals and comments are emitted verbatim, exactly as written. This is the same tokenise-then-transform approach used by other structural converters such as the ones described in the JSON to CSV guide — understand the structure first, transform second.

The Tools.Town SQL Formatter works exactly this way, which is why 'select all rows' and the trailing comment come back identical no matter how you set the casing option.

A worked example

Start with a realistic mess — the kind of query that arrives pasted from an ORM log or a teammate’s clipboard:

select u.id,u.name,o.total from users u inner join orders o on u.id=o.user_id where u.active=1 and o.total>100 order by o.total desc limit 10

It runs, but reviewing it is unpleasant. Run it through the formatter with uppercase keywords and a two-space indent and you get:

SELECT
  u.id,
  u.name,
  o.total
FROM users u
INNER JOIN orders o
  ON u.id = o.user_id
WHERE u.active = 1
  AND o.total > 100
ORDER BY o.total DESC
LIMIT 10

Same query, same result set, but now anyone can see in two seconds that it selects three columns, joins users to their orders, filters to active users with large orders, and returns the top ten by total. That is the entire point of formatting: the database reads the first version just fine, but the human reads the second.

Where formatting fits in your workflow

There are three high-value moments to format SQL:

1. Before a pull request. Format the query so reviewers spend their attention on the logic, not on decoding the layout. Consistent formatting also produces smaller, cleaner diffs — only the lines you actually changed show up, instead of a whitespace storm.
2. When debugging a generated query. ORMs, BI tools, and query builders emit dense, machine-friendly SQL. Pasting it into a formatter is often the fastest way to understand what was actually sent to the database.
3. When documenting. A query in a runbook, ticket, or wiki should be formatted, because the reader has no editor to reflow it for them.

For a one-off, the browser tool is all you need. For a whole team, the natural next step is a shared style enforced automatically — saved formatting profiles, batch-formatting a folder of .sql files, and a CLI you can wire into CI so unformatted SQL never lands in the repo. Those are the planned SQL Formatter Pro features; the single-query formatter stays free for everyone.

Key takeaways

• Formatting changes only whitespace and keyword casing, never the result of the query.
• The two rules that buy the most readability are one major clause per line and indenting what belongs to a clause.
• Pick a keyword casing — uppercase or lowercase — and apply it consistently.
• A correct formatter tokenises first, so it never touches the inside of string literals or comments.

Clean SQL is not vanity; it is the difference between a query a teammate can review in thirty seconds and one they have to puzzle over. Format it once, copy it back, and move on.