SQL Formatting Best Practices: Write Database Queries That Don't Make Your Team Cry

I've been reviewing SQL queries professionally for over a decade, and I can tell you one universal truth: poorly formatted SQL is the silent productivity killer in engineering teams. A single 500-line query with no indentation, inconsistent capitalization, and zero line breaks can add hours to debugging time.

The difference between a maintainable database query and a nightmare isn't the logic—it's the formatting. In this guide, I'll show you the SQL formatting standards used by top engineering teams, how to automatically beautify queries, and the subtle dialect differences between PostgreSQL, MySQL, and SQL Server that trip up even experienced developers.

Why SQL Formatting Actually Matters

Before diving into the "how," let's talk about the "why." Clean SQL formatting isn't pedantry—it's pragmatism:

• Code Reviews: Formatted SQL makes it obvious when logic changes, not just whitespace
• Debugging: When a query fails at 3 AM, proper formatting helps you spot the issue in seconds instead of minutes
• Performance Tuning: Understanding query structure is the first step to optimization
• Team Onboarding: New developers can understand your database schema faster when queries are readable
• ORM Output: ORMs generate terribly formatted SQL—cleaning it helps you understand what your framework is actually doing

The Core Principles of SQL Formatting

Before we get into specific rules, here are the three foundational principles that guide all SQL formatting decisions:

1. Visual Hierarchy Matches Logical Structure

Your indentation should mirror the logical structure of your query. Nested subqueries should be visually nested. JOINs at the same level should align vertically.

2. Keywords Are Signposts

SQL keywords (SELECT, FROM, WHERE, JOIN) should be easy to scan. Uppercase keywords act as visual markers that help you quickly navigate complex queries.

3. Consistency Beats Cleverness

The "best" formatting style is the one your whole team uses consistently. Having a style guide is more important than which specific style you choose.

The Standard SQL Formatting Rules

Here's the formatting style I recommend, based on what I've seen work across dozens of teams:

Rule 1: Uppercase Keywords

SQL keywords should be UPPERCASE. Column names, table names, and values stay lowercase/as-defined:

select users.id, users.name, count(*)
from users
where users.created_at > '2024-01-01'

SELECT users.id, users.name, COUNT(*)
FROM users
WHERE users.created_at > '2024-01-01'

Rule 2: One Clause Per Line

Major clauses (SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY) should start on their own line:

SELECT
  users.id,
  users.name,
  users.email
FROM users
WHERE users.status = 'active'
  AND users.created_at > '2024-01-01'
ORDER BY users.created_at DESC
LIMIT 100;

Rule 3: Indent Nested Subqueries

Use 2 or 4 spaces (not tabs) for each level of nesting:

SELECT
  user_id,
  total_orders
FROM (
  SELECT
    user_id,
    COUNT(*) as total_orders
  FROM orders
  WHERE status = 'completed'
  GROUP BY user_id
) AS order_counts
WHERE total_orders > 5;

Rule 4: Align JOIN Conditions

JOINs should be indented and aligned for visual clarity:

SELECT
  users.name,
  orders.total,
  products.name
FROM users
  INNER JOIN orders
    ON users.id = orders.user_id
  INNER JOIN order_items
    ON orders.id = order_items.order_id
  INNER JOIN products
    ON order_items.product_id = products.id
WHERE users.status = 'active';

Rule 5: One Column Per Line in SELECT

When selecting multiple columns, put each on its own line with a leading comma (or trailing comma):

SELECT
  users.id
  , users.name
  , users.email
  , users.created_at
  , COUNT(orders.id) AS order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
GROUP BY users.id;

PostgreSQL vs MySQL vs SQL Server: Dialect Differences

While standard SQL syntax is mostly universal, each database has quirks that affect formatting:

PostgreSQL Specifics

• Array Notation: SELECT ARRAY[1, 2, 3]
• JSON Operators: WHERE data->>'name' = 'John'
• CTEs: Heavily used, format with attention to readability
• Dollar Quoting: $$text$$ for strings with quotes

MySQL Specifics

• Backticks: `table_name` for identifiers with special chars
• LIMIT Syntax: LIMIT 10 OFFSET 20 (differs from SQL Server)
• String Concatenation: CONCAT() function required

SQL Server Specifics

• Square Brackets: [Table Name] for identifiers
• TOP Instead of LIMIT: SELECT TOP 10 * FROM...
• OFFSET/FETCH: OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY

Formatting Complex Queries: Real-World Examples

Let's take a messy query and clean it up step by step:

Before (ORM Output)

select users.id,users.name,(select count(*) from orders where user_id=users.id and status='completed') as order_count from users where users.created_at>'2023-01-01' and users.status='active' order by order_count desc limit 10

This is what comes out of many ORMs. It's a 270-character one-liner that's nearly impossible to understand at a glance.

After (Formatted)

SELECT
  users.id,
  users.name,
  (
    SELECT COUNT(*)
    FROM orders
    WHERE user_id = users.id
      AND status = 'completed'
  ) AS order_count
FROM users
WHERE users.created_at > '2023-01-01'
  AND users.status = 'active'
ORDER BY order_count DESC
LIMIT 10;

Same query, but now you can:

