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