SQL Formatter

What the formatter does to a query

select u.id, u.email, count(o.id) as orders from users u left join orders o on o.user_id = u.id
and o.status = 'paid' where u.active = true and u.country in ('GB','US') group by u.id, u.email
having count(o.id) > 2 order by orders desc limit 20

SELECT
  u.id,
  u.email,
  COUNT(o.id) AS orders
FROM
  users u
  LEFT JOIN orders o ON o.user_id = u.id
    AND o.status = 'paid'
WHERE
  u.active = TRUE
  AND u.country IN ('GB', 'US')
GROUP BY
  u.id,
  u.email
HAVING
  COUNT(o.id) > 2
ORDER BY
  orders DESC
LIMIT 20

The layout follows a small set of rules, applied the same way every time:

• Each clause starts a line — SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY — and its contents sit on the lines beneath, one level in.
• One item per line in a select list, a GROUP BY, an ORDER BY or a SET, with the comma at the end.
• Each join on its own line, with its ON condition beside it and any further conditions indented underneath.
• AND and OR start a line, so the conditions of a WHERE read as a list. The AND inside BETWEEN … AND … is left where it is.
• Subqueries and common table expressions are indented as blocks, with the closing parenthesis back at the outer level.
• CASE is opened up, with each WHEN and the ELSE on a line of its own.
• Function calls and IN lists stay on one line.
• Statements are separated by a blank line when the input holds several.

Comments are kept, both -- and /* */, and stay attached to the line they were on. Minify does the reverse of all this and produces one line, turning -- comments into /* */ so that they cannot swallow the rest of the statement.

Why layout matters more in SQL than most languages

A query's bugs hide in its structure. Whether a condition belongs to the JOIN or to the WHERE changes which rows a LEFT JOIN returns, and on a single line the two look the same. Laid out, the difference is one of indentation: a condition under the join filters the joined table before matching; the same condition under WHERE filters the result afterwards and quietly turns the outer join into an inner one.

The same goes for mixing AND and OR. AND binds tighter, so a OR b AND c means a OR (b AND c). With each operator starting its own line, a missing pair of parentheses is far easier to notice. And a formatted query produces useful diffs: add one column to a select list and one line changes, where the unformatted version shows the whole query as modified.

Where the SQL comes from

The usual source is something that generates SQL for you. ORMs and query builders emit a single line with machine-chosen aliases; slow-query logs and database monitoring views store statements without their original line breaks; an API that returns the query it ran in an error body does the same. Paste it here first, then read it. If the query came out of an API response, the JSON viewer will find the field, and the API tester will fetch the response.

Dialects, and what the selector changes

The formatter does not need to understand a whole dialect, only to know where a string or a quoted name begins and ends, since nothing inside one may be altered. That is the part that differs.

Choosing the wrong one matters only for input that uses those features: a MySQL string ending in an escaped quote, read as standard SQL, appears to end early and the rest of the query is misread. If the result looks wrong, or the status bar reports an unclosed string, check the dialect first.

Keyword case

SQL keywords are case-insensitive, so select and SELECT mean the same thing. Upper case is the long-standing convention because it separates the language from your table and column names at a glance; lower case is common in teams that find capitals noisy. The formatter changes only reserved words and the names of built-in functions and types where they are called. Your identifiers are never re-cased, and a column that happens to be named key, first or date is left as written.

What it does not do

• It does not validate. The formatter lays out whatever it is given and will format a query that the database would reject. It reports unbalanced parentheses and unclosed strings, because those make any layout unreliable, and nothing else. Only the database can tell you a statement is correct.
• It does not run anything. There is no connection to a database, here or anywhere.
• It does not rewrite. No aliases are added, no joins reordered, no SELECT * expanded. The self-check after each run compares the output with the input, token by token, ignoring only whitespace and keyword case, and warns if they differ.
• Procedural code is formatted loosely. Stored procedures, triggers and vendor scripting such as PL/pgSQL or T-SQL control flow are kept intact and readable, without the block-level indentation a dedicated tool would give them.

One caution if the SQL you are formatting was built by joining strings with user input: formatting it will not make it safe. Values belong in parameters — the $1, ? or :name placeholders the formatter leaves untouched — and an API that builds queries any other way is open to SQL injection, which typically surfaces as a 500 when a stray quote reaches the database.

Frequently asked questions

Related tools and reference