How to Comment in SQL

What you’ll build or solve

You’ll add clear single-line and multi-line comments to SQL queries and scripts.

When this approach works best

This approach works best when:

• You are writing complex queries with joins or aggregations.
• You are sharing SQL scripts with teammates.
• You want to temporarily disable part of a query during testing.

Avoid adding comments for obvious statements. If the SQL already explains itself, extra text adds noise.

Prerequisites

• Access to a SQL database such as MySQL, PostgreSQL, SQL Server, or SQLite
• Basic understanding of SQL queries

No additional setup is required.

Step-by-step instructions

Step 1: Choose the right comment syntax

SQL supports two main comment styles. Pick the one that fits your situation.

Option A: Single-line comments with -

Use -- to comment out everything after it on the same line.

-- Get active users
SELECT id, name, email
FROM users
WHERE active = 1;

You can also place comments at the end of a line:

SELECT id, name -- basic user info
FROM users
WHERE active = 1; -- only active accounts

Single-line comments are ideal for short explanations or temporarily disabling a condition:

SELECT id, name
FROM users
WHERE active = 1
-- AND role = 'admin'
;

Option B: Multi-line comments with /* */

Use /* to start and */ to end a multi-line comment.

/*
 This query retrieves users who signed up this year
 and have completed at least one order.
*/
SELECT u.id, u.name
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.created_at >= '2026-01-01';

Multi-line comments work well for longer explanations or section headers in scripts:

/* ===========================
   Create users table
   =========================== */
CREATE TABLE users (
  id INT PRIMARY KEY,
  name VARCHAR(100),
  email VARCHAR(150),
  active BOOLEAN
);

What to look for

• Use comments to explain why something is done, not what the SQL syntax already shows.
• You can safely comment out filters during testing, but avoid leaving AND or OR without conditions.
• Section comments improve readability in longer migration or setup scripts.
• Always close multi-line comments with /.
• For portability across SQL dialects, prefer - and /* */.

Examples you can copy

Example 1: Document business logic

SELECT id, name, created_at
FROM users
WHERE active = 1
AND created_at >= '2026-01-01'
-- Include only active users created this year
;

This clarifies reporting intent without changing the query.

Example 2: Temporarily disable a condition

SELECT id, total
FROM orders
WHERE total > 100
-- AND status = 'completed'
;

This lets you test broader results without deleting logic.

Example 3: Structure a reporting script

/* Monthly revenue report */
SELECT DATE_TRUNC('month', created_at) AS month,
       SUM(total) AS revenue
FROM orders
GROUP BY DATE_TRUNC('month', created_at)
ORDER BY month;

/* Top customers */
SELECT user_id, SUM(total) AS total_spent
FROM orders
GROUP BY user_id
ORDER BY total_spent DESC;

Clear section comments help future readers understand script structure.

Example 4: Explain a non-obvious join

SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id
-- Join on user_id because orders store foreign key reference
WHERE o.total > 200;

This explains reasoning that may not be obvious from the schema alone.

Common mistakes and how to fix them

Mistake 1: Forgetting to close a multi-line comment

You might write:

/*
Get all active users
SELECT *
FROM users;

Why it breaks:

Everything after /* is treated as a comment, causing a syntax error.

Correct approach:

/*
Get all active users
*/
SELECT *
FROM users;

Always close multi-line comments properly.

Mistake 2: Breaking logical conditions when commenting

You might write:

SELECT *
FROM users
WHERE active = 1
AND -- role = 'admin'
;

Why it breaks:

The AND operator has no condition after it.

Correct approach:

SELECT *
FROM users
WHERE active = 1;

Or comment out the entire condition:

SELECT *
FROM users
WHERE active = 1
-- AND role = 'admin'
;

Mistake 3: Using unsupported comment syntax

You might try:

# Get active users
SELECT * FROM users;

Why it breaks:

# is not supported in all SQL dialects.

Correct approach:

-- Get active users
SELECT * FROM users;

Stick to -- or /* */ for cross-database compatibility.

Troubleshooting

If you see a syntax error near /*, confirm every multi-line comment has a matching */.

If a query fails after commenting something out, check for leftover AND or OR operators.

If your script runs partially, verify that a comment did not remove a semicolon or closing parenthesis.

If comments behave differently across tools, confirm your SQL dialect supports the syntax used.

Quick recap

• SQL supports two comment styles: - and /* */.
• Use - for short, single-line comments.
• Use /* */ for longer explanations or section headers.
• Comment out full conditions, not partial expressions.
• Always close multi-line comments properly.
• Avoid unsupported comment styles like #.