SQL Formatting: Why It Matters and How to Do It Fast

Question

SQL is the language that powers most of the world's data — and it is also one of the most commonly written in the least readable way. A query that runs correctly often looks like this in the wild:

``sql

SELECT u.id,u.name,o.total FROM users u JOIN orders o ON u.id=o.user_id WHERE o.created_at>'2024-01-01' AND o.status='completed' ORDER BY o.total DESC LIMIT 50

`

Nobody reviews that in a pull request. Nobody debugs that at 2am. Formatting is not just aesthetic — it is a correctness tool.

What SQL Formatting Actually Does

A SQL formatter applies consistent rules to your query structure:

• Uppercase keywords — SELECT, FROM, WHERE, JOIN, GROUP BY stand out visually from column names and values
• Indentation — each clause starts on a new line; nested subqueries are indented further
• One clause per line — makes it easy to add, remove, or comment out individual conditions
• Aligned expressions — long SELECT lists and WHERE conditions line up vertically

The same query formatted:

<code>sql <p>SELECT</p> <p>u.id,</p> <p>u.name,</p> <p>o.total</p> <p>FROM users u</p> <p>JOIN orders o ON u.id = o.user_id</p> <p>WHERE</p> <p>o.created_at > '2024-01-01'</p> <p>AND o.status = 'completed'</p> <p>ORDER BY o.total DESC</p> <p>LIMIT 50</p> </code>

The logic is identical. The readability is not.

Dialect Differences Matter

SQL has a standard, but every major database deviates from it. Formatting should reflect the dialect your team uses:

| Database | Notable formatting differences |

|----------|-------------------------------|

| MySQL | BACKTICK identifiers, LIMIT n, m syntax |

| PostgreSQL | $$ dollar-quoting, :: cast syntax |

| SQL Server / T-SQL | [BRACKET] identifiers, TOP n instead of LIMIT |

| BigQuery | Backtick identifiers, STRUCT and ARRAY types |

| SQLite | Minimal type system, AUTOINCREMENT quirks |

A good formatter understands which keywords are dialect-specific and won't flag them as errors.

When to Format

Code review — unformatted SQL in a migration or stored procedure is a review blocker. Format before you commit.

Debugging — when a query returns wrong results, formatting it makes the logical structure visible. Missing parentheses, wrong JOIN conditions, and misplaced AND/OR groupings reveal themselves immediately.

Refactoring — adding a new JOIN or changing a WHERE clause is far easier on formatted code. You can see exactly where to insert the new clause.

Sharing with a DBA — formatted queries communicate intent. A DBA who can't parse your query can't help you optimise it.

Legacy code review — inherited scripts often look like one long line. Format them first, understand them second.

Inline vs. Standalone Formatting

For day-to-day development: most IDEs have SQL formatting built in (VS Code SQLTools extension, DataGrip's built-in formatter, DBeaver's Ctrl+Shift+F). Set a standard style in your team's .editorconfig or IDE settings and format on save.

For quick ad-hoc formatting (a query from a log, a schema from Stack Overflow, a vendor-supplied migration): a browser-based tool is fastest. No configuration, no install, paste and go.

Building a Team SQL Style Guide

Consistent formatting is more important than which convention you choose. A short style guide prevents formatting debates in code review and makes automated formatting enforceable:

1. Keyword case: UPPERCASE keywords (near-universal convention)
2. Identifier case: lowercase table and column names
3. Indentation: 2 or 4 spaces (pick one, enforce it)
4. Join style: explicit JOIN always (never implicit comma-joins)
5. Trailing comma vs leading comma: leading commas ( , column_name) help with git diffs — controversial but worth a team discussion

Document the guide in your repo's README or a CONTRIBUTING.md and point your formatter configuration at it.

SQL Formatting in CI

For teams serious about consistency, format checking can run in CI:

• sqlfluff — Python-based SQL linter + formatter with dialect support and CI integration
• pgFormatter — PostgreSQL-specific, used in pre-commit hooks
• prettier-plugin-sql — Prettier plugin for SQL files

A CI gate that rejects unformatted SQL is the same pattern as eslint or black` for JavaScript or Python. It removes the "formatting nit" category from code reviews entirely.

Try It in Your Browser

If you need to quickly format a query without installing anything, SnappyTools provides free, browser-based tools for developers. All processing happens in your browser — no code is sent to a server.

Clean queries are debuggable queries. Format early, format consistently, and your future self (and your teammates) will thank you.

Originally published at https://snappytools.app/