FlowingDev

SQL, explained: the query language that loves to look good

Learn why consistently formatting SQL statements is crucial for readability, maintainability, and collaboration in any data-driven project.

Try the tool: SQL Viewer

In one sentence

SQL formatting is the practice of applying consistent style rules to SQL code to make it easier for humans to read, debug, and maintain.

The problem it solves

Structured Query Language (SQL) has been the king of data manipulation since the 1970s. It was designed for computers to talk to databases, and it does that job beautifully. The catch? The database engine couldn't care less about how your SQL looks.

To a computer, this:

SELECT u.id, p.profile_url, COUNT(c.id) AS comment_count FROM users u JOIN profiles p ON u.id = p.user_id LEFT JOIN comments c ON u.id = c.user_id WHERE u.signup_date > '2023-01-01' GROUP BY u.id, p.profile_url HAVING COUNT(c.id) > 5 ORDER BY comment_count DESC;

...is exactly the same as this:

select u.id,p.profile_url,count(c.id) as comment_count from users u join profiles p on u.id=p.user_id left join comments c on u.id=c.user_id where u.signup_date>'2023-01-01' group by u.id,p.profile_url having count(c.id)>5 order by comment_count desc;

This flexibility is great for the machine but a total nightmare for the human developer. As queries grow from simple lookups to complex multi-join, multi-subquery behemoths, unformatted SQL becomes a dense, unreadable wall of text. Trying to find a bug or understand the logic in a 100-line, single-block query is a recipe for a headache.

SQL formatting solves this human problem. It imposes a visual structure that mirrors the logical structure of the query. By adding line breaks, indentation, and consistent capitalization, it transforms a tangled mess into a clear, scannable document. It's not about making the code "pretty" for the sake of it; it's about making it understandable. It's a professional courtesy to your teammates and, most importantly, to your future self who has to debug this code at 3 AM.

How it works under the hood

A good SQL formatter is much more than a simple search-and-replace script. It's a language-aware tool that parses and understands your code before rewriting it. The process generally involves three main steps.

Step 1: Lexical Analysis (aka Tokenization)

First, the formatter scans the raw text of your SQL statement and breaks it down into a stream of "tokens." A token is the smallest meaningful unit of the language. Think of it as breaking a sentence into individual words and punctuation marks.

For a simple query like SELECT name FROM users;, the token stream would look something like this:

Token Text Token Type
SELECT KEYWORD
name IDENTIFIER
FROM KEYWORD
users IDENTIFIER
; PUNCTUATION

The lexer categorizes every piece of the input: keywords (SELECT, FROM, WHERE), identifiers (table and column names like users, name), operators (=, +, >), literals (strings like 'admin' or numbers like 42), and punctuation. This stream of tokens is the raw material for the next step.

Step 2: Parsing and the Abstract Syntax Tree (AST)

The list of tokens is just a flat sequence. To truly understand the query, the formatter needs to understand its grammatical structure. This is where parsing comes in. The parser takes the token stream and builds a hierarchical data structure called an Abstract Syntax Tree (AST).

The AST represents the logical structure of the code, much like a sentence diagram shows the relationship between a subject, verb, and object.

For our simple query SELECT name FROM users;, the AST might look like this in a simplified form:

- SelectStatement
  - SelectClause
    - SelectItem
      - Identifier: "name"
  - FromClause
    - Table: "users"

For a more complex query with a WHERE clause, the AST would have another branch for the WhereClause, which would in turn contain nodes representing the comparison operator and the values being compared. This tree is the formatter's "mental model" of your query. It no longer sees a string of text; it sees a SELECT statement with specific clauses and components.

Step 3: Pretty-Printing the Tree

This is where the magic happens. With the AST in hand, the formatter can now walk through the tree, node by node, and print it back out as a string, but this time applying a consistent set of rules.

The "pretty-printer" has a rule for every type of node in the AST:

  • When it sees a SelectStatement node, it knows to start a new line.
  • When it encounters a KEYWORD token like SELECT, a rule determines its case (e.g., UPPERCASE).
  • When it enters a FromClause, it knows to print FROM on a new line and indent the next part.
  • When it finds a list of columns in the SelectClause, it might have a rule to put each column on a new line if the list exceeds a certain length.
  • When it sees an operator token, it adds spaces around it (= becomes =).

By systematically traversing the AST and applying these rules, the formatter constructs the final, clean output. This approach is powerful because it's not just guessing based on text patterns. It understands that user in FROM users is a table name, but user inside 'user_profile.jpg' is just part of a string and should not be touched. It also allows formatters to handle different SQL dialects (e.g., PostgreSQL, MySQL, T-SQL), as the parser can be configured to understand the unique syntax and keywords of each.

Real-world stories

The Case of the Midnight Debugging Session

