COMMENT
Defines or changes the comment of an object.
Synopsis
COMMENT ON
{ ACCESS METHOD <object_name> |
AGGREGATE <aggregate_name> (<aggregate_signature>) |
CAST (<source_type> AS <target_type>) |
COLLATION <object_name>
COLUMN <relation_name>.<column_name> |
CONSTRAINT <constraint_name> ON <table_name> |
CONSTRAINT <constraint_name> ON DOMAIN <domain_name> |
CONVERSION <object_name> |
DATABASE <object_name> |
DOMAIN <object_name> |
EVENT TRIGGER <object_name> |
EXTENSION <object_name> |
FOREIGN DATA WRAPPER <object_name> |
FOREIGN TABLE <object_name> |
FUNCTION <function_name> [([[<argmode>] [<argname>] <argtype> [, ...]])] |
INDEX <object_name> |
MATERIALIZED VIEW <object_name> |
OPERATOR <operator_name> (<left_type>, <right_type>) |
OPERATOR CLASS <object_name> USING <index_method> |
OPERATOR FAMILY <object_name> USING <index_method> |
POLICY <policy_name> ON <table_name> |
[PROCEDURAL] LANGUAGE <object_name> |
PROCEDURE <procedure_name> [([[<argmode>] [<argname>] <argtype> [, ...]])] |
RESOURCE GROUP <object_name> |
RESOURCE QUEUE <object_name> |
ROLE <object_name |
ROUTINE <routine_name> [([[<argmode>] [<argname>] <argtype> [, ...]])] |
RULE <rule_name> ON <table_name> |
SCHEMA <object_name> |
SEQUENCE <object_name> |
SERVER <object_name> |
STATISTICS <object_name> |
TABLE <object_name> |
TABLESPACE <object_name> |
TEXT SEARCH CONFIGURATION <object_name> |
TEXT SEARCH DICTIONARY <object_name> |
TEXT SEARCH PARSER <object_name> |
TEXT SEARCH TEMPLATE <object_name> |
TRANSFORM FOR <type_name> LANGUAGE <lang_name> |
TRIGGER <trigger_name> ON <table_name> |
TYPE <object_name> |
VIEW <object_name>
} IS { <string_literal> | NULL }
-- where <aggregate_signature> is:
* |
[ <argmode> ] [ <argname> ] <argtype> [ , ... ] |
[ [ <argmode> ] [ <argname> ] <argtype> [ , ... ] ] ORDER BY [ <argmode> ] [ <argname> ] <argtype> [ , ... ]
Description
COMMENT
stores a comment about a database object. Only one comment string is stored for each object, so to modify a comment, issue a new COMMENT
command for the same object. To remove a comment, specify NULL
in place of the text string. Comments are automatically dropped when the object is dropped.
Apache Cloudberry acquires a SHARE UPDATE EXCLUSIVE
lock on the object to be commented.
For most kinds of object, only the object's owner can set the comment. Roles don't have owners, so the rule for COMMENT ON ROLE
is that you must be superuser to comment on a superuser role, or have the CREATEROLE
privilege to comment on non-superuser roles. Likewise, access methods don't have owners either; you must be superuser to comment on an access method. Of course, a superuser can comment on anything.
You can view comments using the psql
meta-commands \dd
, \d+
, and \l+
. Other user interfaces to retrieve comments can be built atop the same built-in functions that psql
uses, namely obj_description()
, col_description()
, and shobj_description()
.
Parameters
object_name
relation_name.column_name
aggregate_name
constraint_name
function_name
operator_name
policy_name
procedure_name
routine_name
rule_name
trigger_name
The name of the object to be commented. Names of tables, aggregates, collations, conversions, domains, foreign tables, functions, indexes, operators, operator classes, operator families, procedures, routines, sequences, statistics, text search objects, types, views, and materialized views can be schema-qualified. When commenting on a column, relation_name must refer to a table, view, materialized view, composite type, or foreign table.
Note Apache Cloudberry does not support triggers.
table_name
domain_name
When creating a comment on a constraint, a trigger, a rule, or a policy, these parameters specify the name of the table or domain on which that object is defined.
source_type
The name of the source data type of the cast.
target_type
The name of the target data type of the cast.
argmode
The mode of a function or aggregate argument: either IN
, OUT
, INOUT
, or VARIADIC
. If omitted, the default is IN
. Note that COMMENT
does not actually pay any attention to OUT
arguments, since only the input arguments are needed to determine the function's identity. It is sufficient to list the IN
, INOUT
, and VARIADIC
arguments.
argname
The name of a function, procedure, or aggregate argument. Note that COMMENT
does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity.
argtype
The data type of a function, procedure, or aggregate argument.
left_type
right_type
The data type(s) of the operator's arguments (optionally schema-qualified). Specify NONE
for the missing argument of a prefix or postfix operator.
PROCEDURAL
Apache Cloudberry ignores this noise word.
type_name
The name of the data type of the transform.
lang_name
The name of the language of the transform.
string_literal
The new comment contents, written as a string literal.
NULL
Specify NULL
to drop the comment.
Notes
There is presently no security mechanism for viewing comments: any user connected to a database can see all of the comments for objects in that database. For shared objects such as databases, roles, and tablespaces, comments are stored globally so any user connected to any database in the cluster can see all the comments for shared objects.
Caution Do not put security-critical information in comments.
Examples
Attach a comment to the table mytable
:
COMMENT ON TABLE mytable IS 'This is my table.';