How to Format SQL Queries for Readability: Rules, Examples, and Team Conventions

Overview

If you want to format SQL queries for readability, the goal is not decoration. The goal is to reduce cognitive load. Good formatting makes structure visible: what rows are being selected, where data comes from, how tables relate, which filters apply, and how final results are ordered or grouped.

Teams often run into the same problem: the query works, but nobody wants to touch it later. That usually happens when clauses run together, aliases are inconsistent, conditions are nested without spacing, or a query mixes business logic with unclear naming. A SQL style guide fixes that by making common decisions predictable.

This article focuses on durable conventions rather than dialect-specific syntax. Whether you write PostgreSQL, MySQL, SQLite, SQL Server, or warehouse SQL, the same readability principles usually apply:

• Make the query shape obvious at a glance.
• Keep related logic together.
• Use consistent casing, indentation, and line breaks.
• Name things so the intent is visible.
• Prefer formatting that helps code review, not just personal preference.

If your team already uses a SQL formatter, these rules still matter. A formatter can enforce layout, but it cannot decide whether a Common Table Expression should be split, whether an alias is meaningful, or whether a long WHERE clause should be grouped by intent.

Core framework

Use this framework as a baseline SQL formatting ruleset. It is simple enough for daily work and strong enough to serve as a team convention.

1. Put major clauses on their own lines

Each top-level clause should begin on a new line. This gives the query a visible outline.

SELECT
FROM
JOIN
WHERE
GROUP BY
HAVING
ORDER BY
LIMIT

That structure lets a reviewer scan the query in seconds. If a clause is missing or misplaced, it stands out immediately.

2. Indent subordinate logic consistently

Inside each major clause, indent selected columns, join conditions, and filter conditions. Use one indentation style and keep it stable across the codebase.

SELECT
  u.id,
  u.email,
  u.created_at
FROM users AS u
WHERE
  u.is_active = true
  AND u.deleted_at IS NULL;

The exact number of spaces matters less than consistency. Two spaces or four spaces both work if the team applies one standard everywhere.

3. Choose a keyword casing convention and keep it uniform

Most teams either uppercase SQL keywords or keep everything lowercase. Uppercase can make clauses more visible. Lowercase can feel calmer and blend better with application code. Neither is universally correct. The real rule is to avoid mixing styles.

Example with uppercase keywords:

SELECT
  id,
  name
FROM customers
WHERE status = 'active';

Example with lowercase keywords:

select
  id,
  name
from customers
where status = 'active';

If you use an automated sql formatter, let the tool settle the casing debate so humans can focus on logic.

4. Put one selected column per line in non-trivial queries

Short queries can stay compact, but once a SELECT list grows beyond a few fields, split it. This improves diff quality and reduces merge conflicts.

SELECT
  o.id,
  o.order_number,
  o.created_at,
  c.name AS customer_name,
  c.email AS customer_email,
  SUM(oi.quantity * oi.unit_price) AS order_total
FROM orders AS o
JOIN customers AS c
  ON c.id = o.customer_id
JOIN order_items AS oi
  ON oi.order_id = o.id
GROUP BY
  o.id,
  o.order_number,
  o.created_at,
  c.name,
  c.email;

One item per line makes additions and removals obvious in review.

5. Align joins so relationships are easy to inspect

Joins are often the highest-risk part of a query. Give each JOIN its own block, and place the ON condition beneath it.

FROM orders AS o
JOIN customers AS c
  ON c.id = o.customer_id
LEFT JOIN shipments AS s
  ON s.order_id = o.id
  AND s.cancelled_at IS NULL

This layout helps reviewers catch accidental cross joins, weak join conditions, or filters that belong in WHERE instead of ON.

6. Group WHERE conditions by intent

A long WHERE clause becomes much easier to read when you separate concerns. Common groups include record status, date range, tenant scope, and search filters.

WHERE
  o.account_id = :account_id
  AND o.deleted_at IS NULL
  AND o.status IN ('paid', 'shipped')
  AND o.created_at >= :start_date
  AND o.created_at < :end_date

When logic gets more complex, use parentheses generously and put each logical branch on its own lines.

WHERE
  o.deleted_at IS NULL
  AND (
    o.status = 'paid'
    OR (
      o.status = 'pending'
      AND o.expires_at > NOW()
    )
  )

Parentheses are not just for correctness. They are a readability tool.

7. Use meaningful aliases

Aliases should clarify, not compress. Single-letter aliases are acceptable for very common cases in short queries, but descriptive aliases often age better.

FROM orders AS o
JOIN customers AS c
  ON c.id = o.customer_id

works fine in a compact query. But in a long reporting query, this may be clearer:

