COMMENT

Description

Defines or changes the comment of an object.

Precautions

• Each object stores only one comment. Therefore, you need to modify a comment and issue a new COMMENT command to the same object. To delete the comment, write NULL at the position of the text string. When an object is deleted, the comment is automatically deleted.
• Currently, there is no security protection for viewing comments. Any user connected to a database can view all the comments for objects in the 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. Therefore, do not put security-critical information in comments.
• To comment objects, you must be an object owner or user granted the COMMENT permission. By default, system administrators have the permission.
• Roles do not have owners, so the rule for COMMENT ON ROLE is that you must be an administrator to comment on an administrator role, or have the CREATE ROLE permission to comment on non-administrator roles. A system administrator can comment on all objects.

Syntax

COMMENT ON
{
  AGGREGATE agg_name (agg_type [, ...] ) |
  CAST (source_type AS target_type) |
  COLLATION object_name |
  COLUMN { table_name.column_name | view_name.column_name } |
  CONSTRAINT constraint_name ON table_name |
  CONVERSION object_name |
  DATABASE object_name |
  DOMAIN object_name |
  EXTENSION object_name |
  FOREIGN DATA WRAPPER object_name |
  
  FUNCTION function_name ( [ {[ argname ] [ argmode ] argtype} [, ...] ] ) |
  INDEX object_name |
  LARGE OBJECT large_object_oid |
  OPERATOR operator_name (left_type, right_type) |
  OPERATOR CLASS object_name USING index_method |
  OPERATOR FAMILY object_name USING index_method |
  [ PROCEDURAL ] LANGUAGE object_name |
  ROLE object_name |
  RULE rule_name ON table_name |
  SCHEMA object_name |
  SERVER 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 |
  TYPE object_name |
  VIEW object_name |
  TRIGGER trigger_name ON table_name
}
   IS 'text';

Parameters

• agg_name

  Specifies the new name of an aggregate function.

• agg_type

  Specifies the data type of the aggregate function parameters.

• source_type

  Specifies the source data type of the cast.

• target_type

  Specifies the target data type of the cast.

• object_name

  Specifies the name of an object.

• table_name.column_name

  view_name.column_name

  Specifies a column name. You can add the table name or view name as the prefix.

• constraint_name

  Specifies the name of a table constraint.

• table_name

  Specifies the name of a table.

• function_name

  Specifies a function name.

• argname,argmode,argtype

  Specifies the name, schema, and type of the function parameters.

• large_object_oid

  Specifies an OID of a large object.

• operator_name

  Specifies the name of the operator.

• left_type,right_type

  Specifies the data type of the operator parameters (optionally schema-qualified). If the prefix or suffix operator does not exist, the NONE option can be added.

• trigger_name

  Specifies the trigger name.

• text

  Specifies the comment content.

Examples

-- Create a table.
gaussdb=# CREATE TABLE emp(
    empno varchar(7),
    ename varchar(50),
    job varchar(50),
    mgr varchar(7),
    deptno int
);

-- Add comments to a table.
gaussdb=# COMMENT ON TABLE emp IS 'Department table';

-- Add comments to columns.
gaussdb=# COMMENT ON COLUMN emp.empno  IS  'Employee ID';
gaussdb=# COMMENT ON COLUMN emp.ename  IS  'Employee name';
gaussdb=# COMMENT ON COLUMN emp.job    IS  'Job';
gaussdb=# COMMENT ON COLUMN emp.mgr    IS  'Manager ID';
gaussdb=# COMMENT ON COLUMN emp.deptno IS  'Department ID';

-- View table comments.
gaussdb=# \d+
                                                    List of relations
 Schema | Name | Type  | Owner |  Size   |                             Storage                              | Description 
--------+------+-------+-------+---------+------------------------------------------------------------------+-------------
public | emp | table | omm | 0 bytes | {orientation=row,compression=no,storage_type=USTORE,segment=off} | Department table
(1 row)

-- View column comments.
gaussdb=# \d+ emp
                                 Table "public.emp"
 Column |         Type          | Modifiers | Storage  | Stats target | Description 
--------+-----------------------+-----------+----------+--------------+-------------
 empno  | character varying(7)  |           | extended |              | Employee ID
 ename  | character varying(50) |           | extended |              | Employee name
 job    | character varying(50) |           | extended |              | Job
 mgr    | character varying(7)  |           | extended |              | Manager ID
 deptno | integer               |           | plain    |              | Department ID
Has OIDs: no
Options: orientation=row, compression=no, storage_type=USTORE, segment=off


-- Delete the emp table.
gaussdb=# DROP TABLE emp;