SQL is arguably the most widely used language in software engineering, yet it is often the least carefully written. Most teams enforce strict linting on their application code but leave SQL queries as a free-for-all. This guide covers the formatting rules that separate maintainable, team-friendly SQL from query spaghetti that haunts on-call rotations.
Why Poorly Written SQL Is a Real Engineering Problem
Unformatted SQL is not just an aesthetic issue - it is a correctness risk. Dense, run-on queries make it nearly impossible to spot accidental Cartesian products, missing GROUP BY clauses, or WHERE conditions that silently bypass indexes. By the time a performance problem surfaces in production, tracing it back to the root cause becomes a painful exercise in reading someone else's stream of consciousness.
Rule 1: Keyword Capitalization
SQL engines treat select and SELECT identically, but human readers do not. Always uppercase reserved keywords such as SELECT, FROM, WHERE, JOIN, GROUP BY, and ORDER BY. Keep table names, column names, and aliases lowercase. This single habit immediately creates a visual boundary between the logic structure of the query and the underlying data it operates on.
Rule 2: Indentation and Clause Alignment
Think of SQL clauses as layers in a data pipeline. Each major clause - SELECT, FROM, WHERE, GROUP BY, ORDER BY - should start at the left margin. Columns and filter conditions beneath them should be indented by 4 spaces (or 1 tab, as long as your team is consistent). This structure lets any reviewer skim the query top-to-bottom and understand the data flow at a glance.
Rule 3: Trailing vs. Leading Commas
This is a genuinely debated topic on data teams. Leading commas (placing the comma at the start of each new line) make version control diffs significantly cleaner when columns are added or removed. Trailing commas look more natural for developers coming from JavaScript or Python. Neither approach is wrong - what is wrong is mixing both styles within the same codebase. Pick a convention and enforce it with a linter in your CI pipeline.
Structuring JOINs and WHERE Clauses
Each JOIN should be on its own line, and join predicates should be indented beneath it. If a JOIN involves more than one condition, break each predicate onto a separate line. In WHERE clauses, always use explicit parentheses when mixing AND and OR conditions. Do not rely on implicit operator precedence - make the grouping mathematically unambiguous for every reader who comes after you.
CTEs Over Nested Subqueries
If there is one habit change that will have the largest impact on SQL readability, it is replacing nested subqueries with Common Table Expressions (CTEs) using the WITH clause. Nested subqueries force you to read the query from the inside out. CTEs let you name each step in the pipeline, stack them top-to-bottom, and read the data flow in the same direction the database executes it. They also make individual steps independently testable.
Writing SARGable Queries
Consistent formatting does more than make code readable - it helps you catch performance bugs visually. A SARGable query is one where the database engine can leverage B-Tree indexes effectively. The most common mistake is wrapping an indexed column in a function call (e.g., UPPER(email) = 'VALUE'), which forces a full table scan. Similarly, performing arithmetic on the left side of a WHERE condition (e.g., created_at + INTERVAL '7 days' > NOW()) defeats index seeks. Move all transformations to the right side of the expression to preserve index usage.
Handling Raw and Dynamic SQL
Before you can write clean CTEs, you often need to deal with bulk data coming from spreadsheets, API responses, or JSON payloads. Manually translating these sources into INSERT statements is slow and error-prone. Tools like CSV-to-SQL and JSON-to-SQL generators save significant time by mapping data properties directly into multi-row transactional queries. Conversely, if you need to feed query results to a frontend team quickly, an SQL-to-JSON converter can bridge that gap without hand-coding anything.
Code Review Checklist Before Merging SQL
Before any SQL migration or query reaches production, verify the following:
- Reserved keywords are UPPERCASE
- Nested subqueries are refactored into CTEs
- JOIN predicates are indented and explicitly listed
- WHERE conditions perform math on the right side of the expression
- Window functions are split across lines for readability
- Parentheses are used explicitly in all mixed AND/OR conditions
Conclusion
Good SQL formatting is a form of respect for the engineers who will read and maintain your queries next. Enforcing a consistent style - through CI checks, pre-commit hooks, or a shared SQL linter - removes style debates from code review and lets the team focus entirely on correctness and performance. If you want to skip manual formatting, an online SQL formatter can instantly standardize indentation, capitalization, and comma placement before you commit.
Top comments (0)