SQL Formatter - Complete Guide

SQL formatting transforms messy, single-line queries into readable, properly indented SQL. This is essential for code reviews, documentation, debugging, and maintaining SQL codebases. Well-formatted SQL is easier to understand, modify, and catch errors in.

How It Works

The formatter parses SQL syntax, identifies clauses (SELECT, FROM, WHERE, etc.), and applies consistent formatting rules: keywords uppercase/lowercase, proper indentation for nested queries, line breaks at logical points, and aligned columns. It preserves the query's functionality while improving readability.

Technical Details

SQL formatting involves: tokenization (identifying keywords, identifiers, literals), clause detection (SELECT, FROM, WHERE, JOIN, GROUP BY, etc.), nested query handling, and style application. Dialects (MySQL, PostgreSQL, SQL Server, Oracle) have syntax variations that formatters must handle.

Common Use Cases

1. Code Review: Format SQL for readable pull request reviews.
   • Example: SELECT * FROM users WHERE active=1 → properly indented multi-line
2. Query Debugging: Format complex queries to identify logical errors.
3. Documentation: Format SQL examples in documentation and tutorials.
4. Legacy Code Cleanup: Standardize formatting across old SQL codebases.
5. Query Optimization: Readable queries make optimization opportunities clearer.

Code Examples

Before and After Formatting

-- Before (hard to read)
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 10;

-- After (formatted)
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 10;

Each clause on its own line, consistent indentation, aligned conditions. Much easier to scan and modify.

Using sql-formatter library

import { format } from 'sql-formatter';

const formatted = format(
  'SELECT * FROM users WHERE id = 1',
  {
    language: 'postgresql',
    tabWidth: 4,
    keywordCase: 'upper',
    linesBetweenQueries: 2,
  }
);

// Output:
// SELECT
//     *
// FROM
//     users
// WHERE
//     id = 1

sql-formatter supports multiple SQL dialects and customizable style options.

Command Line

# Using sqlformat (Python)
pip install sqlparse
sqlformat --reindent --keywords upper -o output.sql input.sql

# Using pgFormatter (PostgreSQL)
pg_format -u 1 input.sql > output.sql

# In-place formatting
sqlformat --reindent -a input.sql

sqlparse is a Python library with CLI. pgFormatter is specialized for PostgreSQL.

Tips & Best Practices

• Agree on formatting standards with your team and enforce via CI
• Use IDE extensions for automatic formatting on save
• Keep related conditions together for readability
• Comment complex joins and subqueries
• Consider trailing vs leading commas based on team preference

Common Mistakes to Avoid

• Inconsistent keyword casing within a project
• Over-indenting simple queries
• Not aligning related elements (JOINs, AND/OR conditions)
• Forgetting to handle dialect-specific syntax

When to Use This Tool

Use SQL formatter whenever writing, reviewing, or documenting SQL queries. Essential for team codebases, code reviews, and anywhere SQL readability matters.

Frequently Asked Questions

Should SQL keywords be uppercase or lowercase?

Both are valid - SQL is case-insensitive for keywords. Uppercase (SELECT, FROM, WHERE) is traditional and makes keywords stand out from identifiers. Lowercase is more modern and easier to type. Choose one and be consistent.

How should I format JOIN clauses?

Put each JOIN on its own line, indent ON conditions. Align join conditions for readability. Example:\nFROM users u\n INNER JOIN orders o ON u.id = o.user_id\n LEFT JOIN items i ON o.id = i.order_id

What about long SELECT column lists?

Options: 1) One column per line (best for many columns), 2) Multiple columns per line with logical grouping, 3) Leading commas (makes adding/removing columns easier). Align columns when using multiple lines.

How should subqueries be indented?

Increase indent level for subqueries. The opening parenthesis stays on the same line, closing parenthesis aligns with the clause that contains it. Treat each subquery as its own formatted query.

Does formatting change query execution?

No, SQL formatting is purely cosmetic. The database receives the same logical query regardless of whitespace. Some tools minify SQL to reduce network payload, but this doesn't affect performance.

Get Started

Ready to try SQL Formatter? Use the tool now - it's free, fast, and works right in your browser.

---

Last updated: June 27, 2026