SQL is one of the most widely used languages in software development, yet it is also one of the most frequently written in an unreadable manner. Whether you are debugging a production query, reviewing a colleague's pull request, or trying to understand legacy stored procedures, poorly formatted SQL can slow you down significantly. In this guide, we will explain why formatting SQL matters, walk through the most popular style conventions, and show you how to instantly beautify any query using a free online tool.
Why Formatting SQL Matters
Unlike languages such as Python, SQL does not enforce indentation or whitespace rules. The database engine treats a single-line query identically to one spread across fifty lines with careful indentation. This flexibility is convenient when writing quick ad-hoc queries, but it becomes a liability in team environments and production codebases.
Unformatted SQL introduces several problems. First, it is harder to spot logical errors. When a WHERE clause, a JOIN condition, and an aggregation are all crammed onto one line, it is easy to miss a missing predicate or an incorrect alias. Second, code reviews take longer because reviewers must mentally parse the structure before they can evaluate the logic. Third, version control diffs become noisy when developers reformat queries inconsistently across commits.
Consistent formatting solves all of these issues. When every query in a codebase follows the same style, developers can scan the structure at a glance, diffs show only meaningful changes, and onboarding new team members becomes significantly easier.
SQL Style Guides: An Overview
Several well-known SQL style guides have emerged over the years. While they differ in specifics, they agree on the core principles: use consistent casing for keywords, indent logically, and place each major clause on its own line.
The Simon Holywell style guide (sqlstyle.guide) is one of the most referenced. It recommends right-aligning keywords so that the column names form a clean left edge. For example, SELECT, FROM, and WHERE are right-aligned to a river of whitespace, and the column references start at the same column position. This approach creates a visually distinctive layout but can feel unfamiliar to developers used to left-aligned code.
The GitLab SQL style guide takes a more conventional approach. Keywords are uppercase and left-aligned, each clause starts on a new line, and indentation uses four spaces. This style is closer to what most programming editors expect and integrates well with general-purpose formatters.
The Mozilla SQL style guide and various company-internal guides follow similar conventions. The key takeaway is that the specific style matters less than consistency. Pick a guide, configure your formatter to match it, and enforce it across your team.
Keyword Casing: UPPER vs lower
One of the most debated aspects of SQL formatting is whether keywords should be uppercase or lowercase. The argument for uppercase keywords is that they create a clear visual distinction between SQL syntax and user-defined identifiers like table and column names. When you see SELECT name FROM users WHERE active = true, the uppercase keywords act as structural signposts.
The argument for lowercase keywords is ergonomic. Typing in all caps requires holding the Shift key or toggling Caps Lock, which slows down writing. Modern editors with syntax highlighting already color-code keywords, making the visual distinction argument less compelling.
In practice, uppercase keywords remain the dominant convention in the SQL community. Most style guides recommend them, most formatters default to them, and most database documentation uses them. If you are starting a new project or establishing a team standard, uppercase keywords are the safer choice. If your existing codebase uses lowercase consistently, there is no need to change.
Our SQL formatter supports both conventions. You can choose uppercase, lowercase, or preserve the original casing when formatting your queries.
Indentation Conventions
Indentation is what transforms a flat string of SQL into a readable, hierarchical structure. The most common conventions are:
- Two spaces — Compact and works well for shorter queries. Popular in environments where screen real estate is limited, such as terminal-based SQL clients.
- Four spaces — The most common choice. Provides clear visual hierarchy without excessive horizontal scrolling. Matches the default indentation in most programming languages.
- Tabs — Allows each developer to configure their preferred visual width. Less common in SQL specifically but used in some codebases that standardize on tabs across all languages.
Beyond the basic indentation unit, there are conventions for what gets indented. Column lists after SELECT are typically indented one level. JOIN clauses are often indented one level from FROM, with their ON conditions indented a further level. AND and OR within a WHERE clause are indented to align with the first predicate.
Example: Before Formatting
select u.id, u.name, u.email, o.order_date, o.total from users u inner join orders o on u.id = o.user_id where u.active = true and o.total > 100 order by o.order_date desc limit 50;Example: After Formatting
SELECT
u.id,
u.name,
u.email,
o.order_date,
o.total
FROM
users u
INNER JOIN orders o
ON u.id = o.user_id
WHERE
u.active = true
AND o.total > 100
ORDER BY
o.order_date DESC
LIMIT
50;The formatted version is immediately scannable. You can see at a glance which columns are selected, which tables are joined and on what condition, what filters are applied, and how the results are ordered and limited.
Formatting Subqueries
Subqueries are where formatting becomes especially important. A nested subquery inside a WHERE clause or a FROM clause can become deeply confusing without proper indentation. The general rule is to indent the subquery one level deeper than its surrounding context and to place the opening and closing parentheses on their own lines or aligned with the clause they belong to.
Subquery Example: Before
select * from users where id in (select user_id from orders where total > (select avg(total) from orders where order_date > '2025-01-01'));Subquery Example: After
SELECT
*
FROM
users
WHERE
id IN (
SELECT
user_id
FROM
orders
WHERE
total > (
SELECT
AVG(total)
FROM
orders
WHERE
order_date > '2025-01-01'
)
);Each level of nesting is clearly visible. You can trace the logic from the outermost query inward without losing your place. This is especially valuable when debugging queries that return unexpected results.
Common Table Expressions (CTEs)
CTEs, introduced with the WITH keyword, are an alternative to subqueries that many developers find more readable. Formatting CTEs well means giving each CTE its own block, indenting the body, and clearly separating the final SELECT.
WITH active_users AS (
SELECT
id,
name,
email
FROM
users
WHERE
active = true
),
recent_orders AS (
SELECT
user_id,
SUM(total) AS total_spent
FROM
orders
WHERE
order_date > '2025-01-01'
GROUP BY
user_id
)
SELECT
au.name,
au.email,
ro.total_spent
FROM
active_users au
INNER JOIN recent_orders ro
ON au.id = ro.user_id
ORDER BY
ro.total_spent DESC;Well-formatted CTEs read almost like a series of named steps. Each block has a clear purpose, and the final query simply combines them. This pattern is not only more readable but also easier to debug because you can run each CTE independently.
Formatting INSERT, UPDATE, and DELETE Statements
Formatting is not just for SELECT queries. INSERT statements benefit from aligning column names and values. UPDATE statements are clearer when each SET assignment is on its own line. DELETE statements with complex WHERE clauses need the same careful indentation as SELECT queries.
INSERT INTO users (
name,
email,
role,
created_at
)
VALUES (
'Jane Doe',
'jane@example.com',
'admin',
NOW()
);UPDATE users
SET
role = 'admin',
updated_at = NOW()
WHERE
email = 'jane@example.com'
AND active = true;Dialect Differences
SQL is not a single language but a family of dialects. PostgreSQL, MySQL, SQL Server, Oracle, SQLite, and BigQuery all have syntax extensions and quirks. A good formatter handles dialect-specific syntax gracefully. For example, PostgreSQL uses :: for type casting, MySQL uses backtick-quoted identifiers, and SQL Server uses square brackets. BigQuery supports STRUCT and ARRAY types with their own formatting needs.
When choosing a formatter, make sure it supports the dialect you work with. Our SQL formatter handles the most common dialects and preserves dialect-specific syntax while applying consistent formatting rules.
Integrating Formatting Into Your Workflow
The best formatting is automatic formatting. Here are several ways to integrate SQL formatting into your development workflow:
- Editor plugins — VS Code, JetBrains IDEs, and Vim all have SQL formatting extensions. Configure them to format on save for instant consistency.
- Pre-commit hooks — Use tools like
sqlflufforsqlfmtas pre-commit hooks to enforce formatting before code reaches your repository. - CI/CD checks — Add a formatting check to your continuous integration pipeline. If a query does not match the expected format, the build fails.
- Online tools — For quick one-off formatting, paste your query into an online formatter. This is especially useful when working with queries from logs, Slack messages, or documentation.
Tips for Writing Naturally Readable SQL
Beyond automated formatting, there are practices that make SQL inherently more readable:
- Use meaningful aliases — Instead of
t1andt2, useufor users andofor orders, or even the full table name for complex queries. - Qualify all column references — In multi-table queries, always prefix column names with the table alias. This eliminates ambiguity and makes it clear where each value comes from.
- Comment complex logic — Use
--comments to explain non-obvious business rules or performance optimizations. - Break up long queries — If a query exceeds 50 lines, consider breaking it into CTEs or even separate queries with temporary tables.
- Avoid SELECT * — Explicitly listing columns makes the query self-documenting and protects against schema changes.