begriffs open source - ai-pg/blob - full-docs/txt/sql-comment.txt

   1
   2 COMMENT
   3
   4    COMMENT — define or change the comment of an object
   5
   6 Synopsis
   7
   8 COMMENT ON
   9 {
  10   ACCESS METHOD object_name |
  11   AGGREGATE aggregate_name ( aggregate_signature ) |
  12   CAST (source_type AS target_type) |
  13   COLLATION object_name |
  14   COLUMN relation_name.column_name |
  15   CONSTRAINT constraint_name ON table_name |
  16   CONSTRAINT constraint_name ON DOMAIN domain_name |
  17   CONVERSION object_name |
  18   DATABASE object_name |
  19   DOMAIN object_name |
  20   EXTENSION object_name |
  21   EVENT TRIGGER object_name |
  22   FOREIGN DATA WRAPPER object_name |
  23   FOREIGN TABLE object_name |
  24   FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  25   INDEX object_name |
  26   LARGE OBJECT large_object_oid |
  27   MATERIALIZED VIEW object_name |
  28   OPERATOR operator_name (left_type, right_type) |
  29   OPERATOR CLASS object_name USING index_method |
  30   OPERATOR FAMILY object_name USING index_method |
  31   POLICY policy_name ON table_name |
  32   [ PROCEDURAL ] LANGUAGE object_name |
  33   PROCEDURE procedure_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  34   PUBLICATION object_name |
  35   ROLE object_name |
  36   ROUTINE routine_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  37   RULE rule_name ON table_name |
  38   SCHEMA object_name |
  39   SEQUENCE object_name |
  40   SERVER object_name |
  41   STATISTICS object_name |
  42   SUBSCRIPTION object_name |
  43   TABLE object_name |
  44   TABLESPACE object_name |
  45   TEXT SEARCH CONFIGURATION object_name |
  46   TEXT SEARCH DICTIONARY object_name |
  47   TEXT SEARCH PARSER object_name |
  48   TEXT SEARCH TEMPLATE object_name |
  49   TRANSFORM FOR type_name LANGUAGE lang_name |
  50   TRIGGER trigger_name ON table_name |
  51   TYPE object_name |
  52   VIEW object_name
  53 } IS { string_literal | NULL }
  54
  55 where aggregate_signature is:
  56
  57 * |
  58 [ argmode ] [ argname ] argtype [ , ... ] |
  59 [ [ argmode ] [ argname ] argtype [ , ... ] ] ORDER BY [ argmode ] [ argname ] a
  60 rgtype [ , ... ]
  61
  62 Description
  63
  64    COMMENT stores a comment about a database object.
  65
  66    Only one comment string is stored for each object, so to modify a
  67    comment, issue a new COMMENT command for the same object. To remove a
  68    comment, write NULL in place of the text string. Comments are
  69    automatically dropped when their object is dropped.
  70
  71    A SHARE UPDATE EXCLUSIVE lock is acquired on the object to be
  72    commented.
  73
  74    For most kinds of object, only the object's owner can set the comment.
  75    Roles don't have owners, so the rule for COMMENT ON ROLE is that you
  76    must be superuser to comment on a superuser role, or have the
  77    CREATEROLE privilege and have been granted ADMIN OPTION on the target
  78    role. Likewise, access methods don't have owners either; you must be
  79    superuser to comment on an access method. Of course, a superuser can
  80    comment on anything.
  81
  82    Comments can be viewed using psql's \d family of commands. Other user
  83    interfaces to retrieve comments can be built atop the same built-in
  84    functions that psql uses, namely obj_description, col_description, and
  85    shobj_description (see Table 9.82).
  86
  87 Parameters
  88
  89    object_name
  90           relation_name.column_name
  91           aggregate_name
  92           constraint_name
  93           function_name
  94           operator_name
  95           policy_name
  96           procedure_name
  97           routine_name
  98           rule_name
  99           trigger_name
 100           The name of the object to be commented. Names of objects that
 101           reside in schemas (tables, functions, etc.) can be
 102           schema-qualified. When commenting on a column, relation_name
 103           must refer to a table, view, composite type, or foreign table.
 104
 105    table_name
 106           domain_name
 107           When creating a comment on a constraint, a trigger, a rule or a
 108           policy these parameters specify the name of the table or domain
 109           on which that object is defined.
 110
 111    source_type
 112           The name of the source data type of the cast.
 113
 114    target_type
 115           The name of the target data type of the cast.
 116
 117    argmode
 118           The mode of a function, procedure, or aggregate argument: IN,
 119           OUT, INOUT, or VARIADIC. If omitted, the default is IN. Note
 120           that COMMENT does not actually pay any attention to OUT
 121           arguments, since only the input arguments are needed to
 122           determine the function's identity. So it is sufficient to list
 123           the IN, INOUT, and VARIADIC arguments.
 124
 125    argname
 126           The name of a function, procedure, or aggregate argument. Note
 127           that COMMENT does not actually pay any attention to argument
 128           names, since only the argument data types are needed to
 129           determine the function's identity.
 130
 131    argtype
 132           The data type of a function, procedure, or aggregate argument.
 133
 134    large_object_oid
 135           The OID of the large object.
 136
 137    left_type
 138           right_type
 139           The data type(s) of the operator's arguments (optionally
 140           schema-qualified). Write NONE for the missing argument of a
 141           prefix operator.
 142
 143    PROCEDURAL
 144           This is a noise word.
 145
 146    type_name
 147           The name of the data type of the transform.
 148
 149    lang_name
 150           The name of the language of the transform.
 151
 152    string_literal
 153           The new comment contents, written as a string literal.
 154
 155    NULL
 156           Write NULL to drop the comment.
 157
 158 Notes
 159
 160    There is presently no security mechanism for viewing comments: any user
 161    connected to a database can see all the comments for objects in that
 162    database. For shared objects such as databases, roles, and tablespaces,
 163    comments are stored globally so any user connected to any database in
 164    the cluster can see all the comments for shared objects. Therefore,
 165    don't put security-critical information in comments.
 166
 167 Examples
 168
 169    Attach a comment to the table mytable:
 170 COMMENT ON TABLE mytable IS 'This is my table.';
 171
 172    Remove it again:
 173 COMMENT ON TABLE mytable IS NULL;
 174
 175    Some more examples:
 176 COMMENT ON ACCESS METHOD gin IS 'GIN index access method';
 177 COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample varianc
 178 e';
 179 COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
 180 COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
 181 COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
 182 COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
 183 COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
 184 COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain'
 185 ;
 186 COMMENT ON DATABASE my_database IS 'Development Database';
 187 COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
 188 COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';
 189 COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
 190 COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
 191 COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other data
 192 base';
 193 COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
 194 COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
 195 COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
 196 COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
 197 COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';
 198 COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
 199 COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
 200 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for b
 201 trees';
 202 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for
 203  btrees';
 204 COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
 205 COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';
 206 COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';
 207 COMMENT ON ROLE my_role IS 'Administration group for finance tables';
 208 COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a
 209 function or procedure)';
 210 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
 211 COMMENT ON SCHEMA my_schema IS 'Departmental data';
 212 COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
 213 COMMENT ON SERVER myserver IS 'my foreign server';
 214 COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';
 215 COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tab
 216 les';
 217 COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
 218 COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
 219 COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
 220 COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish langu
 221 age';
 222 COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
 223 COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
 224 COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore
 225  and Python dict';
 226 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 227 COMMENT ON TYPE complex IS 'Complex number data type';
 228 COMMENT ON VIEW my_view IS 'View of departmental costs';
 229
 230 Compatibility
 231
 232    There is no COMMENT command in the SQL standard.