comment(5)

COMMENT()                 SQL Commands                  COMMENT()

NAME

     COMMENT - define or change the comment of an object

SYNOPSIS

     COMMENT ON
     {
       TABLE object_name |
       COLUMN table_name.column_name |
       AGGREGATE agg_name (agg_type [, ...] ) |
       CAST (sourcetype AS targettype) |
       CONSTRAINT constraint_name ON table_name |
       CONVERSION object_name |
       DATABASE object_name |
       DOMAIN object_name |
       FUNCTION func_name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) |
       INDEX object_name |
       LARGE OBJECT large_object_oid |
       OPERATOR op (leftoperand_type, rightoperand_type) |
       OPERATOR CLASS object_name USING index_method |
       [ PROCEDURAL ] LANGUAGE object_name |
       ROLE object_name |
       RULE rule_name ON table_name |
       SCHEMA object_name |
       SEQUENCE object_name |
       TABLESPACE object_name |
       TRIGGER trigger_name ON table_name |
       TYPE object_name |
       VIEW object_name
     } IS 'text'

DESCRIPTION

     COMMENT stores a comment about a database object.

     To modify a comment, issue a new  COMMENT  command  for  the
     same  object.  Only  one  comment  string is stored for each
     object.  To remove a comment, write NULL  in  place  of  the
     text  string.   Comments  are automatically dropped when the
     object is dropped.

     Comments can be easily retrieved with the psql 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 (see in the documentation).

PARAMETERS

     object_name

     table_name.column_name

SQL - Language StatementLast change: 2008-01-03 1

COMMENT()                 SQL Commands                  COMMENT()

     agg_name

     constraint_name

     func_name

     op

     rule_name

     trigger_name
          The name of  the  object  to  be  commented.  Names  of
          tables, aggregates, domains, functions, indexes, opera-
          tors, operator classes, sequences, types, and views may
          be schema-qualified.

     agg_type
          An input data type  on  which  the  aggregate  function
          operates.  To reference a zero-argument aggregate func-
          tion, write * in place of the list of input data types.

     sourcetype
          The name of the source data type of the cast.

     targettype
          The name of the target data type of the cast.

     argmode
          The mode of a function argument:  either  IN,  OUT,  or
          INOUT.  If  omitted, the default is IN.  Note that COM-
          MENT ON FUNCTION does not actually pay any attention to
          OUT  arguments,  since  only  the  input  arguments are
          needed to determine the function's identity.  So it  is
          sufficient to list the IN and INOUT arguments.

     argname
          The name of a function argument.  Note that COMMENT  ON
          FUNCTION  does  not actually pay any attention to argu-
          ment names, since only  the  argument  data  types  are
          needed to determine the function's identity.

     argtype
          The data type(s) of the function's  arguments  (option-
          ally schema-qualified), if any.

     large_object_oid
          The OID of the large object.

     PROCEDURAL
          This is a noise word.

     text The new comment, written as a string literal;  or  NULL

SQL - Language StatementLast change: 2008-01-03 2

COMMENT()                 SQL Commands                  COMMENT()

          to drop the comment.

NOTES

     There is presently no security mechanism for  comments:  any
     user  connected  to  a database can see all the comments for
     objects in  that  database  (although  only  superusers  can
     change comments for objects that they don't own). For shared
     objects such as databases, roles, and  tablespaces  comments
     are  stored  globally and any user connected to any database
     can see all the  comments  for  shared  objects.  Therefore,
     don't put security-critical information in comments.

EXAMPLES

     Attach a comment to the table mytable:

     COMMENT ON TABLE mytable IS 'This is my table.';

     Remove it again:

     COMMENT ON TABLE mytable IS NULL;

     Some more examples:

     COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
     COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
     COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
     COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
     COMMENT ON DATABASE my_database IS 'Development Database';
     COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
     COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
     COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
     COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
     COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
     COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
     COMMENT ON OPERATOR - (NONE, text) IS 'This is a prefix operator on text';
     COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
     COMMENT ON ROLE my_role IS 'Administration group for finance tables';
     COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
     COMMENT ON SCHEMA my_schema IS 'Departmental data';
     COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
     COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
     COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
     COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
     COMMENT ON TYPE complex IS 'Complex number data type';
     COMMENT ON VIEW my_view IS 'View of departmental costs';

COMPATIBILITY

     There is no COMMENT command in the SQL standard.

SQL - Language StatementLast change: 2008-01-03 3