How to Format SQL Queries

Messy SQL is one of the fastest ways to introduce bugs. When a query is a single long line with no indentation, it is hard to see which conditions apply to which joins, where subqueries begin and end, or whether the logic is correct. A browser-based formatter handles the entire job locally without uploading your queries to a server.

Why formatting matters

• Debugging: a well-formatted query makes logic errors visible. You can trace the flow from SELECT to WHERE to JOIN without guessing.
• Code review: reviewers can read formatted SQL in seconds. A single-line query forces them to mentally parse it first.
• Maintenance: when you revisit a query months later, formatting tells you what it does at a glance.
• Collaboration: consistent formatting across a team means everyone reads SQL the same way.
• Onboarding: new team members can read formatted SQL without needing oral history of every query.
• Documentation: when SQL appears in design docs, runbooks, or wikis, formatted queries are easier for non-developers to follow.
• Version control diffs: formatted SQL produces cleaner diffs when you change one clause without reformatting the whole query.

How to format SQL

1. Paste your SQL: enter a minified or messy query into the formatter. It handles SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, and complex queries with subqueries and joins.
2. Configure options: choose indentation size and whether to uppercase keywords. These settings match your project's style guide.
3. Copy the result: the formatted SQL is ready to paste back into your editor, database client, or documentation.

What good formatting looks like

A query like select u.name, o.total from users u join orders o on u.id = o.user_id where o.total > 100 and u.active = 1 order by o.total desc becomes:

SELECT
  u.name,
  o.total
FROM users u
JOIN orders o
  ON u.id = o.user_id
WHERE o.total > 100
  AND u.active = 1
ORDER BY o.total DESC

Each clause starts on its own line. Conditions are indented under their parent clause. Joins and their ON conditions are clearly paired.

A brief history of SQL formatting conventions

SQL was created by IBM researchers Donald Chamberlin and Raymond Boyce in 1974, originally called SEQUEL (Structured English Query Language). The "QL" in the original name reflected an intent for the language to read like English. From the very beginning, this human-readable design implied a convention: indent your clauses so they read top-to-bottom like sentences.

For most of the 1980s and 1990s, SQL was written by hand in text editors and the formatting was personal. Some shops adopted "river style" (where every keyword aligns vertically on the right of a virtual column), others used "Egyptian style" (curly-brace-on-same-line equivalent), and most just used whatever the author preferred.

The first widely-used SQL formatter was Apex SQL Formatter (2000), followed by Devart's SQL Complete (2002) and Red Gate's SQL Prompt (2003). These tools brought IDE-level formatting to SQL Server and Oracle developers. By 2010 every major IDE (SSMS, DataGrip, DBeaver) had built-in SQL formatting, and online formatters became standard for ad-hoc cleanup.

In 2017 the formatter ecosystem shifted with sql-formatter (npm), an open-source JavaScript library that powers most browser-based SQL formatters today, including this one. Modern formatters handle dialect differences (MySQL backticks, PostgreSQL window functions, SQL Server square brackets) and produce consistent, configurable output.

SQL style guides used by major companies

Most professional codebases follow one of several published SQL style guides:

If you are starting a new project, pick one of the established guides. If you are joining an existing codebase, follow what is already there. Consistency within a project matters more than any specific style.

Common formatting choices

• Keyword case: UPPERCASE (most common, makes keywords visually distinct), lowercase (modern dbt/Snowflake style), or original case (some IDEs preserve what you typed).
• Identifier case: snake_case is the default in PostgreSQL and most Unix-friendly databases; PascalCase or camelCase in Oracle/SQL Server traditions.
• Indentation: 2 spaces (compact, fits in 80-char terminal), 4 spaces (matches most code style guides), or tabs (rare in SQL).
• Comma placement: trailing commas (after each column on a separate line) or leading commas (comma at the start of the next line, easier to add/remove columns).
• Line length: 80 chars (terminal-friendly), 120 chars (modern IDE default), or unlimited (less common in production).
• JOIN style: ANSI JOIN keyword (preferred) vs old-style comma-separated FROM with WHERE join conditions (deprecated).
• Subquery formatting: indent subqueries inside parentheses, use Common Table Expressions (CTEs) for clarity, or nest with explicit aliases.

