SQL Formatting Conventions: Write Clean, Readable Queries

Why SQL Formatting Matters

SQL has no opinions about whitespace. A query that spans 50 lines and one that is compressed into a single line execute identically. But the humans who read, debug, and modify that query are not compilers — they need structure to understand what the query does.

Poorly formatted SQL is the number one source of bugs in data work. When a WHERE clause hides in the middle of an unbroken block of text, conditions get overlooked, joins go unchecked, and subtle logic errors survive code review. Consistent formatting prevents these problems.

Most teams eventually adopt a formatting standard. The sooner you internalize good habits, the less reformatting you will do later.

Capitalization Conventions

The most widely adopted convention is uppercase keywords, lowercase identifiers:

SELECT
u.first_name,
u.last_name,
o.order_total
FROM users u
JOIN orders o ON o.user_id = u.id
WHERE u.active = TRUE
ORDER BY o.order_total DESC;

This works because SQL keywords (SELECT, FROM, WHERE, JOIN) are a small, fixed set. Making them visually distinct from table names and column names lets you parse the query structure at a glance.

Some teams prefer all-lowercase for a softer visual style. Either convention works — the key is consistency across your team's entire codebase.

Indentation and Line Breaks

The goal of indentation is to make the logical structure visible. Here are the most effective patterns:

Major Clauses on Their Own Lines

Each major SQL clause (SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT) starts on a new line at the leftmost indentation level. Column lists and conditions are indented one level deeper.

One Column Per Line in SELECT

Listing columns vertically makes it easy to add, remove, or comment out individual columns:

SELECT
u.id,
u.email,
u.created_at,
COUNT(o.id) AS order_count

Horizontal lists (SELECT u.id, u.email, u.created_at) work for 2-3 columns but become unreadable beyond that.

JOIN Clauses

Place each JOIN on its own line, with the ON condition on the same line or indented below:

FROM users u
JOIN orders o ON o.user_id = u.id
LEFT JOIN payments p ON p.order_id = o.id

WHERE Conditions

Place each condition on its own line with AND/OR at the beginning:

WHERE
u.active = TRUE
AND u.created_at > '2024-01-01'
AND o.status IN ('completed', 'shipped')

Leading AND/OR makes it trivial to comment out individual conditions during debugging.

Table and Column Aliases

Aliases reduce repetition and improve readability, but they need to be meaningful:

• Use short but recognizable aliases: users u, orders o, order_items oi. Single-letter aliases work for simple queries. Multi-table queries with several joins benefit from 2-3 letter abbreviations.
• Always alias calculated columns: COUNT(*) AS total_orders, not just COUNT(*). Without an alias, the result column name is implementation-dependent.
• Use AS explicitly: users AS u is clearer than users u even though both work. The explicit AS keyword signals "this is an alias" to anyone scanning the query.
• Prefix columns with table aliases: In multi-table queries, u.email is unambiguous. email alone requires the reader to check which table it belongs to — and may cause errors if another joined table also has an email column.

Subqueries and CTEs

Complex queries often involve subqueries or Common Table Expressions (CTEs). Formatting them well is critical because they introduce additional nesting:

CTEs (WITH Clauses)

CTEs are generally preferred over subqueries because they read top-to-bottom like a narrative:

WITH active_users AS (
SELECT id, email
FROM users
WHERE active = TRUE
),
recent_orders AS (
SELECT user_id, SUM(total) AS total_spent
FROM orders
WHERE created_at > '2024-01-01'
GROUP BY user_id
)
SELECT
au.email,
ro.total_spent
FROM active_users au
JOIN recent_orders ro ON ro.user_id = au.id;

Subqueries

When you must use a subquery, indent it one level and treat it like a mini-query with its own formatting rules:

SELECT *
FROM orders
WHERE user_id IN (
SELECT id
FROM users
WHERE active = TRUE
);

Our SQL Formatter automatically applies these conventions to any query — paste in messy SQL and get clean, consistently formatted output.

Establishing Team Standards

Formatting arguments are endless unless you establish a standard and enforce it. Practical approaches:

• Pick a style and document it. It does not matter which conventions you choose as long as the entire team follows the same ones.
• Use a formatter. Automated formatting tools like our SQL Formatter, SQLFluff, or pgFormatter eliminate subjective debates. Run the formatter before committing code.
• Add linting to CI. SQLFluff integrates with CI pipelines and can reject improperly formatted queries automatically.
• Review formatting in code review. If a query is hard to read, ask for reformatting. Readability is a valid review concern.
• Keep queries in version control. SQL in .sql files gets the same formatting treatment as application code. Inline SQL in application code should follow the same standards.

Format your SQL instantly with our SQL Formatter. For working with data in other formats, see our CSV vs JSON comparison and JSON formatting best practices.