SQL Formatting Best Practices: Readable Queries & Style Guides

Why does SQL formatting matter?

SQL (Structured Query Language) is incredibly forgiving. The database engine does not care about your line breaks, spaces, or indentation. A 50-line query written entirely on a single, unbroken line will execute the same as one meticulously formatted with nested tabs.

However, your colleagues care. Future you will care.

Code is read far more often than it is written. When a production dashboard breaks or a data pipeline fails at 2:00 AM, debugging a massive, unformatted block of SQL is a nightmare. Proper SQL formatting transforms an unreadable wall of text into a logical, structured story that explains exactly what the query is doing.

Core SQL formatting principles

While different teams have different specific style guides, almost all professional SQL formatting adheres to a few core principles:

1. Capitalise keywords

SQL keywords (SELECT, FROM, WHERE, JOIN, GROUP BY) should be capitalised. Table names and column names should be lowercase (often using snake_case). This creates an immediate visual distinction between commands and data.

Bad:

select id, first_name from users where status = 'active';

Good:

SELECT id, first_name
FROM users
WHERE status = 'active';

2. One column per line

When selecting multiple columns, place each column on its own line. This makes it easy to comment out a single column during testing and makes version-control diffs (like Git) much easier to read.

Bad:

SELECT id, first_name, last_name, email, created_at FROM users;

Good:

SELECT
    id,
    first_name,
    last_name,
    email,
    created_at
FROM users;

3. Align JOINs and ON conditions

JOIN operations are often the most complex part of a query. Indent the JOIN clause, and indent the ON condition slightly further so it is clear which tables are being connected.

Good:

SELECT
    u.first_name,
    o.order_total
FROM users u
    LEFT JOIN orders o
        ON u.id = o.user_id

4. Use Common Table Expressions (CTEs) over subqueries

Nested subqueries (queries inside the WHERE or FROM clause) are notoriously difficult to read. Modern SQL formatting heavily favours CTEs (WITH clauses) placed at the top of the file. They act like variables, breaking complex logic into readable, sequential chunks.

Standard SQL Style Guides

No single "official" SQL style guide exists, but several prominent organisations have published internal standards that have become de facto industry benchmarks.

• Mozilla Data Style Guide: A comprehensive guide emphasising CTEs, leading commas (a divisive but practical choice for easier editing), and strict capitalisation.
• GitLab SQL Style Guide: Focuses heavily on readability in large codebases, preferring trailing commas and standard 2-space indentation.
• Fishtown Analytics / dbt Style Guide: Highly influential in the modern data stack, heavily advocating for CTEs and standardised naming conventions.

How to format SQL automatically

Adopting a style guide is great, but manually adding spaces and line breaks to a 500-line query you inherited from someone else is a massive waste of time.

Use the CampaignMorph SQL Formatter to clean up messy code instantly.

Features:

• Instant formatting: Paste your messy query, and it is instantly formatted based on standard best practices.
• Dialect support: The formatter understands the nuances of different SQL dialects (Standard SQL, PostgreSQL, MySQL, Redshift).
• Privacy: The formatting happens in your browser. Your database schema and proprietary queries are never sent to a server.

Related Developer Tools

If you are writing data pipelines or working with APIs, you may also find these formatting tools useful:

• JSON Formatter: Clean up and validate messy JSON responses.
• Text Case Converter: Quickly convert a list of headers into snake_case for your database schema.
• Cron Generator: Write the scheduling expressions for your automated SQL data dumps.