FROM orders AS orders
JOIN customers AS customers
  ON customers.id = orders.customer_id

A practical compromise is to use short aliases when the query involves two or three familiar tables, and more descriptive aliases when joins become dense or self-referential.

8. Prefer CTEs for multi-step logic

If a query has several conceptual stages, format it as a sequence of named Common Table Expressions. This is often the single biggest readability improvement you can make.

WITH active_customers AS (
  SELECT
    id,
    email
  FROM customers
  WHERE deleted_at IS NULL
),
recent_orders AS (
  SELECT
    customer_id,
    created_at,
    total_amount
  FROM orders
  WHERE created_at >= CURRENT_DATE - INTERVAL '30 days'
)
SELECT
  ac.id,
  ac.email,
  ro.created_at,
  ro.total_amount
FROM active_customers AS ac
JOIN recent_orders AS ro
  ON ro.customer_id = ac.id;

Each CTE should represent one understandable step. Avoid using CTEs only to move clutter around. Name them by purpose.

9. Keep expressions readable, not clever

Inline calculations and CASE expressions are often necessary, but format them vertically.

CASE
  WHEN o.cancelled_at IS NOT NULL THEN 'cancelled'
  WHEN o.paid_at IS NOT NULL THEN 'paid'
  WHEN o.expires_at < NOW() THEN 'expired'
  ELSE 'pending'
END AS order_state

This is much easier to audit than a one-line CASE expression buried between columns.

10. End with a stable team convention

A sql style guide only works if the team can apply it repeatedly. Write down a short standard covering casing, indentation, aliasing, comma placement, CTE usage, and line breaks. Keep it lightweight enough that people will actually follow it.

Practical examples

The fastest way to learn readable SQL queries is to compare messy versions with edited ones. These examples show what changes help most.

Example 1: Basic filtering

Hard to read:

SELECT id,name,email,created_at FROM users WHERE deleted_at IS NULL AND is_active = true AND created_at >= '2024-01-01' ORDER BY created_at DESC;

Formatted:

SELECT
  id,
  name,
  email,
  created_at
FROM users
WHERE
  deleted_at IS NULL
  AND is_active = true
  AND created_at >= '2024-01-01'
ORDER BY created_at DESC;

What improved: the selected fields are easy to scan, the filters are grouped, and the sort order is visible immediately.

Example 2: Multi-join query

Hard to read:

SELECT o.id,c.name,s.status FROM orders o LEFT JOIN customers c ON c.id=o.customer_id LEFT JOIN shipments s ON s.order_id=o.id WHERE o.deleted_at IS NULL AND c.deleted_at IS NULL;

Formatted:

SELECT
  o.id,
  c.name AS customer_name,
  s.status AS shipment_status
FROM orders AS o
LEFT JOIN customers AS c
  ON c.id = o.customer_id
LEFT JOIN shipments AS s
  ON s.order_id = o.id
WHERE
  o.deleted_at IS NULL
  AND c.deleted_at IS NULL;

What improved: joins are inspectable, aliases have meaning, and output names are explicit.

Example 3: Aggregation and grouping

Hard to read:

SELECT c.id,c.name,COUNT(o.id) order_count,SUM(o.total_amount) revenue FROM customers c JOIN orders o ON o.customer_id=c.id WHERE o.status='paid' GROUP BY c.id,c.name HAVING SUM(o.total_amount)>1000 ORDER BY revenue DESC;

Formatted:

SELECT
  c.id,
  c.name,
  COUNT(o.id) AS order_count,
  SUM(o.total_amount) AS revenue
FROM customers AS c
JOIN orders AS o
  ON o.customer_id = c.id
WHERE o.status = 'paid'
GROUP BY
  c.id,
  c.name
HAVING SUM(o.total_amount) > 1000
ORDER BY revenue DESC;

What improved: aggregate output is easy to identify, grouping keys are clear, and the post-aggregation filter is no longer buried.

Example 4: Complex business logic with CTEs

Less maintainable:

SELECT u.id,u.email,COUNT(s.id) session_count FROM users u LEFT JOIN sessions s ON s.user_id=u.id AND s.created_at>=CURRENT_DATE-INTERVAL '7 days' WHERE u.deleted_at IS NULL AND u.is_active=true GROUP BY u.id,u.email;

Formatted with a clearer step:

WITH recent_sessions AS (
  SELECT
    user_id,
    id
  FROM sessions
  WHERE created_at >= CURRENT_DATE - INTERVAL '7 days'
)
SELECT
  u.id,
  u.email,
  COUNT(rs.id) AS session_count
