SQL Formatter

The query is not changed

This is the guarantee, and it is stated precisely: **whitespace and keyword case are the only things this tool alters.** Every identifier, every string literal, every number, every operator and every comment comes out exactly as it went in.

That is checkable, so it is checked. The test suite strips exactly what a formatter is allowed to change — whitespace, and the case of words that are SQL keywords — and nothing else, then asserts the result is identical for the input and the output. It runs over a corpus of fifty-one statements: subqueries, window functions, common table expressions, nested comments, dollar-quoted bodies, casts, quoted identifiers in all three styles, and a query with a syntax error in it.

Those expectations come from **sqlparse**, an independent SQL implementation in Python, rather than from a stored copy of this tool's own output. That distinction is the whole point: a test comparing a formatter to itself passes perfectly when the formatter is wrong.

What that caught

The check earned its place immediately, by finding a bug in the feature meant to improve the output. Folding a short list onto a single line joined the lines with a space, and a comment inside the list was glued to the code after it:

SELECT a, -- the first column b -- and the second
FROM t

Read that again: the identifier `b` is now inside the comment, so the query genuinely says something different. The layout feature was the cause. Comments are now excluded from the folding, and there is a test for exactly this input.

Layout is an opinion, and formatters disagree

Here is the thing worth knowing before you compare this output with another tool's. **There is no standard for SQL formatting.** The major formatters do not produce the same output for the same query, and they are not all wrong.

The most common complaint about `sqlparse`, for example, is that it breaks a two-column `SELECT` list across two lines, and that it explodes `IN (1, 2, 3)` over three. Both are layout decisions rather than errors. This tool makes the opposite choice in both cases: a list that fits the line stays on it, and a value list never breaks. You can turn that off with **One item per line**, and you can widen the wrap column.

It does not validate, and it cannot

This reformats and nothing more. Paste `select from where` and it will lay it out neatly, because **telling a broken query from an unusual one is a parser's job**, and this is a formatter.

The distinction matters more than it sounds. A tool that refused to format invalid SQL would be a validator wearing a formatter's clothes, and it would be refusing a great deal of legitimate SQL in the process: vendor extensions, a dialect you have not declared, a query with a placeholder your client library fills in. If you need to know whether your SQL is valid, run it against the database. That is the only thing that actually knows.

The dialect it assumes, and why there is no switch

This reads a double-quoted run as a **quoted identifier**, which is the ANSI rule. MySQL reads it as a **string**. Backticks and SQL Server's square brackets are read as quoted identifiers too.

There is no dialect selector, and that is deliberate. Nothing in the text distinguishes the two cases — `"x"` is the same four characters either way — so a switch would have to be set correctly by the reader, who is the only person who knows which database they are writing for. A control that cannot be right by default is worse than an assumption that is named, so the assumption is in the status bar and here.

What the layout rules *are* dialect-neutral, incidentally: they are about commas, brackets and clause keywords, and those are the same everywhere. Only the tokeniser has an opinion, and it has one.

Why there is no library behind this

The obvious choice was `sql-formatter`, and it was measured rather than assumed: about 3 MB unpacked, two direct dependencies, and one of those pulls in four more — including a command-line argument parser, a fuzzing helper and a railroad-diagram renderer, none of which a web page can use.

Because this site has no server and loads one shared script bundle on every page, that would have been a cost paid by every visitor to every page of the site, in exchange for a tool whose entire output is whitespace. The argument for a dependency is much weaker here than it is for a YAML parser: a YAML parser has to resolve tags and anchors, and getting that wrong destroys data, whereas a formatter that gets it wrong produces something ugly and obviously wrong.

The trade is real and worth naming. Hand-rolling means the keyword list is this project's, and it will not cover every vendor's reserved words. Where a word is genuinely reserved and this tool does not know it, the only consequence is that it stays lowercase — the query is unchanged either way.

The cases worth knowing about

• **Block comments nest.** PostgreSQL treats `/* a /* b */ c */` as one comment, and so does this. Some tools stop at the first `*/` and turn the rest of your file into a comment, which is a silent truncation rather than an error.
• **Dollar-quoted bodies are opaque.** `$$a; select b;$$` is one string, so the semicolon and the `select` inside it do not end the statement. A formatter that splits there will mangle a function body.
• **A doubled quote is an escaped quote.** `'it''s'` is one string, and a tokeniser that ends it at the first quote will reformat the remainder of the line as SQL.
• **An unrecognised character is passed through, not dropped.** A dialect this has never seen produces ugly output rather than a query that quietly changed.

The last one is the important one, and it is why the page can promise the query is unchanged. The alternative — skipping a character it does not recognise — would be faster to write and would be the one bug that matters.