SQL Formatter

Why SQL Formatting Matters

SQL queries can range from simple one-liners to complex multi-table joins spanning dozens of lines. When a query is written or pasted as a single continuous string, understanding its logic becomes unnecessarily difficult. Proper formatting transforms an unreadable wall of text into a clearly structured document where each clause has its own line, indentation reveals the logical hierarchy, and keywords stand out from identifiers. This is not a cosmetic preference; it directly impacts how quickly developers can debug queries, review code changes, and onboard new team members.

Well-formatted SQL reduces the cognitive load required to understand what a query does. When each SELECT column, each JOIN, and each WHERE condition occupies its own line, a developer can scan the query vertically rather than parsing it left to right. This scanning ability is especially valuable during code reviews, where reviewers need to quickly assess whether a query is correct, efficient, and safe. Poorly formatted SQL in a pull request slows down the entire review process.

Common SQL Style Conventions

The most widely adopted SQL formatting convention uses uppercase for all reserved keywords (SELECT, FROM, WHERE, JOIN, ORDER BY) and lowercase for table names, column names, and aliases. Each major clause starts on a new line at the base indentation level, while sub-clauses like AND, OR, and ON are indented one level deeper. Column lists in SELECT clauses can be placed one per line for complex queries or kept on a single line for simple ones. Table aliases should be short but meaningful, typically one to three characters.

The Keyword Capitalization Debate

While SQL is case-insensitive for keywords, the debate between uppercase and lowercase keywords has persisted for decades. Uppercase keywords won out as the dominant convention for a practical reason: they create an immediate visual distinction between the structural elements of the query (SELECT, WHERE, JOIN) and the data elements (table names, column names, values). This distinction makes queries faster to scan and less prone to misreading. Modern IDEs with syntax highlighting reduce the need for case-based distinction, but uppercase remains the standard in documentation, books, and most team style guides.

Indentation Strategies for Complex Queries

Simple queries need minimal formatting, but complex queries with subqueries, Common Table Expressions (CTEs), and multiple joins benefit enormously from consistent indentation. For subqueries, indent the inner query one level and place the opening and closing parentheses on their own lines aligned with the outer clause. For CTEs using WITH, place each CTE definition as a separate block and indent its body. For multiple JOINs, keep each JOIN on its own line at the same indentation level as FROM, with the ON condition indented beneath it. This layered approach makes even the most complex analytical queries readable.

Formatting and Code Review

Consistent SQL formatting has a direct impact on version control and code review workflows. When SQL is formatted with one clause per line, a change to a WHERE condition shows up as a single modified line in a diff. When the entire query is on one line, even a trivial change appears as a complete rewrite, making it impossible for reviewers to identify what actually changed. Teams that enforce SQL formatting standards through automated tools or linters consistently report faster code reviews and fewer bugs in database queries.

Frequently Asked Questions

What does a SQL formatter do?

A SQL formatter restructures your query with consistent indentation, line breaks before major clauses, and uppercased keywords. It makes complex queries easier to read without changing what the query does.

Should SQL keywords be uppercase or lowercase?

Uppercase is the dominant convention because it visually separates SQL syntax from table and column names. SQL is case-insensitive for keywords, so either works functionally.

How should I indent subqueries and CTEs?

Add one indentation level for each nesting depth. For CTEs, indent the inner query body. For subqueries, indent inside the parentheses. Keep the main query at the base level.

Does formatting affect query performance?

No. The database strips all whitespace before parsing. Formatting is purely for human readability and has zero impact on execution.

Why put each clause on a new line?

It makes queries scannable, simplifies debugging, and produces cleaner version control diffs. A change to one clause appears as a single modified line.