Formateur SQL

What is SQL Formatting?

SQL formatting transforms compact or inconsistently written SQL queries into a readable, standardized layout with proper indentation, keyword capitalization, and clause alignment. Unlike application code that has universally adopted formatters like Prettier or Black, SQL formatting remains fragmented across teams and organizations. A well-formatted query reduces cognitive load during code review, makes logical errors visible at a glance, and establishes a shared baseline for collaborative database work. The formatting process is purely cosmetic — it does not alter query semantics, execution plans, or results.

SQL Formatting Conventions and Style Rules

SQL formatting conventions address three primary dimensions: keyword capitalization, clause indentation, and expression alignment. The most widely adopted convention capitalizes reserved keywords (SELECT, FROM, WHERE, JOIN) while keeping identifiers (table names, column names) in lowercase or their original case. This visual separation between language structure and user-defined names makes queries scannable without reading every token.

Clause indentation places each major clause (SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY) on its own line at the same indentation level, with their contents indented one level deeper. This river formatting style — named for the vertical "river" of whitespace that forms along the left margin — originated from Simon Holywell's SQL Style Guide and has become the de facto standard in many engineering organizations. Column lists in SELECT clauses typically place each column on its own line with a leading comma, which simplifies diffs in version control and makes it trivial to comment out individual columns during debugging.

Expression alignment handles operators and conditions within clauses. AND and OR operators in WHERE clauses start on new lines at the same indentation level, making boolean logic structure immediately apparent. Subqueries receive additional indentation, clearly marking scope boundaries even in deeply nested expressions.

Dialect Awareness: MySQL, PostgreSQL, SQL Server, and Oracle

SQL is not a single language — it is a family of dialects that share core syntax but diverge in functions, quoting rules, data types, and procedural extensions. A dialect-aware formatter recognizes these differences and applies appropriate rules for each target database. MySQL uses backtick quoting (`column_name`), PostgreSQL uses double quotes ("column_name"), and SQL Server uses square brackets ([column_name]). Formatting a PostgreSQL array operator (@>) or MySQL's LIMIT offset, count syntax requires the formatter to understand which tokens are operators versus identifiers.

PostgreSQL introduces Common Table Expressions (CTEs) with WITH RECURSIVE, window functions with complex OVER clauses, and lateral joins — all requiring specific indentation strategies. SQL Server's TOP clause, CROSS APPLY, and MERGE statements have unique formatting needs. Oracle's CONNECT BY hierarchical queries and MODEL clause demand specialized handling that generic formatters often get wrong. This tool supports dialect selection so that formatting rules match your target database engine precisely.

Handling Complex Queries: CTEs, Window Functions, and JOINs

Real-world SQL rarely consists of simple SELECT ... FROM ... WHERE patterns. Production queries involve Common Table Expressions (CTEs) that define reusable subqueries, window functions that compute aggregates across partitions, multi-table JOINs with complex conditions, and nested subqueries several levels deep. A formatter must handle all of these while maintaining readability.

CTEs benefit from treating each WITH block as a distinct visual unit, with the CTE name and AS keyword on one line and the enclosed query indented within parentheses. Window functions format best when the OVER clause is kept inline for simple partitions but broken across lines when combining PARTITION BY, ORDER BY, and frame specifications like ROWS BETWEEN. JOIN formatting places the join type and target table on one line with the ON condition indented below, making it easy to trace the relationship path through multiple tables.

Benefits for Code Review and Team Collaboration

Consistent SQL formatting directly improves code review quality. When every query follows the same structural conventions, reviewers can focus on logic — incorrect JOIN conditions, missing WHERE clauses, or unintended cross joins — instead of mentally parsing inconsistent layouts. Version control diffs become meaningful: a change to one column in a SELECT list produces a single-line diff rather than a reformatted block that obscures the actual modification.

Teams that adopt automated SQL formatting report faster onboarding for new members, fewer style-related review comments, and reduced risk of logic errors hiding in poorly structured queries. Integrating a formatter into CI pipelines ensures that committed SQL always meets the team standard, eliminating formatting debates entirely and freeing review time for correctness and performance analysis.

Code Examples

SQL formatting: before and after

-- Before formatting (compact, hard to review):
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 o.status = 'completed' and o.total > 100 order by o.created_at desc limit 20;

-- After formatting (structured, reviewable):
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 o.status = 'completed'
  AND o.total > 100
ORDER BY o.created_at DESC
LIMIT 20;

CTE and window function formatting

WITH monthly_revenue AS (
  SELECT
    DATE_TRUNC('month', created_at) AS month,
    SUM(total) AS revenue
  FROM orders
  WHERE status = 'completed'
  GROUP BY DATE_TRUNC('month', created_at)
)
SELECT
  month,
  revenue,
  LAG(revenue) OVER (ORDER BY month) AS prev_month,
  ROUND(
    (revenue - LAG(revenue) OVER (ORDER BY month))
    / LAG(revenue) OVER (ORDER BY month) * 100,
    2
  ) AS growth_pct
FROM monthly_revenue
ORDER BY month DESC;

Standards & Specifications

• SQL Style Guide (Simon Holywell) — Widely adopted SQL formatting conventions covering naming, indentation, and river formatting
• ISO/IEC 9075 (SQL Standard) — The international standard defining SQL syntax, grammar, and reserved keywords