The worst query I ever had to review was 340 lines on a single logical thought: a revenue report for a Laravel SaaS, written as one DB::select() raw string, built up over eight months by three developers who each had a different idea about capitalization and none about line breaks. Somewhere in that wall of text, a LEFT JOIN had quietly become an INNER JOIN during a refactor, and customers with zero orders vanished from the report. The bug was one word. Finding it took a day and a half — not because the logic was hard, but because the query was unreadable, and unreadable code hides its bugs in plain sight.
Here's the thing about SQL: the database does not care about your formatting. The parser reads select id,name from users where active=1 and SELECT id, name FROM users WHERE active = 1 as the same statement, produces the same execution plan, returns the same rows in the same time. Formatting SQL is purely for humans — which is exactly why it's worth doing, because humans are the ones who review it, debug it at 2 AM, and inherit it three jobs later. A query you can't skim is a query you can't verify.
An SQL formatter turns any query — pasted from a log, an ORM's debug output, a coworker's Slack message, a legacy stored procedure — into consistently indented, consistently cased, reviewable SQL in one click. The one on toolz.dev runs entirely in your browser, which matters more for SQL than for almost any other text you'd paste into an online tool, because production queries carry your schema and sometimes your data.
This guide covers how to use it, the formatting conventions that actually matter (keyword casing, indentation, and the eternal comma war), and the workflows where a formatter pays for itself daily.
TL;DR: Paste any query into the toolz.dev SQL Formatter and get back consistently indented, keyword-cased SQL — instant, free, client-side, no signup. Formatting never changes what a query does or how fast it runs; it changes whether a human can verify it. Conventions worth adopting: uppercase keywords, one clause per line, indent under each clause, and pick a comma style and stop arguing about it. Pair it with the JSON Formatter for the API layer above your database and the Text Diff tool for comparing two versions of a query.
Key Features
One-Click Consistent Indentation
The formatter's core move: each major clause — SELECT, FROM, WHERE, GROUP BY, ORDER BY — starts its own line, with columns, conditions, and joins indented beneath. This is the "river" structure experienced SQL readers scan by: the eye runs down the left edge reading clause keywords, then dives into whichever clause matters. A 60-line formatted query with clear structure reviews faster than a 6-line unformatted one, because the structure is doing half the reading for you. My 340-line horror story would have been a twenty-minute review with this shape — the changed join type would have sat alone on its own line, visibly wrong.
Keyword Case Normalization
SELECT versus select genuinely doesn't matter to any database — SQL keywords are case-insensitive per the standard, and every dialect honors that. It matters enormously to a codebase, though, because mixed casing is visual noise that makes structurally identical queries look different. Uppercase keywords are the older convention, dating from editors without syntax highlighting, where SELECT in caps was the highlighting. I still write uppercase — keywords pop against lowercase identifiers, and it survives every context that strips highlighting: logs, diffs, plain-text email, terminal output. The formatter normalizes to your chosen convention so a codebase written by five people reads like it was written by one.
Handles ORM and Log Output
The queries most in need of formatting are the ones no human wrote: Eloquent and ActiveRecord output, Doctrine's generated joins, the single-line monsters in your slow-query log. ORM output arrives as one line with machine-generated aliases (t0, t1, laravel_reserved_0), and reading it raw is how you get headaches. My single most frequent use of the formatter: grab the query from Laravel's query log or Telescope, format it, and actually see what the ORM decided to do — which is the first step of every "why is this endpoint slow" investigation, right before EXPLAIN.
Multi-Dialect Tolerance
Real-world SQL is a family of dialects: MySQL's backtick-quoted identifiers, PostgreSQL's double quotes and :: casts, SQL Server's square brackets and TOP, SQLite's easygoing everything. A useful formatter handles all of them without demanding you declare a dialect first, preserving dialect-specific syntax rather than "correcting" it. The ANSI/ISO SQL standard (ISO/IEC 9075) defines the common core, but nobody writes pure standard SQL in practice, and a formatter that only speaks the standard would choke on the first backtick.
Preserves Semantics, Guaranteed
Worth stating explicitly because it's the fear that stops people: formatting cannot change results. Whitespace and keyword case are not semantic in SQL — the one historical caveat being that string literals are compared case-sensitively or not depending on your collation, and a formatter never touches the inside of your quoted strings. The output is the same statement, byte-for-byte where bytes matter. Run EXPLAIN on both versions if you want to see it: identical plans.
Client-Side, Which Actually Matters Here
SQL is the most sensitive text category that routinely gets pasted into online tools. Queries reveal your schema — table names, column names, relationships — and queries copied from logs frequently contain literal values: emails in WHERE clauses, ID ranges, occasionally something that should never have been in a query string at all. The toolz.dev formatter processes everything in your browser; nothing is transmitted. For SQL specifically, I'd call client-side processing a requirement, not a feature — verify it in the Network tab and then relax.
How to Use the SQL Formatter
Step 1: Capture the Query
Copy the SQL from its source: your migration file, a stored procedure, the ORM's debug output (DB::listen() or Telescope in Laravel, ActiveRecord::Base.logger in Rails), the slow-query log, or the query tab of your APM tool. If it came from a log, it may have escaped quotes or parameter placeholders (?, $1) — that's fine, formatters handle placeholders, and seeing them clearly is often the point.
Step 2: Paste and Format
Open the SQL Formatter, paste, and the formatted version appears. No dialect ceremony, no configuration required to get a good default. If your query includes multiple statements separated by semicolons, they format as separate statements — useful for reading migration scripts whole.
Step 3: Read It Like a Reviewer
Now do the thing formatting exists for: scan the left edge. Which tables are joined, and with which join types? Does the WHERE clause have the conditions you expect — and are the AND/OR groupings parenthesized the way you think they group? (Operator precedence in SQL puts AND before OR, and unparenthesized mixes of the two are the second-biggest bug source I see in review, right after wrong join types.) Formatted SQL makes both mistakes visible in seconds.
Step 4: Copy It Back — Selectively
For queries headed into your codebase, copy the formatted version into the migration, the ->select() raw expression, the .sql file. For one-off debugging, don't bother round-tripping; the formatted copy served its purpose the moment you read it. One place not to paste formatted SQL: back into systems that store queries as configuration strings where someone's diff tooling will now show a wall of whitespace changes. Format for reading always; reformat stored queries only when you're prepared to own the diff.
Step 5: Standardize the Team Convention
The formatter's biggest value is compounding: pick the conventions you can automate — keyword case and indentation width are the two this formatter controls directly — format everything new on the way into the codebase, and SQL review friction drops permanently. Write the choice down in your contributing guide. The specific convention chosen matters far less than everyone using the same one — a sentence that is true of every formatting debate in software and believed by approximately nobody mid-debate.
Technical Deep Dive: The Conventions Worth Having Opinions About
Keyword casing. Uppercase keywords, lowercase identifiers is the dominant convention and my recommendation. The argument isn't tradition — it's robustness. Syntax highlighting disappears in logs, terminals, code review comments, and Stack Overflow answers pasted into Slack; uppercase keywords are highlighting that travels with the text. The counterargument (lowercase everything, let the editor highlight) is coherent and I've worked in codebases that used it happily. What's not coherent is mixing, which is what you get without a formatter enforcing the choice.
One clause per line, indented contents. The structural rule with the highest payoff. SELECT starts a line; its columns are indented below (or on the same line if short). Each JOIN gets its own line with its ON condition visible — join conditions hidden mid-line are where wrong-join bugs hide. WHERE conditions stack one per line, aligned, with AND/OR leading each line so the logical structure reads vertically. When a query's conditions read as a column, a missing condition is visible as a gap in a pattern, which human eyes are exceptionally good at spotting.
The comma war. Trailing commas (after each column) read naturally; leading commas (before each column, at line start) make the punctuation structural:
-- Trailing (most common)
SELECT
u.id,
u.email,
o.total
-- Leading (the DBA classic)
SELECT
u.id
, u.email
, o.total
Leading-comma advocates have two genuinely good points: commenting out any line except the first never breaks the statement, and a missing comma is instantly visible at the left margin. Trailing-comma advocates have one: it looks like every other language you write. I write trailing commas and have stopped feeling bad about it — but note that SQL, unlike modern JavaScript or Python, does not forgive a dangling comma after the final column, which is why this debate exists at all and why the leading style refuses to die in DBA circles. Full disclosure: the toolz.dev formatter takes the mainstream side and emits trailing commas — it has no leading-comma mode, so if you're a committed leading-comma shop this is the one convention it won't reformat for you. Pick a house style, apply it consistently, and move on.
What formatting does not do. It doesn't optimize. A formatted SELECT * across a five-table join is a beautifully indented performance problem. Formatting is the precondition for optimization — you cannot reason about a query you cannot read — but the reasoning still requires EXPLAIN, index awareness, and knowing your data's shape. I think of the pipeline as: format, read, EXPLAIN, then optimize. Skipping step one doesn't make you faster; it makes steps two through four slower. The same discipline applies one layer up at the API, which is why the JSON formatter guide makes a structurally identical argument about payloads.
Comments survive. Unlike minification, formatting preserves comments — -- line comments and /* */ blocks come through intact. Use them. A -- deliberately LEFT JOIN: include customers with no orders comment above a join is the cheapest bug insurance ever written, and it's the comment my 340-line horror story needed.
Common Use Cases
Code Review
Unformatted SQL in a pull request is a review that isn't going to happen — the reviewer's eyes slide off the wall of text and the approval lands anyway. Formatting the query before opening the PR is basic courtesy with measurable payoff: join types, condition groupings, and column lists become individually visible, which means they become individually reviewable. Every genuine SQL bug I've caught in review — the wrong join, the unparenthesized OR, the DELETE missing half its WHERE clause — I caught because the query was formatted well enough to read line by line.
Debugging ORM-Generated Queries
ORMs are wonderful right up until the endpoint is slow, at which point you need to see the actual SQL — and ORM output is always one dense line. Format it and the story appears: the N+1 that eager loading missed, the join the relationship definition silently added, the ORDER BY on an unindexed column. In Laravel work this is a several-times-weekly ritual: Telescope, copy, format, wince, fix the Eloquent code, repeat. The formatter doesn't diagnose anything itself; it makes the query legible enough that you can.
Archaeology on Legacy Queries
Every long-lived system has them: the stored procedure from 2015, the reporting view nobody dares touch, the query embedded in a config file with the original author's formatting (i.e., none). Before modifying legacy SQL, format it and read it end to end — you'll routinely find conditions that can't ever be true, joins to tables that no longer receive writes, and logic the current team's assumptions contradict. Formatting first turns "scary legacy query" into "long but legible query," which is a different and better problem.
Comparing Query Versions
When a report's numbers change between releases, the question is "what changed in the query," and the answer requires diffing two versions — which only works if both are formatted identically first. Format both with the same settings, then run them through the Text Diff tool: the noise disappears and the two changed lines stand alone. This exact sequence found my inner-join bug, eventually. I now do it before the day and a half of confusion instead of after.
Teaching and Documentation
SQL in tutorials, runbooks, and internal docs gets read many more times than it gets written, by readers less familiar with the schema than the author. Formatted examples with uppercase keywords and one-concept-per-line structure are dramatically easier to learn from — the structure teaches alongside the content. When I write documentation with embedded queries, every one goes through the formatter first; unformatted SQL in docs tells the reader the author didn't expect anyone to actually read it.
Formatting Conventions Compared
| Convention choice | Option A | Option B | My take |
|---|---|---|---|
| Keyword case | SELECT (uppercase) |
select (lowercase) |
Uppercase — survives contexts without highlighting |
| Identifier case | snake_case | Match table definitions | Match definitions; never fight the schema |
| Commas | Trailing (id,) |
Leading (, id) |
Trailing, but leading is defensible — just pick one |
| Clause layout | One clause per line | Compact single line | One per line for anything past trivial |
AND/OR placement |
Leading each condition line | Trailing previous line | Leading — logic reads vertically |
| Join conditions | ON on its own line or inline with JOIN |
Buried mid-line | Visible with the join, always |
| Indent width | 2 spaces | 4 spaces | Either; SQL nests less than JSON, so 4 is fine here |
None of these rows has a wrong answer, and that's precisely the trap — because every option is defensible, teams re-litigate them forever unless a formatter makes the decision mechanical. The winning move is boring: choose, configure, format everything, and spend the reclaimed argument time on things that affect the execution plan. For the rest of the daily toolkit around this one, see the coding tools guide and the broader web developer toolkit.
FAQ
What does an SQL formatter do?
An SQL formatter rewrites a query's whitespace, line breaks, and keyword casing into a consistent, readable structure — each clause on its own line, conditions and columns indented, keywords normalized to one case. The statement's meaning is untouched: SQL parsers ignore formatting entirely, so the formatted query returns identical results with an identical execution plan. The change is purely for the humans who review, debug, and maintain the query.
Does formatting SQL change query performance?
No. Whitespace and keyword case are not semantic in SQL — the database parses both versions into the same internal representation and produces the same execution plan, which you can verify by running EXPLAIN on each. Formatting is the precondition for performance work rather than performance work itself: you can't reason about indexes and join order in a query you can't read.
Should SQL keywords be uppercase or lowercase?
Both are valid — SQL keywords are case-insensitive per the standard — so this is a readability convention, not a correctness rule. Uppercase keywords (SELECT, FROM, WHERE) remain the most common choice because they act as built-in highlighting in contexts that strip colors: logs, diffs, terminals, and plain-text messages. Whichever you choose, consistency across the codebase matters far more than the choice itself.
What are leading commas in SQL and why do people use them?
Leading-comma style places the comma at the start of each column line (, email) instead of the end of the previous one. Advocates like it because commenting out any column except the first never produces a syntax error, and missing commas are instantly visible at the left margin — real advantages, since SQL doesn't tolerate a dangling comma after the final column the way modern JavaScript does. Trailing commas remain more common; either works if applied consistently.
Can I format SQL generated by an ORM like Eloquent or ActiveRecord?
Yes, and it's one of the best uses of a formatter — ORM debug output arrives as a single dense line with machine-generated aliases, and formatting it is the first step of diagnosing slow endpoints and N+1 problems. Capture the query from your ORM's logging (Laravel Telescope, ActiveRecord logs), paste it into the SQL Formatter, and read what the ORM actually built before reaching for EXPLAIN.
Does the formatter work with MySQL, PostgreSQL, and SQL Server syntax?
Yes — practical formatters handle the major dialects' quirks, preserving MySQL backticks, PostgreSQL double-quoted identifiers and :: casts, and SQL Server square brackets rather than rewriting them. The ANSI SQL standard defines the shared core, but no production database speaks pure standard SQL, so dialect tolerance is a requirement for a formatter to be useful on real queries.
Is it safe to paste production queries into an online SQL formatter?
Only into a client-side one, because SQL is unusually sensitive: queries expose your schema, and queries copied from logs often contain literal values like emails or IDs in WHERE clauses. The toolz.dev SQL Formatter processes everything in your browser with nothing transmitted or stored — verify it yourself by watching the Network tab while you paste. Avoid server-based formatters for anything from production.
Does formatting preserve SQL comments?
Yes — both -- line comments and /* */ block comments pass through intact, unlike minification, which deletes them. This makes formatting safe for annotated queries and stored procedures where comments carry intent. Use that: a one-line comment explaining a deliberate LEFT JOIN or an unusual condition is the cheapest protection against the next developer "fixing" something that wasn't broken.
