SQL Formatter: Make Any Query Readable

Why a formatter has to tokenize before it reformats

Most quick-and-dirty SQL beautifiers are a stack of regular expressions run over the raw text: uppercase anything that looks like a keyword, break a line before every FROM, collapse runs of whitespace. That works right up until the query contains a string, and then it quietly edits your data. The classic failure looks like this:

-- what you wrote
WHERE note = 'select from where order by'

-- what a regex formatter gives back
WHERE note = 'SELECT
FROM WHERE ORDER BY'

The comparison now fails against every row, and nothing errors. The fix is structural, not a longer regex: read the input character by character into typed tokens first — whitespace, line comment, block comment, string, quoted identifier, number, word, punctuation — and only then decide where the line breaks go. Four of those token types are emitted verbatim, so no layout rule can ever reach inside them. Here is the same query through this tool:

SELECT
  *
FROM t
WHERE note = 'select from where order by'
  AND tag = 'it''s fine';

The keywords inside the quotes stay lowercase and on one line, and 'it''s fine' is understood as one string containing an escaped quote rather than two strings with stray text between them. The same protection covers -- and /* */ comments, backtick and bracket identifiers, and PostgreSQL $$dollar-quoted$$ blocks.

The house style: what gets its own line

The layout here is opinionated on purpose. Leading keywords sit at column zero so you can read the shape of a statement down the left edge; selected columns get one line each so adding a column is a one-line diff; join conditions and boolean operators are indented one level under the clause they belong to. This is the full rule set:

Indentation is 2 spaces, 4 spaces, or a tab, your choice. The minify mode applies the same tokenizer in reverse — one line, single spaces, nothing removed — with one exception: a -- comment keeps its newline, because collapsing it would comment out the rest of the statement.

The same query, before and after

This is what comes out of an ORM log, a stack trace, or a colleague’s chat message — a real query with three tables in it, on one line:

select o.id, c.name, sum(l.qty*l.price) as total from orders o join customers c on c.id=o.customer_id left join order_lines l on l.order_id=o.id where o.status='paid' and o.created_at >= '2026-01-01' group by o.id, c.name having sum(l.qty*l.price) > 100 order by total desc limit 20;

And this is the same query, unchanged in every way that matters, after formatting with uppercase keywords and 2-space indents:

SELECT
  o.id,
  c.name,
  sum(l.qty * l.price) AS total
FROM orders o
JOIN customers c
  ON c.id = o.customer_id
LEFT JOIN order_lines l
  ON l.order_id = o.id
WHERE o.status = 'paid'
  AND o.created_at >= '2026-01-01'
GROUP BY o.id, c.name
HAVING sum(l.qty * l.price) > 100
ORDER BY total DESC
LIMIT 20;

Notice what did not change: sum is still lowercase because it is a function name, not a reserved word, and the GROUP BY list stayed on one line. Fourteen lines instead of one, and now you can see at a glance that there are two joins, both with an ON clause.

Formatting is a code-review tool, not decoration

A one-line query is unreviewable. Nobody reads 400 characters of horizontal text carefully, and in a pull request a one-line query produces a one-line diff: change a join condition and the reviewer sees the entire query marked as modified, with no way to tell what actually moved. Break it into clauses and the diff shrinks to the line that changed. That alone is worth the habit — commit your SQL formatted, and format it the same way every time so the diffs stay honest.

The most valuable thing formatting surfaces is the accidental cross join. Two tables listed in FROM separated by a comma, with no join condition, produce every row of one paired with every row of the other — 10,000 customers and 500 products is five million rows. In a wall of text it is invisible. On its own line it is obvious:

SELECT
  c.name,
  p.title
FROM customers c, products p
WHERE c.active = 1;

The tell is a FROM line carrying two comma-separated tables with no JOIN and no indented ON beneath it. The formatter does not flag this — it has no idea whether you meant it — but it puts the evidence where a human will see it. The same goes for a WHERE clause whose AND conditions stack vertically: a missing condition is a missing line, and missing lines are easy to notice.

Identifier quoting and quote escaping, dialect by dialect

The reason a shared formatter has to be dialect-agnostic is that the four mainstream databases disagree about the two characters that matter most to a tokenizer: what quotes an identifier, and how you put a quote inside a string. All of the forms below are recognised and passed through untouched.

• Double quotes are the trap. In PostgreSQL, SQLite and the SQL standard, "x" is an identifier. In MySQL’s default mode it is a string, unless the server is running in ANSI_QUOTES mode. The same character means two different things, which is exactly why a formatter cannot assume a dialect.
• Backslash escapes are MySQL-flavoured. MySQL treats \' as an escaped quote by default; PostgreSQL does not inside an ordinary string, only inside an E'...' string. This tool honours the backslash form, which is the safe direction to be wrong in — see the failure note below.
• Case folding differs too. PostgreSQL lowercases unquoted identifiers, so Email and email are the same column but "Email" is not. The formatter never changes the case of an identifier, quoted or otherwise, precisely because that decision is not safe to make for you.
• PostgreSQL dollar quoting is handled. $$...$$ and $tag$...$tag$ blocks — the usual way to write a function body — are captured whole and emitted verbatim, so the SQL inside a function body is never reformatted out from under you.

If you are writing the schema rather than querying it, the sibling SQL CREATE TABLE generator does know about dialects: you design a table visually and it emits DDL with the correct identifier quoting, auto-increment syntax and type names for PostgreSQL, MySQL, SQLite or SQL Server. And if you are still deciding whether SQL is the right store at all, SQL vs NoSQL covers that trade-off.

What it will not do, and how it fails when it fails

This is a text formatter. It does not parse SQL into a syntax tree, so it cannot validate a query, cannot lint it, cannot suggest an index, cannot rewrite a subquery as a join, and cannot tell you anything about the execution plan. A query it lays out beautifully may still be rejected by your database on the first line. Run EXPLAIN against the real thing for anything performance-related — no browser tool can know your table sizes or your indexes.

Because it is dialect-agnostic, there are inputs where the tokenizer guesses wrong. Two worth knowing about, both PostgreSQL-flavoured:

• A # is read as the start of a MySQL line comment, so the PostgreSQL JSON path operators #> and #>> cause the rest of that line to be treated as comment text.
• A backslash immediately before a closing quote is read as an escape, so a literal Windows path like 'C:\' in a standard-conforming PostgreSQL string makes the tokenizer run on to the next quote.

In both cases the failure mode is the same and it is the important part: the affected text stops being formatted, and is copied out unchanged. You get a query that looks half-formatted, which is visible and fixable, rather than a query that looks perfect and means something different. A formatter that fails loudly is worth more than one that fails silently — which is the whole argument of this page. As a habit, glance at the output before you run it, the same way you would glance at any diff.

Frequently asked questions