Dialect differences

SQL formatters need to handle dialect-specific syntax:

A good formatter detects or accepts a dialect hint, then handles syntax that other dialects would reject.

Common pitfalls

• Reformatting inside production scripts: changing whitespace in a migration script that has already been partially applied can cause issues if your migration tool fingerprints by hash. Format before the first run.
• String literals reformatted: a multi-line string inside a query should not be reformatted by the SQL formatter; some naive formatters break inline strings.
• Comments lost or misplaced: SQL comments (-- single line and /* multi line */) need to survive formatting. Some formatters drop or move them in confusing ways.
• Identifier quoting changed: "my_table" in PostgreSQL means a quoted identifier, \my_table`` means the same in MySQL. A formatter that "normalizes" by removing quotes can change the query's behavior if the identifier needed quoting (reserved word, mixed case in PostgreSQL).
• Window functions misformatted: OVER (PARTITION BY x ORDER BY y) should stay readable. Aggressive line-wrapping inside window function parentheses produces messy output.
• CTE chains over-indented: WITH cte1 AS (...), cte2 AS (...) can get nested too deeply by some formatters. Most modern formatters keep CTEs at the top level.
• Dollar-quoted strings (PostgreSQL functions): $$ function body $$ should not have its contents reformatted. Some formatters mangle them.
• Vendor-specific keywords misclassified: a formatter not aware of QUALIFY (Snowflake) or LATERAL (PostgreSQL) may not capitalize or align them correctly.
• Stored procedures with control flow: BEGIN/END, IF/THEN/ELSE blocks in T-SQL or PL/SQL need indentation rules different from pure queries.

Tips

• Format before committing: run your SQL through a formatter before adding it to version control. This keeps diffs clean and reviews focused on logic, not style.
• Use consistent keyword casing: pick uppercase or lowercase keywords and stick with it across your project. Mixing styles makes queries harder to read.
• Break up complex queries: if a query is still hard to read after formatting, consider breaking it into CTEs (Common Table Expressions) or views. Formatting cannot fix fundamentally complex logic.
• Check syntax highlighting: a good formatter provides color-coded highlighting that makes keywords, strings, and numbers visually distinct, which helps catch typos.
• Format only what you change: in a large existing codebase, reformatting everything at once produces a huge diff that obscures real changes. Format incrementally as you touch queries.
• Set up your editor: VS Code (SQLTools, vscode-sql-formatter), DataGrip, DBeaver, and pgAdmin all have built-in or extension-based formatters. Configure once and forget.
• Watch out for case-sensitive databases: PostgreSQL is case-sensitive for quoted identifiers. A formatter that changes "MyTable" to MYTABLE will break queries.
• Test the formatted query: after reformatting, run the query to verify the output is unchanged. Most formatters are reliable, but a bug in the formatter can corrupt a query.
• Use CTEs over nested subqueries: a CTE chain is almost always easier to read and debug than the equivalent nested subquery, even after formatting.

Privacy and confidential queries

The SQL formatter runs entirely in your browser. The queries you paste, intermediate processing, and the formatted output all stay on your device. Nothing is uploaded to a server, logged, or shared with anyone.

This matters because SQL queries often contain extremely sensitive information: table names that reveal product architecture, column names that expose business logic and metrics, real customer IDs in WHERE clauses, internal API endpoints in stored procedures, SSNs and credit card numbers in test data, employee compensation in HR queries, financial figures in analytics queries, customer email addresses in marketing queries. Cloud SQL formatters log every query in their request logs, sometimes retain them for "service improvement," and have been involved in real breaches where pasted production queries leaked sensitive schema and data. A browser-based formatter has zero exposure: the query never leaves your machine.

Browser-based formatting also works offline once the page is loaded, useful for formatting queries on airplanes, in secure environments without internet access, or anywhere you cannot or should not paste a database query into a third-party service.