FROM users AS u
LEFT JOIN recent_sessions AS rs
  ON rs.user_id = u.id
WHERE
  u.deleted_at IS NULL
  AND u.is_active = true
GROUP BY
  u.id,
  u.email;

What improved: the time filter has a name and a location of its own, which makes the main query easier to discuss.

Suggested team convention template

If your team wants a starting point, this compact convention is usually enough:

• Use uppercase for SQL keywords.
• Place each major clause on its own line.
• Use one selected column per line for queries with more than three columns.
• Indent clause contents by two spaces.
• Place each JOIN on its own line and the ON condition beneath it.
• Use explicit AS for aliases.
• Group WHERE conditions by purpose, with parentheses for OR branches.
• Prefer CTEs for multi-step transformations.
• Avoid SELECT * in shared or long-lived queries unless there is a clear reason.
• Use a formatter for baseline consistency, then review for intent and naming.

If your team works with other structured text regularly, consistent formatting habits can improve more than SQL. For example, comparing API payloads becomes easier with structured tools and stable conventions, similar to the workflow discussed in JSON Diff Tools Compared: Best Ways to Compare API Responses and Config Files.

Common mistakes

Many unreadable queries are not wrong in terms of syntax. They are wrong in terms of maintenance cost. Watch for these common issues.

1. Keeping everything on one line

This usually happens when a query starts small and grows without reformatting. Once the query has joins, filters, or aggregations, a single line becomes hostile to review.

2. Mixing join filters and result filters carelessly

Conditions in ON and WHERE can change results, especially with LEFT JOIN. Formatting joins clearly helps you notice whether a condition is limiting the join relationship or filtering rows after the join.

3. Inconsistent aliasing

Switching between full table names, single letters, and omitted aliases in the same query creates friction. Readers should not have to decode naming conventions line by line.

4. Using SELECT * in long-lived application queries

For quick exploration, SELECT * can be fine. In shared code, it hides intent, makes output less stable, and increases the chance that schema changes will affect behavior in surprising ways. Explicit column lists are usually easier to review and safer to evolve.

5. Dense boolean logic without parentheses

Even when operator precedence makes the query technically correct, reviewers may still misread it. Parentheses communicate intent and reduce mistakes during future edits.

6. Over-formatting trivial queries

Readability is contextual. A tiny one-table query does not need five screens of vertical spacing. Good formatting should make a query easier to read, not artificially longer.

7. Letting the formatter replace judgment

An automated sql formatter is useful, but formatting tools do not know your business logic. They cannot decide whether a query should be split into CTEs, whether a name is vague, or whether repeated expressions deserve extraction.

8. Hiding intent in vague CTE names

Names like temp, data, or cte1 add structure without adding clarity. Prefer names such as active_subscriptions, ranked_events, or latest_invoice_per_customer.

Readable code across a stack often depends on the same discipline: stable naming, explicit structure, and predictable formatting. If your work crosses into application configuration and tooling, that same principle shows up in guides such as TypeScript Config Guide: tsconfig Options That Matter for Modern Projects.

When to revisit

Your SQL style guide should not be rewritten every month, but it should be revisited when the way your team writes queries changes. The most useful style guide is stable, documented, and updated only when a recurring pain point appears.

Revisit your conventions when:

• You adopt a new SQL formatter, linter, or editor integration.
• Your team moves from simple transactional queries to more analytical or reporting-heavy SQL.
• You introduce dbt, stored procedures, query builders, or generated SQL into the workflow.
• Code reviews keep raising the same readability issues.
• Your schema becomes more complex and aliasing starts to break down.
• You support multiple SQL dialects and need cross-dialect readability rules.

A practical review process is simple:

1. Collect five to ten real queries from current projects.
2. Identify recurring pain points: joins, naming, CTE sprawl, WHERE clause complexity, or grouping style.
3. Update only the conventions that solve those problems.
4. Run the rules through your formatter or linting setup where possible.
5. Publish a short team example file with before-and-after patterns.

If you maintain internal tooling for developer workflows, treat SQL formatting like any other repeatable quality practice. The same mindset applies to debugging, scheduling, and structured text handling in adjacent areas, whether you are validating cron syntax, comparing JSON, or standardizing date output. Small conventions save time repeatedly.

To make this article actionable today, pick one existing query in your codebase and refactor it using these rules:

• Split top-level clauses onto separate lines.
• Move to one selected column per line.
• Reformat each JOIN as its own block.
• Group WHERE conditions by purpose.
• Replace vague aliases with meaningful ones.
• Extract one multi-step section into a clearly named CTE.

Then turn that edited query into the first example in your team’s SQL style guide. That is often enough to create a convention people will actually reuse.