Comments are blocks of text which, through special character sequences, can be used to embed non-SQL text within SQL code. These can be used within blocks of code, because PostgreSQL removes the commented areas from the input stream and treats it as whitespace. There are two styles of comments available: single-line comments, and multi-line comments.
Single-line comments are preceded by two dashes ( -- ), and may either be on a line by themselves, or they may follow valid SQL tokens. (The comments themselves are not considered tokens to PostgreSQL's parser, as any character data following the -- sequence (up to the end of the line) is treated as whitespace.) This is demonstrated in Example 3-11 .
Example 3-11. Single-line comments
testdb=# SELECT 'Test' -- This can follow valid SQL tokens, testdb-# -- or be on a line of it own. testdb-# AS example; example --------- Test (1 row)
Multi-line comments are begun with a sequential slash-asterisk ( /* ) sequence, and are terminated with a sequential asterisk-slash ( */ ) sequence. This style of commenting may already be familiar to C programmers, but there is one key difference between PostgreSQL's interpretter and the C language interpretter: PostgreSQL comments may be nested . Therefore, when creating a multi-line comment within another multi-line comment does not cause the entire commented area to be terminated prematurely when a single */ sequence is reached.
Example 3-12. Multi-line comments
testdb=# SELECT 'Multi' /* This comment extends across testdb*# * numerous lines, and can be testdb*# * /* nested safely */ */ testdb-# || '-test' AS example; example ------------ Multi-test (1 row)
Nesting these kinds of comments can be useful if you have a file containing SQL syntax that you wish to comment a large portion of before sending to PostgreSQL for interpretting and execution. If you have already used multi-line comments within that document, and you wish to comment a large section which includes those comments, PostgreSQL is intelligent enough to recognize that a closing comment sequence ( */ ) only closes the most recently opened comment, and not the entire commented region.
|Asterisks in comments|
The asterisk character by itself (without an adjacent slash character) has no special meaning within a comment. The extra asterisks in Example 3-12 on multi-line comments are provided only for aesthetic purposes and readability.