SQL Query Formatting Best Practices for Team Codebases

SQL query displayed on a dark-themed code editor

SQL is one of the oldest languages in active use, and it shows. Unlike JavaScript or Python, there is no universally adopted style guide for SQL. This leads to codebases where every developer formats queries differently, making code reviews painful and bugs harder to spot.

This guide establishes practical SQL formatting conventions that work across MySQL, PostgreSQL, SQL Server, and SQLite.

Why SQL Formatting Matters

Unformatted SQL is not just ugly - it is dangerous. Consider this single-line query:

SELECT u.id,u.name,u.email,o.total,o.created_at FROM users u INNER JOIN orders o ON u.id=o.user_id WHERE u.active=1 AND o.total>100 ORDER BY o.created_at DESC LIMIT 50;

Now compare with the formatted version:

SELECT
    u.id,
    u.name,
    u.email,
    o.total,
    o.created_at
FROM users u
INNER JOIN orders o
    ON u.id = o.user_id
WHERE u.active = 1
    AND o.total > 100
ORDER BY o.created_at DESC
LIMIT 50;

The second version makes the join condition, filter criteria, and column list immediately obvious. Bugs hide in dense code. Formatted code reveals them.

Core Formatting Rules

Rule 1: Uppercase SQL Keywords

SQL keywords should be uppercase to visually separate them from table names, column names, and values:

-- Good
SELECT name FROM users WHERE active = 1;

-- Bad
select name from users where active = 1;

Rule 2: One Column Per Line in SELECT

When selecting more than two columns, place each on its own line:

SELECT
    first_name,
    last_name,
    email,
    created_at
FROM users;

Rule 3: Indent JOIN Conditions

The ON clause should be indented under the JOIN to show the relationship clearly:

FROM orders o
INNER JOIN users u
    ON o.user_id = u.id
LEFT JOIN payments p
    ON o.id = p.order_id
    AND p.status = 'completed';

Rule 4: Align WHERE Conditions

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

WHERE u.active = 1
    AND u.role = 'admin'
    AND u.created_at > '2026-01-01';

SQL code formatting comparison showing before and after beautification

Naming Conventions

Table Names

Use snake_case and plural nouns: users, order_items, payment_methods. Avoid abbreviations unless universally understood (e.g., id is fine, usr is not).

Column Names

Use snake_case. Prefix boolean columns with is_ or has_: is_active, has_premium. Use _at suffix for timestamps: created_at, updated_at, deleted_at.

Alias Conventions

Use short, meaningful aliases. The first letter of the table name is common:

FROM users u
INNER JOIN orders o ON u.id = o.user_id
INNER JOIN products p ON o.product_id = p.id

Common Formatting Mistakes

Mistake 1: Mixing JOIN Syntax

Do not mix implicit joins (comma-separated FROM) with explicit JOIN syntax:

-- Bad: Mixed styles
SELECT * FROM users u, orders o
INNER JOIN products p ON o.product_id = p.id
WHERE u.id = o.user_id;

-- Good: Consistent explicit JOINs
SELECT *
FROM users u
INNER JOIN orders o ON u.id = o.user_id
INNER JOIN products p ON o.product_id = p.id;

Mistake 2: SELECT * in Production

Never use SELECT * in production code. It fetches unnecessary columns, breaks when schema changes, and hides the intent of the query.

Mistake 3: Not Using CTEs for Complex Queries

Common Table Expressions (CTEs) break complex queries into named, readable steps:

WITH active_users AS (
    SELECT id, name, email
    FROM users
    WHERE active = 1
        AND last_login > NOW() - INTERVAL '30 days'
),
user_orders AS (
    SELECT
        u.id AS user_id,
        u.name,
        COUNT(o.id) AS order_count,
        SUM(o.total) AS total_spent
    FROM active_users u
    INNER JOIN orders o ON u.id = o.user_id
    GROUP BY u.id, u.name
)
SELECT *
FROM user_orders
WHERE total_spent > 1000
ORDER BY total_spent DESC;

Automated Formatting Tools

Manual formatting is tedious and inconsistent. Use automated tools:

Online Formatters

Our free SQL Formatter instantly beautifies SQL queries with support for MySQL, PostgreSQL, SQL Server, and standard SQL dialects. Paste your query, click format, and copy the result.

IDE Integration

VS Code: Use the "SQL Formatter" extension for format-on-save
DataGrip: Built-in formatter with customisable rules
DBeaver: Right-click → Format SQL

CI/CD Integration

Add SQL linting to your CI pipeline with sqlfluff:

pip install sqlfluff
sqlfluff lint queries/ --dialect postgres
sqlfluff fix queries/ --dialect postgres

Security and Formatting

Properly formatted SQL also reduces security risks. Parameterised queries are easier to spot (and verify) in well-formatted code:

-- Obvious parameterisation in formatted code
SELECT id, name, email
FROM users
WHERE id = $1
    AND role = $2;

Versus the unformatted version where injection vulnerabilities can hide in the noise.