SQL Formatting Best Practices for Developers

Why Format SQL?

SQL (Structured Query Language) is English-like, which leads many developers to write it as unstructured blocks of text.

SELECT u.id, u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id WHERE o.total > 100 ORDER BY o.total DESC;

While the database engine parses this happily, it is a nightmare for humans to read, debug, or review. Consistent formatting reduces cognitive load and makes logic errors obvious.

Core Formatting Rules

1. Capitalization (UpperSnake vs LowerCamel)

The standard convention is:

• Keywords: UPPERCASE (SELECT, FROM, WHERE)
• Identifiers: lowercase_snake_case (table_name, user_id)

Good:

SELECT first_name, last_name 
FROM users

Bad:

select First_Name, Last_Name
from Users

2. New Lines (The "River" Pattern)

Place each major clause (SELECT, FROM, WHERE, GROUP BY) on its own line. Align the keywords to the right or left to create a clean visual edge.

Left Aligned (Most Common):

SELECT 
    user_id, 
    email
FROM 
    users
WHERE 
    created_at > '2025-01-01';

3. Indentation

Indent lists of columns, join conditions, and sub-clauses. 4 spaces or 2 spaces are both acceptable, but be consistent.

SELECT
    o.order_id,
    c.customer_name,
    SUM(oi.price) as total_price
FROM
    orders o
    JOIN customers c ON o.customer_id = c.id
    JOIN order_items oi ON o.id = oi.order_id
GROUP BY
    o.order_id,
    c.customer_name

4. Joins

Always separate joins onto new lines. Indent the ON condition or keep it on the same line if short.

FROM
    employees e
    LEFT JOIN departments d ON e.dept_id = d.id
    LEFT JOIN locations l ON d.loc_id = l.id

Advanced Formatting

CTEs (Common Table Expressions)

CTEs make queries more readable than nested subqueries. Format them with clear boundaries.

WITH Sales_Data AS (
    SELECT 
        region, 
        SUM(amount) as revenue 
    FROM 
        transactions
    GROUP BY 
        region
)

SELECT 
    * 
FROM 
    Sales_Data 
WHERE 
    revenue > 10000;

Subqueries

Always indent the content of a subquery.

SELECT name 
FROM products 
WHERE id IN (
    SELECT product_id 
    FROM inventory 
    WHERE quantity < 5
);

Naming Conventions

1. Tables: Plural (users, products).
2. Primary Keys: id or table_name_id. Be consistent.
3. Foreign Keys: singular_table_name_id (e.g., user_id).
4. Aliases: Use short but meaningful aliases.
   • Good: FROM users u, FROM orders o
   • Bad: FROM users a, FROM orders b

Comments

Use comments for why not what.

• -- for single line comments.
• /* ... */ for multi-line comments.

-- Filter out test accounts created by QA
WHERE email NOT LIKE '%@test.com'

Conclusion

Adopting a SQL style guide (like the one provided by SQL Formatter tools) ensures your team speaks the same language. It turns your SQL from "executable noise" into "executable documentation."

Use our SQL Formatter to instantly beautify your ugly queries into standard, readable SQL.