doc/src/sgml/ref/comment.sgml

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