How to Comment in SQL

A comment in SQL can be used in a couple of different ways. One usage of SQL comments is to provide documentation about what your code is doing. This is often helpful if you have complicated queries that need more explanation. It can help other SQL developers to know why you did something in a certain way.

You can also use comments to tell the database to ignore certain portions of code. Sometimes you might comment out a line or section of code. When you do this, the database ignores it completely. You can often use this when you’re working on writing a new query and need to test things out. For example, you might comment out a line in your WHERE clause to see a larger data set. It saves you from having to remember or re-type that piece of code.

There are two basic types of comments in SQL: inline comments and block comments. All of the major database platforms (like MySQL, PostgreSQL, and SQL Server) support commenting. For the most part, the method you use for comments in SQL is the same across platforms as well.

How to Comment in SQL With Inline Comments

Inline comments are comments that are on a single line. They can either take up the entire line or they can come at the end of a line of code. You can use two consecutive dashes to indicate an inline comment: --. For example, you might use an inline comment before your query to describe what the query does.

-- This query will retrieve all projects for customer ID = 1
SELECT *
FROM projects
WHERE customer_id = 1

The first line will be ignored by the database. Anything after the -- and to the end of that line will be completely ignored.

You can also use an inline comment at the end of a line. Just remember that the database will ignored everything after the --.

SELECT project_name,
    project_start_date, -- project_end_date,
    customer_id
FROM projects
WHERE customer_id = 1

In this query, we are only going to get columns for project_name, project_start_date, and customer_id. The project_end_date field comes after the comment dashes and is therefore ignored by the database.

Using SQL Block Comments

Another way to comment in SQL is using block comments. These are comments that can span one or more lines. There is a slightly different way of indicating block comments in SQL. You start with a forward-slash followed by an asterisk: /* and then you close the comment with an asterisk and a forward-slash */ to indicate the end of a comment.

Block comments can be anywhere within a query – even within the middle of a line. The database will ignore anything between the start and end of the comment.

As an example, you could use a block comment to provide a detailed description of your query right at the beginning.

/*
    This query is going to 
    retrieve the sum of the
    task hours by project.
*/
SELECT SUM(t.estimated_hours) AS total_hours,
   p.project_name
FROM tasks t
INNER JOIN projects p ON p.id = t.project_id
GROUP BY p.project_name

Here you can see the comment at the beginning of the query spans multiple lines. The database will completely ignore the comment when you run the query.

As an another example, let’s look at an example of a block comment in the middle of a line. This will be similar to our inline comment above, but with a different result.

SELECT project_name,
    project_start_date, /* this is a comment */ project_end_date,
    customer_id
FROM projects
WHERE customer_id = 1

In this case, we still have a comment on the same line. But because we’re using a block comment, the selection of the project_end_date column isn’t going to be ignored. The database will return that as a column in our data set because it’s outside of our block comment.

Database Platform-Specific SQL Commenting

There are a few things to know about commenting on different database platforms.

MySQL allows for a hashtag or pound sign # to be used as an inline comment indicator. It also supports the two consecutive dashes -- as inline comments. These two comment indicators function in the same way.

PostgreSQL actually supports a COMMENT command. Note that this is not a SQL standard command, so it’s not going to work on MySQL or SQL Server. This allows you to store comments about a given object – like a table, column, or constraint – directly within the database.

Commenting in SQL is very easy to learn. It’s also very useful as a tool to enhance your development as well as for documenting your work. Even if you’re the only person working on a query, you should document your work with comments. This way if you come back to it weeks or months later, you’ll remember why you did things a certain way.