MySQL Comments

Last updated: October 19, 2026Oct 19, 2026

Comments are notes in your SQL that MySQL ignores. They explain why a query is written the way it is, help teammates understand migration scripts, and let you temporarily switch off a line while testing. MySQL also lets you store comments on tables and columns, so the documentation lives inside the database.

1. The Three Comment Styles

-- monthly salary report
SELECT name,            # employee name
       salary * 12 AS annual_salary   /* yearly cost */
FROM employees
WHERE dept = 'IT';

Result: 2 rows

2. Why -- Needs a Space

MySQL treats -- as a comment only when followed by whitespace. This avoids ambiguity in expressions like 5--3, which MySQL reads as 5 minus negative 3:

SELECT 5--3 AS no_space_means_math;

Result: 1 row

SELECT 5 -- 3
  AS with_space_rest_is_comment;

Result: 1 row

3. Multi-line Comments

/*
  Report: IT department payroll
  Owner : data team
  Note  : salaries are monthly, in INR
*/
SELECT COUNT(*) AS it_staff, SUM(salary) AS monthly_cost
FROM employees
WHERE dept = 'IT' /* AND salary > 50000 */;

Result: 1 row

Wrapping a condition in /* … */ is a handy way to switch it off while testing. C-style comments can't be nested.

4. Executable Version Comments /*! */

A comment that starts with /*! is executed by MySQL but ignored by other databases. With a version number, MySQL runs it only on that version or newer. mysqldump uses this heavily, for example /*!40101 SET NAMES utf8mb4 */.

SELECT 1 /*! + 1 */ AS mysql_adds_one, 10 /*!99999 * 100 */ AS skipped_on_older_versions;

Result: 1 row

5. Optimizer Hints /*+ */

A comment starting with /*+ right after SELECT, UPDATE or DELETE gives the optimizer instructions:

SELECT /*+ MAX_EXECUTION_TIME(1000) */ name FROM employees;     -- stop after 1 second
SELECT /*+ NO_INDEX(employees) */ * FROM employees WHERE id = 3;

6. Comments on Tables and Columns

The COMMENT clause stores documentation in the data dictionary, where tools such as MySQL Workbench and IntelliJ show it:

CREATE TABLE leave_requests (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  emp_id     INT NOT NULL COMMENT 'employees.id of the requester',
  days       DECIMAL(3,1) NOT NULL COMMENT 'half days allowed, e.g. 1.5',
  status     ENUM('pending','approved','rejected') DEFAULT 'pending' COMMENT 'set by the manager'
) COMMENT = 'Leave applications submitted through the HR portal';

SELECT column_name, column_comment
FROM information_schema.columns
WHERE table_schema = 'hr' AND table_name = 'leave_requests';

Result: 4 rows

SELECT table_name, table_comment FROM information_schema.tables WHERE table_schema = 'hr' AND table_comment <> '';

Result: 1 row

Change a comment later with ALTER TABLE leave_requests COMMENT = '…' or by modifying the column.

7. Writing Good Comments

• Explain why, not what: -- exclude test accounts created by QA beats -- where id > 1000.
• Put a header comment at the top of migration scripts: purpose, author, ticket number.
• Keep comments up to date; a wrong comment is worse than none.
• Use COMMENT on columns whose meaning isn't obvious (units, codes, allowed values).
• Don't leave large blocks of commented-out SQL in production scripts; version control keeps the history.

8. Summary

• Single-line comments: -- (with a space) and #; multi-line: /* … */.
• /*! … */ runs only on MySQL (optionally only on a minimum version); /*+ … */ holds optimizer hints.
• COMMENT clauses document tables and columns inside the database.
• Comment the why, keep comments current.