What SQL is, and why formatting a query matters
SQL (Structured Query Language) is the standard language for querying and manipulating relational databases. Unlike JSON or XML, SQL is not a data format, it is a declarative instruction set: you describe the result you want and the database engine decides how to retrieve it. A SELECT statement can span two lines or two hundred; the database does not care about whitespace. Your colleagues and your future self do.
Unformatted SQL collapses joins, conditions, and subqueries into a single dense line that is nearly impossible to reason about under time pressure. A well-formatted query puts each major clause on its own line, indents joined tables under their parent FROM, aligns AND/OR conditions, and uppercase-caps keywords so they stand apart visually from table and column names. Code review, pair debugging, and audit trail documentation all move faster when the structure is visible at a glance.
SQL clause formatting conventions
Most style guides agree on these fundamentals: SQL keywords (SELECT, FROM, WHERE, JOIN, ON, GROUP BY, ORDER BY, HAVING, LIMIT) are written in uppercase. Table aliases are short and descriptive (o for orders, u for users). Each major clause starts on a new line at the same indentation level. Joining conditions and AND/OR predicates are indented one level deeper than the clause that contains them. Subqueries are indented further and wrapped in parentheses on their own lines.
| Element | Convention | Reason |
|---|---|---|
| Keywords | UPPERCASE (SELECT, WHERE) | Visual contrast with identifiers |
| Table/column names | lowercase or snake_case | Matches the actual schema names |
| Major clauses | Each on its own line | Readable scan top-to-bottom |
| AND / OR conditions | Leading operator, indented | Makes adding/removing conditions safe |
| Subqueries | Indented, closing ) on its own line | Nesting depth visible immediately |
| CTEs | WITH cte_name AS ( on one line | Named intermediate results readable in order |
Common SQL formatting challenges
Long IN lists: WHERE status IN ('active', 'pending', 'trial', 'paused') is more readable when each value goes on its own line when the list exceeds four items. Complex JOINs: Three or more joins benefit from aligning ON conditions under each JOIN keyword. CTEs (Common Table Expressions): A WITH clause with multiple named subqueries reads like a story if each CTE is named for what it produces and separated by a blank line. CASE expressions: Each WHEN branch should align, with END on its own line, so branch logic reads like a decision tree rather than a wall of text.
Dialect compatibility
This formatter targets ANSI SQL and handles MySQL, PostgreSQL, SQL Server, SQLite, Oracle, and BigQuery queries. Dialect-specific syntax, PostgreSQL's : cast operator, MySQL's backtick identifiers, SQL Server's [] quoted identifiers, or BigQuery's QUALIFY clause, is passed through unchanged. The formatter restructures indentation and keyword casing without interpreting execution semantics, so it is safe to use on stored procedures, DDL statements (CREATE TABLE, ALTER TABLE), and multi-statement migration scripts.
For related tools: use the JSON formatter when working with JSON columns in PostgreSQL, or the YAML formatter for database configuration files. See the CI/CD guide for integrating SQL linting into deployment pipelines.