SQL Formatting Best Practices for Readable Queries
Well-formatted SQL is easier to read, review, debug, and maintain. Yet many developers write SQL as a single long line or with inconsistent formatting. A few simple rules can make any query dramatically more readable.
Why SQL Formatting Matters
SQL queries often live in application code, migration files, or analytics dashboards where multiple people read and modify them. Poorly formatted SQL leads to bugs that are hard to spot, slower code reviews, and confusion about query logic. Consistent formatting makes the structure of a query visible at a glance.
The Basics: Keywords and Indentation
The most impactful formatting rule is putting major SQL keywords on their own line. Compare these two versions:
-- Hard to read
SELECT u.name, u.email, o.total FROM users u JOIN orders o ON u.id = o.user_id WHERE o.status = 'active' AND o.total > 100 ORDER BY o.total DESC LIMIT 10;
-- Easy to read
SELECT
u.name,
u.email,
o.total
FROM
users u
JOIN
orders o ON u.id = o.user_id
WHERE
o.status = 'active'
AND o.total > 100
ORDER BY
o.total DESC
LIMIT
10;
Formatting Rules
- Uppercase keywords. Write
SELECT,FROM,WHEREin uppercase to distinguish them from column and table names. - One column per line in SELECT. This makes it easy to add, remove, or comment out columns during development.
- Leading commas (optional). Some teams prefer
, column_nameat the start of each line. This makes it easier to spot missing commas and comment out lines. - Indent clauses. Indent column names, conditions, and expressions under their parent keyword by 2-4 spaces.
- Align JOINs consistently. Put each JOIN on its own line with the ON condition either on the same line or indented below.
Subquery Formatting
Subqueries should be indented one level deeper than the outer query. Use parentheses on their own lines for complex subqueries:
SELECT
u.name,
u.email
FROM
users u
WHERE
u.id IN (
SELECT
user_id
FROM
orders
WHERE
total > 1000
);
Common Mistakes
- Using SELECT *. Always list specific columns. It makes the query self-documenting and prevents unexpected data from leaking through.
- Inconsistent aliasing. Pick a convention (first letter, abbreviation, or full name) and stick with it across all queries.
- No comments on complex logic. If a WHERE condition or CASE statement is not obvious, add a brief comment explaining why it exists.
- Mixing formatting styles. Agree on one style guide for your team. Whether you use leading commas or trailing commas matters less than consistency.
Automated SQL Formatting
Manual formatting is tedious and error-prone. Automated formatters apply consistent rules instantly. Tools like sql-formatter (npm), sqlfluff (Python), and online SQL formatters can reformat an entire query in seconds. Many IDEs like DataGrip and VS Code extensions also include built-in SQL formatting.
Format your SQL now
Paste any SQL query to instantly format it with proper indentation and consistent style.
Open SQL Formatter