SQL Formatter

The 200-character single line in code review

A pull request contains a one-line change, and that line is 200 characters wide. It holds three joins, four predicates and a subquery. You mean to review it, but first you have to reassemble it mentally while scrolling sideways to find where it ends. Review effectively stops there: nobody reads the line and everybody approves it. Formatting is not a matter of taste, it is what makes a query reviewable at all.

Why regular expressions cannot format SQL

Most formatters on the web run search and replace over raw text, and that leaks in three separate places. A keyword inside a string literal gets uppercased, so the query now matches a different row. A newline inserted into a -- comment either comments out real SQL or uncomments something that was meant to stay hidden. And the '' escape sequence inside a single-quoted string desynchronizes a naive quote scanner, after which every literal and keyword in the rest of the document is misclassified.

1-- Input2select * from posts where title = 'select' and note = 'it''s fine'3 4-- A regex-based formatter (corrupted)5SELECT * FROM posts WHERE title = 'SELECT' AND note = 'it''S FINE'6 7-- A tokenizing formatter (correct)8SELECT9  *10FROM11  posts12WHERE13  title = 'select'14  AND note = 'it''s fine'

One fix covers all three failures: tokenize the input once, properly, and treat string literals, quoted identifiers and comments as opaque atoms that pass through untouched. Only tokens classified as keywords are ever case-folded here, and layout decisions look at token boundaries and nothing else. The output is also idempotent, meaning formatting an already-formatted query returns identical text, which is the evidence that the tokenizer can read what it wrote.

Clause structure and better diffs

The formatter recognizes clause openers such as SELECT, FROM, WHERE, the JOIN variants, GROUP BY and ORDER BY, puts each on its own line, and indents its body one level. UNION is deliberately excluded from that indentation, because it separates two queries at the same level and indenting after it would imply a nesting that does not exist. Multi-word openers like LEFT OUTER JOIN are matched before LEFT JOIN, otherwise the shorter match wins and the leftover words land on the wrong line.

The concrete payoff of one column per line shows up in version control. Add a column to a fifty-column list that lives on a single line and the diff marks the whole line as changed, leaving the reviewer to hunt for the difference by eye. With one column per line, the addition is a single green line. The same reasoning applies to predicates separated by AND, which is why they each get their own line too.

Keyword casing and dialect differences

Uppercasing keywords is the common convention because it separates them visually from table and column names. Plenty of teams prefer lowercase, and both are technically correct: no database is case-sensitive about keywords. Consistency matters far more than the particular choice, since mixed casing produces diff noise for no benefit. The formatter only touches words in its keyword list, so a column named status or a schema named public keeps exactly the case you wrote.

Formatting does not affect performance

A recurring worry is that an indented query will run more slowly. It will not. The database parses your text into a plan, and whitespace is discarded in the first step of that parse. A one-line query and its twenty-line formatted equivalent produce the same plan and take the same time. Every bit of the benefit belongs to the human reading the query.