SQL Comment: Syntax, Usage, and Examples

A SQL comment allows you to include explanatory notes or temporarily disable parts of a query. You can make your SQL queries easier to understand, maintain, and debug by adding meaningful comments. Comments never get executed—they exist purely to help humans read the code.

How to Use SQL Comments

SQL supports two types of comments:

1. Single-Line Comment

Use two hyphens (--) to write a comment that spans only one line.

-- This query returns all active users
SELECT * FROM users WHERE status = 'active';

You can also place a single-line comment at the end of a statement:

SELECT * FROM users; -- Fetch all users

2. Multi-Line (Block) Comment

Use /* */ to write multi-line comments or block out parts of a SQL query.

/*
This query joins two tables:
- users
- orders
*/
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id;

You can also comment out a block of code using this style:

/*
SELECT * FROM orders;
*/

This feature is especially handy when you want to disable a large section temporarily.

When to Use SQL Comment in Your Queries

Explain Query Logic

Add a SQL comment above complex joins, filtering logic, or subqueries to describe what’s going on. You make it easier for others—and future you—to understand the query.

-- Get top 5 customers by order value
SELECT customer_id, SUM(total) as total_spent
FROM orders
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 5;

Document Business Rules

If a query includes specific logic that ties to business rules (like date cutoffs or special user types), explain why in a comment.

-- Only include users who joined after the product relaunch
SELECT * FROM users WHERE signup_date > '2024-01-01';

Temporarily Disable a Line or Block

When debugging, commenting in SQL helps you isolate parts of your query without deleting them.

-- SELECT * FROM products;
SELECT * FROM customers;

Or disable an entire section:

/*
SELECT * FROM audit_log;
SELECT * FROM error_log;
*/

This approach helps you test queries incrementally.

Examples of SQL Comment Usage

Inline Documentation Example

-- Add 10% bonus to salaries above 100K
SELECT employee_id, salary * 1.1 as new_salary
FROM employees
WHERE salary > 100000;

SQL Comment Block for Queries

/*
Query Description:
This report lists all invoices over $5000
issued in Q1 for the North America region.
*/
SELECT * FROM invoices
WHERE amount > 5000
AND region = 'North America'
AND invoice_date BETWEEN '2025-01-01' AND '2025-03-31';

SQL Shortcut to Comment All Highlighted Lines

Most code editors support shortcuts for commenting. For example:

• SSMS (SQL Server Management Studio): Ctrl + K, Ctrl + C to comment, Ctrl + K, Ctrl + U to uncomment.
• VS Code (with SQL extension): Ctrl + / to toggle comments.
• DataGrip or DBeaver: Ctrl + / or Cmd + / for Mac.

Using these SQL shortcuts to comment all highlighted lines speeds up development and testing.

Learn More About SQL Comments

Comment SQL Code in Stored Procedures

SQL comments are vital in stored procedures, views, and functions. Use comments to explain parameters, expected results, or known limitations.

/*
Procedure: get_active_customers
Returns all customers with active status.
Created by: Jane Doe
Updated: 2025-04-12
*/

This documentation helps teams understand what the procedure is doing at a glance.

Comments in SQL Script Files

When writing larger SQL script files—such as database migrations or data loading scripts—use comments liberally. Add headers, mark important sections, and record version info.

-- ========================
-- Create and Seed Users Table
-- ========================

CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(100),
    created_at DATE
);

-- Insert test data
INSERT INTO users VALUES (1, 'Sam', '2024-01-01');

This structure makes long scripts manageable.

SQL Query Comment Best Practices

• Avoid obvious comments. You don’t need to explain what SELECT does.
• Keep comments up-to-date. An outdated SQL comment causes confusion.
• Be specific. Instead of saying "filter data," say "filter out inactive users."
• Write for future maintainers. Imagine someone new reading your query with no context.

SQL Commenting for Collaboration

If multiple people edit the same SQL codebase or dashboard, comments help maintain consistency. You can include your name, reason for changes, or a link to a task ticket.

-- Modified by Alex for ticket #123: Adjusted cutoff date
SELECT * FROM subscriptions
WHERE start_date >= '2024-12-01';

This gives others a breadcrumb trail to follow.

How to Comment in SQL Across Different Databases

The syntax for SQL commenting is nearly universal, but some flavors behave slightly differently:

• MySQL, PostgreSQL, SQL Server, SQLite: All support - and /* */
• Oracle SQL: Also supports both styles, but line terminators can sometimes affect comments.
• BigQuery: Uses standard SQL comment syntax.
• Redshift: Same support for block and single-line comments.

In short, you can safely use both styles in most modern SQL engines.

SQL Comment Block and Code Readability

Adding a SQL comment block before each section of your query improves structure. For example:

-- ===========================
-- Section 1: Filter Active Users
-- ===========================
SELECT id, name
FROM users
WHERE active = 1;

-- ===========================
-- Section 2: Join with Purchases
-- ===========================
SELECT u.id, p.amount
FROM users u
JOIN purchases p ON u.id = p.user_id;

This makes it easy to follow even in complex scripts.