Priya, a senior engineer, was jolted awake by a PagerDuty alert: "Database CPU at 99%". She logged in and found the source: a single, monstrous SQL query running in a loop, consuming all the resources. The query had been committed an hour earlier by a junior dev. She opened the file and her heart sank. It was a 250-line block of unformatted SQL, a chaotic jumble of nested subqueries, case statements, and multiple JOINs. It was impossible to follow the logic.

Before even trying to understand it, she copied the entire blob of text and pasted it into a SQL formatter. Instantly, the beast was tamed. The formatted output, with clear indentation and line breaks, revealed the query's structure. And there it was, plain as day: a JOIN to a massive table with a missing ON condition, resulting in a catastrophic Cartesian product. She added the correct ON clause, pushed the fix, and watched the database CPU drop back to normal.

Lesson: Formatting isn't just about style; it's a critical first step in debugging. It makes logical structure visible, often revealing the bug in the process.

The Merger and the Mashup of Styles

Two startups merged, and their engineering teams were combined. The "Acme" team wrote SQL in all-caps, used trailing commas, and indented with tabs. The "Bolt" team used lowercase, leading commas, and indented with four spaces. Code reviews devolved into endless, passive-aggressive bickering about style. "Nit: we use lowercase keywords here," became the most common comment, completely derailing discussions about actual logic and performance.

The new tech lead, fed up with the style wars, implemented a simple rule: all SQL code must be passed through an automated formatter as part of the CI/CD pipeline before it can be merged. He configured the formatter with a neutral style guide and added it to the pre-commit hooks. The debates stopped overnight. The codebase slowly became uniform. Engineers could now focus on what the code did, not what it looked like.

Lesson: An automated, shared formatter is the ultimate peacemaker. It enforces consistency, eliminates pointless arguments, and lets teams focus on what matters.

The Analyst Who Couldn't Copy-Paste

Ben, a data analyst, needed to run a complex query to generate a quarterly sales report. An engineer emailed him the query. But when Ben copied it from his email client and pasted it into his database tool, it was a mess. The email client had added > characters to every line, inserted weird line breaks, and converted smart quotes. The query failed with a dozen syntax errors.

Frustrated after ten minutes of manually cleaning it up, Ben remembered the internal tools portal. He pasted the entire garbled mess from his email—> characters and all—into the SQL viewer. The tool was smart enough to ignore the email artifacts, parse the underlying SQL, and spit out a perfectly clean, executable query. He ran it and had his data in seconds.

Lesson: A robust formatter is more than a beautifier; it's a cleanup tool that can salvage code mangled by non-code-aware systems like email or chat.

Common mistakes and traps

  • Ignoring dialect differences. Formatting a Microsoft T-SQL query using a PostgreSQL ruleset is a bad idea. A formatter might "fix" TOP 10 by changing it to LIMIT 10, which would then cause a syntax error on SQL Server. Always ensure your formatter is configured for the correct SQL dialect.
  • Formatting generated code. Be very careful formatting SQL that is dynamically constructed by a program or an ORM (Object-Relational Mapper). That application might depend on a very specific—and often ugly—string structure. "Fixing" the whitespace could break the code that generates or reads it.
  • Arguing over the "perfect" style. The primary benefit of formatting is consistency. Wasting hours debating whether keywords should be uppercase or lowercase is counterproductive. Pick a sensible default (like a popular style guide) and let the tool enforce it.
  • Relying on formatting to fix bad logic. A formatter can make a slow, inefficient query look beautiful. It won't make it fast. Formatting makes bad logic visible, but it's still on you to fix the underlying performance or correctness issues.

Why it belongs on your radar

If you work with data, you work with SQL. And if you work with SQL in any professional capacity, you should care about its readability. You should think about SQL formatting whenever you:

  • Write a new query: Format it before you commit it. It's a gift to your colleagues.
  • Review someone else's code: If a query is hard to read, your first request should be, "Can you please run this through the formatter?"
  • Debug a complex query: Don't even try to read the raw code. Format it first.
  • Onboard to a new project: Look for their SQL style guide or formatter configuration. It's a quick way to learn the team's standards.
  • Set up a new project: Establish a formatting standard from day one and automate it in your CI/CD pipeline.

In short, formatting isn't an optional "nice-to-have." It's a fundamental part of writing professional, maintainable, and collaborative SQL.

Go deeper

  • Wikipedia: SQL: The high-level overview of the language itself.
  • dbt Labs SQL Style Guide: A widely respected and practical style guide for writing SQL in modern data teams.
  • SQLFluff Docs: The documentation for a popular, highly configurable SQL linter and formatter. Its "Rules" section is a great tour of all the things one can configure.
  • PostgreSQL: Lexical Structure: A deep dive into the official grammar and tokenization rules for one of the most popular SQL dialects.

Theory done. Time to get your hands dirty — 100% in your browser.

Try the tool: SQL Viewer