granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/comment.sgml

   1 <!--
   2 doc/src/sgml/ref/comment.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-COMMENT">
   7  <refmeta>
   8   <refentrytitle>COMMENT</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>COMMENT</refname>
  15   <refpurpose>define or change the comment of an object</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-comment">
  19   <primary>COMMENT</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 COMMENT ON
  25 {
  26   AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable> [, ...] ) |
  27   CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) |
  28   COLLATION <replaceable class="PARAMETER">object_name</replaceable> |
  29   COLUMN <replaceable class="PARAMETER">relation_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable> |
  30   CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  31   CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
  32   DATABASE <replaceable class="PARAMETER">object_name</replaceable> |
  33   DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
  34   EXTENSION <replaceable class="PARAMETER">object_name</replaceable> |
  35   FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> |
  36   FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> |
  37   FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
  38   INDEX <replaceable class="PARAMETER">object_name</replaceable> |
  39   LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> |
  40   OPERATOR <replaceable class="PARAMETER">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_type</replaceable>) |
  41   OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
  42   OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
  43   [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
  44   ROLE <replaceable class="PARAMETER">object_name</replaceable> |
  45   RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  46   SCHEMA <replaceable class="PARAMETER">object_name</replaceable> |
  47   SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> |
  48   SERVER <replaceable class="PARAMETER">object_name</replaceable> |
  49   TABLE <replaceable class="PARAMETER">object_name</replaceable> |
  50   TABLESPACE <replaceable class="PARAMETER">object_name</replaceable> |
  51   TEXT SEARCH CONFIGURATION <replaceable class="PARAMETER">object_name</replaceable> |
  52   TEXT SEARCH DICTIONARY <replaceable class="PARAMETER">object_name</replaceable> |
  53   TEXT SEARCH PARSER <replaceable class="PARAMETER">object_name</replaceable> |
  54   TEXT SEARCH TEMPLATE <replaceable class="PARAMETER">object_name</replaceable> |
  55   TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  56   TYPE <replaceable class="PARAMETER">object_name</replaceable> |
  57   VIEW <replaceable class="PARAMETER">object_name</replaceable>
  58 } IS '<replaceable class="PARAMETER">text</replaceable>'
  59 </synopsis>
  60  </refsynopsisdiv>
  61
  62  <refsect1>
  63   <title>Description</title>
  64
  65   <para>
  66    <command>COMMENT</command> stores a comment about a database object.
  67   </para>
  68
  69   <para>
  70    Only one comment string is stored for each object, so to modify a comment,
  71    issue a new <command>COMMENT</> command for the same object.  To remove a
  72    comment, write <literal>NULL</literal> in place of the text string.
  73    Comments are automatically dropped when their object is dropped.
  74   </para>
  75
  76   <para>
  77    For most kinds of object, only the object's owner can set the comment.
  78    Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</> is
  79    that you must be superuser to comment on a superuser role, or have the
  80    <literal>CREATEROLE</> privilege to comment on non-superuser roles.
  81    Of course, a superuser can comment on anything.
  82   </para>
  83
  84   <para>
  85     Comments can be viewed using <application>psql</application>'s
  86     <command>\d</command> family of commands.
  87     Other user interfaces to retrieve comments can be built atop
  88     the same built-in functions that <application>psql</application> uses, namely
  89     <function>obj_description</>, <function>col_description</>,
  90     and <function>shobj_description</>
  91     (see <xref linkend="functions-info-comment-table">).
  92   </para>
  93  </refsect1>
  94
  95  <refsect1>
  96   <title>Parameters</title>
  97
  98   <variablelist>
  99    <varlistentry>
 100     <term><replaceable class="parameter">object_name</replaceable></term>
 101     <term><replaceable class="parameter">relation_name</replaceable>.<replaceable>column_name</replaceable></term>
 102     <term><replaceable class="parameter">agg_name</replaceable></term>
 103     <term><replaceable class="parameter">constraint_name</replaceable></term>
 104     <term><replaceable class="parameter">function_name</replaceable></term>
 105     <term><replaceable class="parameter">operator_name</replaceable></term>
 106     <term><replaceable class="parameter">rule_name</replaceable></term>
 107     <term><replaceable class="parameter">trigger_name</replaceable></term>
 108     <listitem>
 109      <para>
 110       The name of the object to be commented.  Names of tables,
 111       aggregates, collations, conversions, domains, foreign tables, functions,
 112       indexes, operators, operator classes, operator families, sequences,
 113       text search objects, types, and views can be schema-qualified.
 114       When commenting on a column,
 115       <replaceable class="parameter">relation_name</replaceable> must refer
 116       to a table, view, composite type, or foreign table.
 117      </para>
 118     </listitem>
 119    </varlistentry>
 120
 121    <varlistentry>
 122     <term><replaceable class="parameter">agg_type</replaceable></term>
 123     <listitem>
 124      <para>
 125       An input data type on which the aggregate function operates.
 126       To reference a zero-argument aggregate function, write <literal>*</>
 127       in place of the list of input data types.
 128      </para>
 129     </listitem>
 130    </varlistentry>
 131
 132    <varlistentry>
 133      <term><replaceable>source_type</replaceable></term>
 134      <listitem>
 135       <para>
 136        The name of the source data type of the cast.
 137       </para>
 138      </listitem>
 139     </varlistentry>
 140
 141     <varlistentry>
 142      <term><replaceable>target_type</replaceable></term>
 143      <listitem>
 144       <para>
 145        The name of the target data type of the cast.
 146       </para>
 147      </listitem>
 148     </varlistentry>
 149
 150    <varlistentry>
 151     <term><replaceable class="parameter">argmode</replaceable></term>
 152     <listitem>
 153      <para>
 154       The mode of a function argument: <literal>IN</>, <literal>OUT</>,
 155       <literal>INOUT</>, or <literal>VARIADIC</>.
 156       If omitted, the default is <literal>IN</>.
 157       Note that <command>COMMENT ON FUNCTION</command> does not actually pay
 158       any attention to <literal>OUT</> arguments, since only the input
 159       arguments are needed to determine the function's identity.
 160       So it is sufficient to list the <literal>IN</>, <literal>INOUT</>,
 161       and <literal>VARIADIC</> arguments.
 162      </para>
 163     </listitem>
 164    </varlistentry>
 165
 166    <varlistentry>
 167     <term><replaceable class="parameter">argname</replaceable></term>
 168     <listitem>
 169      <para>
 170       The name of a function argument.
 171       Note that <command>COMMENT ON FUNCTION</command> does not actually pay
 172       any attention to argument names, since only the argument data
 173       types are needed to determine the function's identity.
 174      </para>
 175     </listitem>
 176    </varlistentry>
 177
 178    <varlistentry>
 179     <term><replaceable class="parameter">argtype</replaceable></term>
 180     <listitem>
 181      <para>
 182       The data type(s) of the function's arguments (optionally
 183       schema-qualified), if any.
 184      </para>
 185     </listitem>
 186    </varlistentry>
 187
 188    <varlistentry>
 189     <term><replaceable class="parameter">large_object_oid</replaceable></term>
 190     <listitem>
 191      <para>
 192       The OID of the large object.
 193      </para>
 194     </listitem>
 195    </varlistentry>
 196
 197    <varlistentry>
 198     <term><replaceable class="parameter">left_type</replaceable></term>
 199     <term><replaceable class="parameter">right_type</replaceable></term>
 200     <listitem>
 201      <para>
 202       The data type(s) of the operator's arguments (optionally
 203       schema-qualified).  Write <literal>NONE</> for the missing argument
 204       of a prefix or postfix operator.
 205      </para>
 206     </listitem>
 207    </varlistentry>
 208
 209     <varlistentry>
 210      <term><literal>PROCEDURAL</literal></term>
 211      <listitem>
 212       <para>
 213        This is a noise word.
 214       </para>
 215      </listitem>
 216     </varlistentry>
 217
 218    <varlistentry>
 219     <term><replaceable class="parameter">text</replaceable></term>
 220     <listitem>
 221      <para>
 222       The new comment, written as a string literal; or <literal>NULL</>
 223       to drop the comment.
 224      </para>
 225     </listitem>
 226    </varlistentry>
 227
 228   </variablelist>
 229  </refsect1>
 230
 231  <refsect1>
 232   <title>Notes</title>
 233
 234   <para>
 235    There is presently no security mechanism for viewing comments: any user
 236    connected to a database can see all the comments for objects in
 237    that database.  For shared objects such as
 238    databases, roles, and tablespaces, comments are stored globally so any
 239    user connected to any database in the cluster can see all the comments
 240    for shared objects.  Therefore, don't put security-critical
 241    information in comments.
 242   </para>
 243  </refsect1>
 244
 245  <refsect1>
 246   <title>Examples</title>
 247
 248   <para>
 249    Attach a comment to the table <literal>mytable</literal>:
 250
 251 <programlisting>
 252 COMMENT ON TABLE mytable IS 'This is my table.';
 253 </programlisting>
 254
 255    Remove it again:
 256
 257 <programlisting>
 258 COMMENT ON TABLE mytable IS NULL;
 259 </programlisting>
 260   </para>
 261
 262   <para>
 263    Some more examples:
 264
 265 <programlisting>
 266 COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
 267 COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
 268 COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
 269 COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
 270 COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
 271 COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
 272 COMMENT ON DATABASE my_database IS 'Development Database';
 273 COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
 274 COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
 275 COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
 276 COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
 277 COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
 278 COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
 279 COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
 280 COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
 281 COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
 282 COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
 283 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
 284 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
 285 COMMENT ON ROLE my_role IS 'Administration group for finance tables';
 286 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
 287 COMMENT ON SCHEMA my_schema IS 'Departmental data';
 288 COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
 289 COMMENT ON SERVER myserver IS 'my foreign server';
 290 COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
 291 COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
 292 COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
 293 COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for swedish language';
 294 COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
 295 COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
 296 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 297 COMMENT ON TYPE complex IS 'Complex number data type';
 298 COMMENT ON VIEW my_view IS 'View of departmental costs';
 299 </programlisting></para>
 300  </refsect1>
 301
 302  <refsect1>
 303   <title>Compatibility</title>
 304
 305   <para>
 306    There is no <command>COMMENT</command> command in the SQL standard.
 307   </para>
 308  </refsect1>
 309 </refentry>