SQL Comments | Academic Block

SQL COMMENTS

Learn how to write comments in SQL to document queries, explain database logic, and temporarily disable SQL statements.

What are SQL Comments?

SQL Comments are notes written inside SQL code that are ignored by the database engine. Comments help developers explain queries, document database logic, and make SQL code easier to understand and maintain.

Single-Line Comments

In SQLite, a single-line comment begins with two hyphens (--). Everything after -- on that line is treated as a comment.

DROP TABLE IF EXISTS books;

CREATE TABLE books (
  book_id INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  price REAL NOT NULL
);

-- Insert a few books into the table
INSERT INTO books (book_id, title, price)
VALUES
  (1, 'The Silent River', 450),
  (2, 'Beyond the Horizon', 620),
  (3, 'Modern Databases', 780);

-- Display all books
SELECT *
FROM books;

Comments at the End of a Line

A comment can also be placed after an SQL statement. The database ignores everything following the -- marker on that line.

DROP TABLE IF EXISTS students;

CREATE TABLE students (
  student_id INTEGER,
  student_name TEXT,
  score INTEGER
);

INSERT INTO students VALUES
  (1, 'Aarav', 88),   -- Mathematics
  (2, 'Meera', 92),   -- Science
  (3, 'Kabir', 79);  -- History

SELECT student_name, score
FROM students
WHERE score >= 85;   -- Show high scores

Multi-Line Comments

SQL also supports multi-line comments using /* and */. Everything between these markers is treated as a comment.

DROP TABLE IF EXISTS courses;

CREATE TABLE courses (
  course_id INTEGER PRIMARY KEY,
  course_name TEXT NOT NULL,
  duration INTEGER NOT NULL
);

/*
  Insert course information.
  Duration is stored in hours.
*/
INSERT INTO courses (course_id, course_name, duration)
VALUES
  (1, 'SQL Fundamentals', 20),
  (2, 'Web Development', 35),
  (3, 'Database Design', 25);

/*
  Display courses
  lasting more than 20 hours.
*/
SELECT *
FROM courses
WHERE duration > 20
ORDER BY duration DESC;

Commenting Out an SQL Statement

Comments can temporarily disable a statement without deleting it. This is useful when testing or troubleshooting SQL code.

DROP TABLE IF EXISTS products;

CREATE TABLE products (
  product_id INTEGER PRIMARY KEY,
  product_name TEXT NOT NULL,
  price REAL NOT NULL
);

INSERT INTO products (product_id, product_name, price)
VALUES
  (1, 'Wireless Mouse', 850),
  (2, 'Mechanical Keyboard', 3200),
  (3, 'USB Hub', 750);

-- This query is temporarily disabled:
-- DELETE FROM products WHERE product_id = 1;

SELECT *
FROM products
ORDER BY product_id;

Using Comments to Explain a Query

Comments can describe what different parts of a query are doing. This is particularly useful for queries containing filtering, sorting, grouping, or calculations.

DROP TABLE IF EXISTS sales;

CREATE TABLE sales (
  sale_id INTEGER PRIMARY KEY,
  product TEXT NOT NULL,
  quantity INTEGER NOT NULL,
  price REAL NOT NULL
);

INSERT INTO sales (sale_id, product, quantity, price)
VALUES
  (1, 'Notebook', 5, 120),
  (2, 'Desk Lamp', 2, 950),
  (3, 'USB Cable', 8, 300),
  (4, 'Keyboard', 3, 1800);

-- Calculate the total value of each product sale
SELECT
  product,
  quantity,
  price,
  quantity * price AS total_value
FROM sales
ORDER BY total_value DESC;

Comments with WHERE Conditions

Comments can make filtering conditions easier to understand, especially when a query contains several conditions.

DROP TABLE IF EXISTS employees;

CREATE TABLE employees (
  employee_id INTEGER PRIMARY KEY,
  employee_name TEXT NOT NULL,
  department TEXT NOT NULL,
  salary INTEGER NOT NULL
);

