How to Comment Characters in PostgreSQL

1. Basic Commenting in PostgreSQL
2. Comment in PSQL - The PostgreSQL Command-Line Utility
3. COMMENT on Specific Objects in PostgreSQL

This article will introduce how we can comment on a character or a set of characters in PostgreSQL.

Many languages use comments as a way for the programmer to explain how a certain code or a specific part of it works.

It is mostly followed by a symbol and then an entire line perceived as a comment by the parser. In PostgreSQL, we comment using the -- keyword, followed by a specific comment.

Basic Commenting in PostgreSQL

To comment on anything in a Postgres query, use the following syntax for your code.

-- [comment string] (STANDARD SQL SINGLE LINE)
or
/* [comment string
    comment string 2] */ (STANDARD SQL MULTI LINE CODE)

Comments are removed before further syntax analysis occurs as they are deemed unnecessary for query execution.

So to comment on something, go to your query and do something as follows.

-- This is a test comment

And if you tend to run the code with something like this, your code will still execute properly as the characters are part of the comment and will not meddle with your code syntax. To do the same thing in multi-line with a bigger comment string, write something as follows.

/*
I am working on a test string
that is effectively better
with multiple lines
*/

Hence, you can see how easy it is to COMMENT in PostgreSQL. But this methodology works perfectly for PGADMIN[Version_NO] or any other GUI that can run PostgreSQL.

We must keep a few points in mind if we refer to the command line utility or bash. Let’s see what they are below.

Comment in PSQL - The PostgreSQL Command-Line Utility

Let’s boot up PSQL and try commenting as we did in PGADMIN.

select  * from DOGGY; --postgres

Executing the above query returns us the correct results. But what if we try to do the same with a \ command. Running the following query.

\dt --display relations

Output:

Did not find any relation named "--display".
\dt: extra argument "relations" ignored

And it’s not just the case with the DT command. Executing any other query in PSQL containing a SLASH will possibly ignore comments.

Hence to resolve this, we can go ahead and instead of writing comments next to a query in PostgreSQL, we can take the COMMENT and run it before the SLASH commands. In this manner, the comment will not be ignored, but we will also be able to implement a clean version of our working code.

postgres=# --postgres
postgres=# \dt

Running the command above will now give us the result we desire. Also, there will be no more IGNORE errors.

The above command works simply by appending the -- POSTGRES before the \DT and then executing.

SLASH commands in PSQL are also known as META-COMMANDS. Let’s now look at various other ways of putting comments in PSQL.

Use the \ECHO to Comment in PSQL

Running the following query tends to work perfectly.

\dt \echo display table

And displays the following result:

The \ECHO in PSQL tends to print arguments to the OUTPUT. So when you write the comment next to \ECHO, it will print that comment in the console.

Hence, a beautiful way to add comments in PSQL.

Use \WARN as an Alternative to the \ECHO Command in PSQL for Commenting

Another command that can print comments in the console is \WARN. It is similar to \ECHO; however, the output is printed to the standard error channel.

This does not make a difference. It will work perfectly if you run the query with the \WARN command.

\dt \warn display_table;

Because PSQL's standard error channel is the console, any comment next to \ECHO will be printed right after the execution of the preceding command.

Use \ and Then -- to Comment in PSQL

\dt \\ --display_table_check

The above query returns us the table but does not print any comment on the console. \\ is the SEPARATOR meta-command and is used to specify that the two different ends meeting it are not to be joined in any scenario.

In our case, \dt is an entirely separate command than the -- comment, and it could be that PSQL, without the specification of \\, might have assumed that both were one command.

Now that we have learned how to comment in PSQL and PGADMIN, there are still a few other options that you can explore, which we will cover in short here for you to follow and implement if the above are not according to your needs and wants.

COMMENT on Specific Objects in PostgreSQL

The COMMENT keyword is another efficient method to comment on specific objects in a PostgreSQL database. You can read up on COMMENT here: URL.

As for now, we will use the example of TABLE and comment on it using this.

COMMENT on table DOGGY is 'The Dogs table is amazing!';

And then, to view this comment, switch to PSQL and run the command; \d+. This will return a table to view our comments in the DESCRIPTION column.

So if we run the query in PSQL, we will get something as follows.

Output:

Hence, using COMMENT helps us avoid syntax errors and is also an efficient way to keep comments simple, effective, and specific.

So today, we learned how we could comment in a PostgreSQL session. Of course, different methods are required for different scenarios.

Using COMMENT, for example, would be of much help if other programmers had to check descriptions and detailed explanations of objects rather than the “working of the code that created them”. Hence, it is up to you which method you choose.

As always, make sure to read our tutorials properly to better understand the functioning of our code.