← All guides

SQL Formatting: Common Gotchas With Auto-Formatters

A one-line query is easy to read. A five-join query with nested subqueries and a dozen conditions in the WHERE clause is not, until someone puts every clause on its own line and indents consistently. That's all a SQL formatter does — it doesn't change what the query does, only how it's laid out.

select u.id, u.name, o.total from users u join orders o on u.id = o.user_id where o.total > 100 order by o.total desc

↓

SELECT
  u.id,
  u.name,
  o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.total > 100
ORDER BY o.total DESC

Keyword collisions with identifiers

A naive formatter that matches keywords as substrings can misfire on a table or column name that happens to contain one. A column literally named from_date shouldn't get split at FROM, and a table named deleted_users shouldn't trigger on DELETE. A correct formatter tokenizes with word boundaries — matches FROM only as a standalone keyword token, not as a substring anywhere it appears — and picks the longest matching keyword first so DELETE FROM isn't split into two separate lines at FROM when it should stay together as one clause.

Dialect differences the formatter doesn't know about

Generic formatting (indentation, keyword casing, clause line breaks) is dialect-agnostic and safe across MySQL, Postgres, SQLite, whatever you're using. What a generic formatter can't do is validate dialect-specific syntax — Postgres's ILIKE, MySQL's backtick-quoted identifiers, SQL Server's TOP instead of LIMIT. Formatting won't catch a query that's syntactically wrong for your actual database; it just makes correct queries easier to read and slightly easier to spot mistakes in by eye.

Comments can get separated from what they're describing

An inline comment (-- explains this join) placed at the end of a line will sometimes end up on its own line after reformatting if that line gets split. Worth a quick glance after formatting a query that had inline comments — not because it changes behavior, just because it can make the comment look like it's describing the wrong clause.

Try the SQL Formatter