This guide shows you how to add comments to your SQL code using both line and block syntax, and highlights two common traps that can break your queries or confuse your team. You’ll learn the exact syntax for MySQL, PostgreSQL, SQL Server, and Oracle, plus how to avoid the pitfalls that trip up even experienced developers.
What You’ll Need
- A text editor or SQL client where you can write and run queries (such as MySQL Workbench, pgAdmin, SSMS, or SQL Developer).
- Basic familiarity with writing SQL statements.
Step-by-Step
- Use two hyphens for a single-line comment. Place
--at the start of the comment. Everything after the hyphens until the end of that line is ignored by the database. For example:SELECT * FROM customers; -- returns all customers. In MySQL, you must add a space or control character after the--, so write-- commentnot--comment. In PostgreSQL, SQL Server, and Oracle, the space is optional but recommended for readability. - Use the hash symbol for a single-line comment in MySQL only. MySQL also supports
#for a line comment. This is not standard SQL, so avoid it if you might switch databases. Example:SELECT * FROM orders; # recent orders. - Use
/* */for a block comment. This syntax works in every major SQL database. Place/*at the start and*/at the end. Everything between them, even across multiple lines, is ignored. Example:/* This query fetches.
all active users */ SELECT * FROM users WHERE active = 1; - Nest block comments carefully. Standard SQL does not allow nested block comments. In PostgreSQL, you can nest them (
/* outer /* inner */ outer */), but in MySQL, SQL Server, and Oracle, nesting is not supported. The first*/ends the comment, which can cause syntax errors. To be safe, avoid nesting entirely. - Comment out a section of code to debug. Wrap a block of SQL in
/* ... */to temporarily disable it. This is faster than deleting and retyping. For example, to test a query without a JOIN, wrap the JOIN line in a block comment. - Use comments to document your logic. Add a line comment above a complex WHERE clause explaining the business rule, or a block comment at the top of a stored procedure describing its purpose, inputs, and outputs. This helps other developers (and your future self) understand the code.
- Be careful with comments inside a string literal. If you have a string that contains
--or/*, the database will treat it as part of the string, not as a comment. For example,SELECT '--not a comment';returns the literal text. This is correct behavior, but it means you cannot use comments to break a string across lines. - Check for hidden line breaks. A line comment ends at the newline character. If you copy code from a web page or email, the line break might be lost, causing the comment to swallow the rest of your query. Always verify that each
--comment is on its own logical line.
Common Mistakes
- Forgetting the space after
--in MySQL. MySQL requires a space or control character after the double hyphen. Writing--commentwill cause a syntax error. This is the most frequent trap for developers moving from other databases. - Using
--at the end of a line that continues. If you put a line comment at the end of a line and the next line is a continuation of the SQL statement, the comment will hide that continuation. For example:SELECT * FROM users -- active only– the
WHERE active = 1;WHEREclause is commented out, and you get all users, not just active ones. This silent change in results is dangerous. - Nesting block comments in databases that don’t support it. In MySQL, SQL Server, and Oracle,
/* outer /* inner */ outer */ends at the first*/, leavingouter */as uncommented code, which usually causes a syntax error. - Putting a comment inside a multi-line string. If you have a string literal that spans lines, you cannot insert a comment in the middle of it. The comment markers will be treated as string content.
Tips
- Use line comments for short, single-purpose notes. Use block comments for longer explanations or to temporarily disable multiple lines of code.
- Always put a space after
--even in databases that don’t require it. This makes your code portable and avoids surprises if you switch to MySQL. - When commenting out a block of code for debugging, add a clear marker like
-- DEBUGabove it so you remember to remove it later. - Keep comments in the same language as your team’s documentation. Mixing languages reduces their value.
- Update comments when you change the code. A stale comment is worse than no comment.
Troubleshooting
If your query fails with a syntax error near a comment, check these things in order:
- Look for
--without a space in MySQL. Add a space after the hyphens and try again. - Check for an unclosed block comment. Search for
/*and make sure each has a matching*/. Many editors highlight this; if not, count them manually. - Look for a line comment that extends too far. If your query runs but returns unexpected results, the issue is often a
--comment that swallowed the next line. Review every line that ends with--. - Verify you’re not inside a string. If your comment is inside single quotes, it’s not a comment. Check the quote balance in your query.
- Try removing comments one by one. If the error persists, comment out half of your query, then narrow down the problem area. This isolates the faulty comment.
Frequently Asked Questions
Can I use comments to hide sensitive data from users?
No. Comments are stripped out by the database engine and are never sent to the client. They are for developers only. To restrict data access, use views or column-level permissions.
Do comments affect query performance?
No. The database parser removes comments before execution. They have zero effect on speed or resource usage.
Can I put a comment between a function name and its parentheses?
Yes, in most databases you can write COUNT(/* comment */ *) or COUNT(*) /* comment */. However, you cannot put a comment inside the function name itself, like COUNT.
Is there a difference between -- and # in MySQL?
Functionally, no. Both create a line comment. The # is a MySQL-specific extension, while -- is standard SQL. Use -- for portability.
How do I comment out a large block of code that already contains comments?
You can’t safely do this with /* */ because nested comments are not supported in most databases. Instead, add -- to the start of each line, or use your editor’s block-comment toggle (often Ctrl+/ or Cmd+/).
Can comments appear anywhere in a SQL statement?
Almost anywhere whitespace is allowed. You can put them between keywords, after commas, or at the end of a statement. The only forbidden places are inside string literals and inside identifiers (like table or column names).
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Create App Shortcuts in Windows 10 Start Menu
- How to Rename a SQL Server Database
- Fix Google Calendar Not Syncing on iPhone
- Fix Skype Microphone Not Working on Windows
- Google Docs Landscape: Change Page Orientation
- Recover Deleted Admin Account in Windows 11