SQL Comments

Just like every other programming language, SQL lets you write comments — text in your query that the database completely ignores when running it. Comments exist purely for humans: to leave notes, explain reasoning, or temporarily disable part of a query without deleting it.

Single-line comments

A double hyphen (--) starts a single-line comment. Everything from the -- to the end of that line is ignored by the database.

Single-line comments with --

SQL

-- Get every active customer in Canada
SELECT id, name
FROM customers
WHERE country = 'Canada' -- only Canadian customers
  AND is_active = true;

Multi-line comments

For longer notes, or to comment out several lines at once, use /* ... */. Everything between the opening /* and the closing */ is ignored, even if it spans multiple lines.

Multi-line comments with /* */

SQL

/*
  Report: monthly active customers by country.
  Owner: data-team
  Last updated: 2024-01-15
*/
SELECT country, COUNT(*) AS active_customers
FROM customers
WHERE is_active = true
GROUP BY country;

When comments actually earn their keep

SQL can get surprisingly dense — a single query with several joins, filters, and subqueries can hide a lot of business logic in a small space. Comments are most valuable when they explain the why behind a decision, not just restate what the SQL already makes obvious.

Explaining a non-obvious condition in a WHERE clause, e.g. why a specific status code or date cutoff is excluded
Documenting why a query is structured a particular way, such as a workaround for a known data quality issue
Flagging a query as auto-generated, or linking to the ticket/PR that introduced a tricky piece of logic
Leaving a TODO for a follow-up optimization or fix

A comment explaining the reasoning, not the syntax

SQL

SELECT *
FROM orders
-- Exclude test orders created by the QA team (see TICKET-482)
WHERE customer_id NOT IN (SELECT id FROM customers WHERE email LIKE '%@qa-test.internal');

Tip

Comments are also a handy debugging tool. While developing a longer query, you can prefix a line with -- to temporarily remove a condition or join and see how the results change, without deleting any code — then simply remove the -- to bring it back once you’re done experimenting.