SQL Formatting Best Practices for Readable Queries

Well-formatted SQL is essential for code readability, debugging, and collaboration. Poor formatting makes queries harder to understand and maintain.

Why Format SQL?

• Readability: Quickly understand query logic
• Debugging: Easier to spot errors in formatted queries
• Collaboration: Team members can review queries faster
• Maintenance: Formatted queries are easier to modify

Core Formatting Rules

1. Keywords in UPPERCASE

SELECT name, email

FROM users
WHERE active = true
ORDER BY created_at DESC;

2. One Clause Per Line

-- Good

SELECT
    u.name,
    u.email,
    COUNT(o.id) AS order_count
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.active = true
GROUP BY u.name, u.email
HAVING COUNT(o.id) > 5
ORDER BY order_count DESC
LIMIT 10;
-- Bad (everything on one line)
SELECT u.name, u.email, COUNT(o.id) AS order_count FROM users u JOIN orders o ON u.id = o.user_id WHERE u.active = true GROUP BY u.name, u.email HAVING COUNT(o.id) > 5 ORDER BY order_count DESC LIMIT 10;

3. Consistent Indentation

Use 4 spaces for indentation. Indent column lists, conditions, and subqueries:

SELECT

    u.first_name,
    u.last_name,
    u.email
FROM users u
WHERE
    u.active = true
    AND u.created_at > '2024-01-01'
    AND u.role IN ('admin', 'editor');

4. Use Table Aliases

-- Good

SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id;
-- Bad
SELECT users.name, orders.total
FROM users
JOIN orders ON users.id = orders.user_id;

5. Format JOINs Clearly

SELECT

    u.name,
    o.total,
    p.name AS product_name
FROM users u
INNER JOIN orders o
    ON u.id = o.user_id
LEFT JOIN products p
    ON o.product_id = p.id
WHERE u.active = true;

6. Subquery Formatting

SELECT name, email

FROM users
WHERE id IN (
    SELECT user_id
    FROM orders
    WHERE total > 100
    GROUP BY user_id
    HAVING COUNT(*) > 3
);

Common Style Guides

Simon Holywell's SQL Style Guide

• Keywords uppercase, identifiers lowercase
• Right-aligned keywords (river style)
• Consistent use of aliases

GitLab SQL Style Guide

• 4-space indentation
• Trailing commas in SELECT lists
• CTEs (WITH clauses) preferred over subqueries

CTE (Common Table Expression) Best Practices

WITH active_users AS (

    SELECT id, name, email
    FROM users
    WHERE active = true
),
user_orders AS (
    SELECT
        user_id,
        COUNT(*) AS order_count,
        SUM(total) AS total_spent
    FROM orders
    GROUP BY user_id
)
SELECT
    au.name,
    au.email,
    uo.order_count,
    uo.total_spent
FROM active_users au
JOIN user_orders uo ON au.id = uo.user_id
ORDER BY uo.total_spent DESC;

Format your SQL queries instantly with our SQL Formatter tool.