• Instantly see the subquery is counting completed orders
• Spot the two WHERE conditions at a glance
• Understand that we're limiting to top 10 by order count

Advanced Formatting: Window Functions and CTEs

Modern SQL uses advanced features like window functions and Common Table Expressions (CTEs). Here's how to format them:

Window Functions

SELECT
  user_id,
  order_date,
  amount,
  SUM(amount) OVER (
    PARTITION BY user_id
    ORDER BY order_date
  ) AS running_total,
  ROW_NUMBER() OVER (
    PARTITION BY user_id
    ORDER BY amount DESC
  ) AS rank_by_amount
FROM orders;

CTEs (WITH Clauses)

WITH active_users AS (
  SELECT id, name
  FROM users
  WHERE status = 'active'
),
user_orders AS (
  SELECT
    user_id,
    COUNT(*) AS order_count,
    SUM(total) AS total_spent
  FROM orders
  GROUP BY user_id
)
SELECT
  au.name,
  COALESCE(uo.order_count, 0) AS orders,
  COALESCE(uo.total_spent, 0) AS spent
FROM active_users au
LEFT JOIN user_orders uo ON au.id = uo.user_id
ORDER BY spent DESC;

Team SQL Style Guide Template

Here's a copy-paste style guide you can adapt for your team:

# SQL Style Guide

## Keywords
- UPPERCASE for all SQL keywords (SELECT, FROM, WHERE, JOIN)
- lowercase for table names, column names, and aliases

## Indentation
- Use 2 spaces per indentation level
- No tabs

## Line Breaks
- One major clause per line (SELECT, FROM, WHERE, etc.)
- One column per line in SELECT statements
- One condition per line in WHERE clauses

## Commas
- Leading commas for multi-line column lists
- Trailing commas for INSERT statements

## Joins
- Each JOIN on its own line
- ON conditions indented 2 spaces
- Multiple ON conditions: one per line, aligned with first

## Subqueries
- Indent entire subquery 2 spaces
- Wrap in parentheses with opening paren on same line

## Aliases
- Use AS keyword for column aliases
- Use AS keyword for table aliases (optional)
- Aliases should be descriptive (not a, b, c)

## Comments
- Use -- for single-line comments
- Use /* */ for multi-line comments
- Add comments for complex business logic

## Naming
- snake_case for table and column names
- Avoid reserved keywords as identifiers

Automated SQL Formatting Tools

Don't format SQL manually! Use these tools to automate the process:

IDE Extensions

• VS Code: SQL Formatter, PostgreSQL Formatter
• JetBrains: Built-in SQL formatter in DataGrip, IntelliJ
• Sublime Text: SQLTools, SQL Beautifier

Online Tools

• GetDevUtils SQL Formatter: Free, privacy-focused, local processing
• SQL Format: Web-based with multiple dialects
• Instant SQL Formatter: Advanced options with preview

Command-Line Tools

• pg_format: PostgreSQL formatter (Perl-based)
• sqlfluff: Linter and formatter with auto-fix
• sql-formatter: Node.js library for multiple dialects

Pre-Commit Hooks for SQL Formatting

Enforce formatting standards automatically with git pre-commit hooks:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/sqlfluff/sqlfluff
    rev: 2.3.5
    hooks:
      - id: sqlfluff-lint
      - id: sqlfluff-fix

Now every commit automatically formats SQL to your team's standards.

Common SQL Formatting Mistakes

Mistake #1: Mixing Capitalization Styles

Don't do this:

Select users.ID, users.Name
from USERS
Where users.status = 'active'

Mistake #2: No Indentation for Subqueries

This is unreadable:

SELECT * FROM (
SELECT id FROM users WHERE status='active'
) AS active_users

Mistake #3: Inconsistent Alias Usage

Use aliases consistently or not at all:

-- Bad: Mixed styles
SELECT u.name, orders.total
FROM users u, orders

-- Good: Consistent aliases
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id

SQL Formatting for Different Scenarios

For Version Control

Format SQL in migration files consistently so git diffs show actual logic changes, not whitespace changes.

For Documentation

Add comments explaining business logic:

-- Calculate lifetime value for customers
-- who have made purchases in the last 90 days
SELECT
  user_id,
  SUM(amount) AS ltv
FROM orders
WHERE created_at > CURRENT_DATE - INTERVAL '90 days'
GROUP BY user_id;

For Performance Tuning

Format queries to make EXPLAIN ANALYZE output easier to correlate:

EXPLAIN ANALYZE
SELECT
  users.name,
  COUNT(orders.id) AS order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
WHERE users.status = 'active'
GROUP BY users.id
HAVING COUNT(orders.id) > 5;

Conclusion: Clean SQL is Professional SQL

SQL formatting might seem like a minor detail, but it's a marker of professional engineering. Well-formatted queries:

• Save hours of debugging time
• Make code reviews faster and more effective
• Help junior developers learn faster
• Prevent subtle bugs from hiding in complexity
• Make performance optimization easier

Start with the basics: uppercase keywords, one clause per line, consistent indentation. Use automated tools to enforce your style guide. Your future self (and your teammates) will thank you.

← Back to Blog | GetDevUtils Home