How to Write Clean and Readable SQL Queries Your Team Will Appreciate

Why SQL Formatting Actually Matters

A SQL query that returns the correct result is not enough if nobody can understand it three months later. SQL queries live in codebases for years. A query written today for a report will likely still be running in five years, modified by four people who did not write the original. Inconsistent formatting makes understanding intent much harder than it needs to be.

Badly formatted SQL also makes bugs easier to miss. A subquery buried in the middle of an unindented SELECT clause can be misread. A missing parenthesis around a set of OR conditions changes the logic dramatically and is far harder to spot in wall-of-text SQL than in well-structured SQL.

Core SQL Formatting Conventions

Uppercase keywords make the structure immediately visible. Write SQL reserved words in UPPERCASE: SELECT, FROM, WHERE, JOIN, GROUP BY, ORDER BY, HAVING, INSERT INTO, UPDATE, DELETE FROM. Keep column names and table names in their original case. The visual distinction between keywords and identifiers shows query structure at a glance.

One clause per line keeps the structure navigable. Each major clause starts on a new line. SELECT, FROM, WHERE, GROUP BY and ORDER BY each get their own line. This makes adding, removing or commenting out individual clauses straightforward.

Indented column lists and conditions add clarity. Selected columns go one per line indented under SELECT. WHERE conditions go one per line indented under WHERE, with AND and OR at the start of each condition line rather than the end of the previous one.

Explicit JOIN syntax beats comma-separated FROM clauses. Use explicit JOIN and ON keywords rather than listing tables in FROM with join conditions buried in WHERE. Explicit joins are clearer, easier to read and prevent accidental cross joins.

Meaningful table aliases help in complex queries. Single-letter aliases work in simple queries but become confusing when eight tables are joined. Abbreviations like 'user_orders uo' communicate intent far better than just 'o'.

Formatted vs Unformatted: A Real Example

Unformatted:

select u.name,count(o.id) as order_count,sum(o.total) as revenue from users u inner join orders o on u.id=o.user_id where o.created_at>'2024-01-01' and o.status='completed' group by u.id,u.name having count(o.id)>5 order by revenue desc limit 10

Formatted:

SELECT
  u.name,
  COUNT(o.id) AS order_count,
  SUM(o.total) AS revenue
FROM users u
INNER JOIN orders o ON u.id = o.user_id
WHERE
  o.created_at > '2024-01-01'
  AND o.status = 'completed'
GROUP BY u.id, u.name
HAVING COUNT(o.id) > 5
ORDER BY revenue DESC
LIMIT 10

Same query. The formatted version takes a few seconds to understand. The unformatted version takes considerably longer, and that is for a relatively simple query.

Using a SQL Formatter

Our SQL Formatter supports SELECT, INSERT, UPDATE, DELETE and CREATE TABLE statements along with complex nested subqueries. It handles MySQL, PostgreSQL, SQLite, T-SQL, BigQuery and MariaDB dialects with appropriate keyword capitalisation and quoting conventions for each.

Paste messy SQL and get clean, consistently formatted output instantly. Useful for reformatting queries copied from logs, standardising auto-generated SQL from ORMs or cleaning up a team's shared query library.