INSERT INTO employees
(employee_id, employee_name, department, salary)
VALUES
  (1, 'Nisha', 'Engineering', 72000),
  (2, 'Rohan', 'Marketing', 58000),
  (3, 'Ishita', 'Engineering', 68000),
  (4, 'Arjun', 'Support', 51000);

-- Find engineering employees
-- earning more than 65000
SELECT employee_name, salary
FROM employees
WHERE department = 'Engineering'
  AND salary > 65000
ORDER BY salary DESC;

Comments with Aggregate Functions

Comments are especially helpful when queries use aggregate functions such as COUNT(), SUM(), AVG(), MIN(), and MAX().

DROP TABLE IF EXISTS orders;

CREATE TABLE orders (
  order_id INTEGER PRIMARY KEY,
  customer TEXT NOT NULL,
  amount REAL NOT NULL
);

INSERT INTO orders (order_id, customer, amount)
VALUES
  (1, 'Riya', 1200),
  (2, 'Dev', 1850),
  (3, 'Riya', 950),
  (4, 'Tara', 2400),
  (5, 'Dev', 1100);

-- Calculate total spending for each customer
SELECT
  customer,
  COUNT(*) AS order_count,
  SUM(amount) AS total_spending,
  AVG(amount) AS average_order
FROM orders
GROUP BY customer
ORDER BY total_spending DESC;

Multi-Line Comments Inside a Query

A multi-line comment can also appear between different parts of an SQL statement.

DROP TABLE IF EXISTS movies;

CREATE TABLE movies (
  movie_id INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  genre TEXT NOT NULL,
  rating REAL NOT NULL
);

INSERT INTO movies (movie_id, title, genre, rating)
VALUES
  (1, 'Skybound', 'Adventure', 8.2),
  (2, 'Hidden Code', 'Thriller', 7.6),
  (3, 'Ocean Light', 'Drama', 8.7),
  (4, 'Final Orbit', 'Science Fiction', 8.4);

SELECT title, genre, rating

/* Only highly rated movies
   should appear in the result. */

FROM movies
WHERE rating >= 8.0
ORDER BY rating DESC;

Comments in Database Scripts

Comments can document database setup scripts by explaining table creation, sample data, relationships, and important operations.

-- Create the customers table
DROP TABLE IF EXISTS customers;

CREATE TABLE customers (
  customer_id INTEGER PRIMARY KEY,
  customer_name TEXT NOT NULL,
  city TEXT NOT NULL
);

-- Add sample customer records
INSERT INTO customers (customer_id, customer_name, city)
VALUES
  (1, 'Maya', 'Delhi'),
  (2, 'Kabir', 'Jaipur'),
  (3, 'Sara', 'Pune');

-- Retrieve customers from selected cities
SELECT *
FROM customers
WHERE city IN ('Delhi', 'Pune')
ORDER BY customer_name;

Single-Line vs Multi-Line Comments

Type	Syntax	Common Use
Single-Line	`-- comment`	Short explanations
Multi-Line	`/* comment */`	Longer explanations

Advantages of SQL Comments

Make SQL queries easier to understand.
Explain complex database operations.
Help developers maintain SQL scripts.
Can temporarily disable SQL statements during testing.
Provide useful documentation for database projects.

Best Practices

Use comments to explain why complex SQL logic exists.
Keep comments short and relevant.
Update comments when the SQL logic changes.
Use -- for simple single-line explanations.
Use /* ... */ for longer or multi-line explanations.
Avoid comments that simply repeat what the SQL statement obviously does.

SQL Comments are useful for documenting queries and making database scripts easier to read and maintain. In SQLite, use — for single-line comments and /* … */ for multi-line comments.

Ctrl + Enter to run SQL code Esc to close editor

🧪 Test Your SQL Code

Edit the SQL code on the left and click “Run Code” to see the result on the right.

📝 SQL Code

👁️ Preview (query result)

Click “Run Code” to see the result here.