DEV Community

Snappy Tools
Snappy Tools

Posted on

Why Formatted SQL Is Worth the Extra Keystrokes

#webdev #productivity #beginners #tools

Unformatted SQL is a maintenance hazard. A single query stretching across 300 characters with no line breaks is hard to read in a code review, nearly impossible to debug in a log file, and a nightmare to modify six months later.

Formatting SQL costs nothing and saves significant time. Here's why it matters and what consistent formatting looks like.

What "Formatted SQL" Actually Means

Formatted SQL doesn't mean anything fancy — it's just consistent whitespace, capitalisation, and alignment that makes the structure of a query visible at a glance.

Before:

select u.id,u.email,o.total,o.created_at from users u left join orders o on u.id=o.user_id where u.created_at>'2024-01-01' and o.status='completed' order by o.created_at desc limit 100
Enter fullscreen mode Exit fullscreen mode

After:

SELECT
  u.id,
  u.email,
  o.total,
  o.created_at
FROM users u
LEFT JOIN orders o
  ON u.id = o.user_id
WHERE u.created_at > '2024-01-01'
  AND o.status = 'completed'
ORDER BY o.created_at DESC
LIMIT 100;
Enter fullscreen mode Exit fullscreen mode

The query is identical — the database doesn't care about whitespace. But the second version makes the joins, conditions, and selected columns immediately scannable.

The Code Review Argument

SQL in code reviews is often the most poorly reviewed part of a pull request. Reviewers skim past a wall of unformatted SQL because parsing its structure mentally is too much cognitive work. Formatted SQL gets reviewed properly because:

  • You can see at a glance which tables are joined and how
  • You can spot missing index conditions in the WHERE clause
  • You can identify whether SELECT * is being used (it shouldn't be)
  • You can check that joins have explicit conditions on the right columns

A reviewer who can read your SQL quickly is more likely to catch bugs — a suboptimal join condition, a missing NULL check, a Cartesian product hiding in a FROM clause.

Capitalisation Conventions

There are two camps:

UPPERCASE keywords — SELECT, FROM, WHERE, JOIN. The traditional SQL style, still the most common in professional environments and documentation. Makes keywords visually distinct from table/column names.

lowercase keywords — select, from, where, join. Preferred by some modern teams, particularly those writing SQL inside application code (Python SQLAlchemy, JavaScript knex.js) where all-caps feels like shouting.

Pick one and stick to it. The worst option is inconsistency — some queries in uppercase, some in lowercase, mixed within the same file.

Indentation Rules That Actually Help

The goal of SQL indentation is to make the logical structure of the query visible:

-- Main clauses at the left margin
SELECT
  column1,           -- Selected columns indented one level
  column2,
  column3
FROM primary_table
LEFT JOIN secondary_table
  ON primary_table.id = secondary_table.fk_id   -- JOIN conditions indented
WHERE condition1 = 'value'
  AND condition2 > 0                             -- AND/OR conditions aligned
  AND (
    sub_condition1 = 1                           -- Grouped conditions indented further
    OR sub_condition2 = 2
  )
ORDER BY column1 DESC;
Enter fullscreen mode Exit fullscreen mode

The structure tells you: what am I selecting, from where, joined to what, filtered how, sorted how. You shouldn't need to read every word to understand the shape of the query.

Common Formatting Mistakes

Putting everything on one line. The database doesn't care, but your future self will hate you for it.

Mixing alignment styles. If you indent JOIN conditions, indent all JOIN conditions. Inconsistency in the same query is more confusing than no indentation at all.

No spaces around operators. WHERE id=5 is harder to read than WHERE id = 5. Always space around =, >, <, !=, LIKE.

Not aliasing tables. FROM very_long_table_name JOIN another_long_table_name ON very_long_table_name.id = another_long_table_name.fk is hard to read. Use aliases: FROM orders o JOIN users u ON o.user_id = u.id.

Forgetting the semicolon. In multi-statement scripts, missing semicolons cause silent failures. Get in the habit.

Formatting Tools

You don't have to format SQL by hand. Most SQL IDEs (DataGrip, DBeaver, VS Code with SQLTools) have built-in formatters. For quick formatting of a query you've copied from a log or a colleague's message, the SQL Formatter & Beautifier at SnappyTools handles MySQL, PostgreSQL, and Transact-SQL in the browser — paste your query, click Format, copy the result.

Useful for one-off formatting without leaving your current context.

A Note on Dialects

SQL syntax varies between databases. Standard formatting rules apply universally, but some syntax is dialect-specific:

  • MySQL: backtick quoting for identifiers `table_name`
  • PostgreSQL: double-quote identifiers "table_name", strong adherence to SQL standard
  • Transact-SQL (SQL Server): bracket quoting [table_name], TOP instead of LIMIT

If you're writing SQL that will run on multiple databases, stick to standard SQL where possible and make the dialect explicit in comments or filenames.

The Bottom Line

Formatted SQL is professional SQL. It signals that you thought about the query carefully enough to make it readable, which is a reliable indicator that you also thought about whether it's correct and performant.

The next time you're about to paste a single-line query into a code review, spend 30 seconds formatting it first. Your reviewers will thank you — and your future self will too.

Top comments (0)