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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.26 2005/01/04 00:39:53 tgl Exp $
   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">arg1_type</replaceable>, <replaceable class="PARAMETER">arg2_type</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   [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
  39   RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  40   SCHEMA <replaceable class="PARAMETER">object_name</replaceable> |
  41   SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> |
  42   TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  43   TYPE <replaceable class="PARAMETER">object_name</replaceable> |
  44   VIEW <replaceable class="PARAMETER">object_name</replaceable>
  45 } IS <replaceable class="PARAMETER">'text'</replaceable>
  46 </synopsis>
  47  </refsynopsisdiv>
  48
  49  <refsect1>
  50   <title>Description</title>
  51
  52   <para>
  53    <command>COMMENT</command> stores a comment about a database object.
  54   </para>
  55
  56   <para>
  57     To modify a comment, issue a new <command>COMMENT</> command for the
  58     same object.  Only one comment string is stored for each object.
  59     To remove a comment, write <literal>NULL</literal> in place of the text
  60     string.
  61     Comments are automatically dropped when the object is dropped.
  62   </para>
  63
  64   <para>
  65     Comments can be
  66     easily retrieved with the <application>psql</application> commands
  67     <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
  68     Other user interfaces to retrieve comments can be built atop
  69     the same built-in functions that <application>psql</application> uses, namely
  70     <function>obj_description</> and <function>col_description</>
  71     (see <xref linkend="functions-info-comment-table">).
  72   </para>
  73  </refsect1>
  74
  75  <refsect1>
  76   <title>Parameters</title>
  77
  78   <variablelist>
  79    <varlistentry>
  80     <term><replaceable class="parameter">object_name</replaceable></term>
  81     <term><replaceable class="parameter">table_name.column_name</replaceable></term>
  82     <term><replaceable class="parameter">agg_name</replaceable></term>
  83     <term><replaceable class="parameter">constraint_name</replaceable></term>
  84     <term><replaceable class="parameter">func_name</replaceable></term>
  85     <term><replaceable class="parameter">op</replaceable></term>
  86     <term><replaceable class="parameter">rule_name</replaceable></term>
  87     <term><replaceable class="parameter">trigger_name</replaceable></term>
  88     <listitem>
  89      <para>
  90       The name of the object to be commented.  Names of tables,
  91       aggregates, domains, functions, indexes, operators, operator classes,
  92       sequences, types, and views may be schema-qualified.
  93      </para>
  94     </listitem>
  95    </varlistentry>
  96
  97    <varlistentry>
  98     <term><replaceable class="parameter">agg_type</replaceable></term>
  99     <listitem>
 100      <para>
 101       The argument data type of the aggregate function, or
 102       <literal>*</literal> if the function accepts any data type.
 103      </para>
 104     </listitem>
 105    </varlistentry>
 106
 107    <varlistentry>
 108     <term><replaceable class="parameter">large_object_oid</replaceable></term>
 109     <listitem>
 110      <para>
 111       The OID of the large object.
 112      </para>
 113     </listitem>
 114    </varlistentry>
 115
 116     <varlistentry>
 117      <term><literal>PROCEDURAL</literal></term>
 118
 119      <listitem>
 120       <para>
 121        This is a noise word.
 122       </para>
 123      </listitem>
 124     </varlistentry>
 125
 126    <varlistentry>
 127      <term><replaceable>sourcetype</replaceable></term>
 128      <listitem>
 129       <para>
 130        The name of the source data type of the cast.
 131       </para>
 132      </listitem>
 133     </varlistentry>
 134
 135     <varlistentry>
 136      <term><replaceable>targettype</replaceable></term>
 137      <listitem>
 138       <para>
 139        The name of the target data type of the cast.
 140       </para>
 141      </listitem>
 142     </varlistentry>
 143
 144    <varlistentry>
 145     <term><replaceable class="parameter">text</replaceable></term>
 146     <listitem>
 147      <para>
 148       The new comment, written as a string literal; or <literal>NULL</>
 149       to drop the comment.
 150      </para>
 151     </listitem>
 152    </varlistentry>
 153
 154   </variablelist>
 155  </refsect1>
 156
 157  <refsect1>
 158   <title>Notes</title>
 159
 160   <para>
 161    A comment for a database can only be created in that database,
 162    and will only be visible in that database, not in other databases.
 163   </para>
 164
 165   <para>
 166    There is presently no security mechanism for comments: any user
 167    connected to a database can see all the comments for objects in
 168    that database (although only superusers can change comments for
 169    objects that they don't own).  Therefore, don't put
 170    security-critical information in comments.
 171   </para>
 172  </refsect1>
 173
 174  <refsect1>
 175   <title>Examples</title>
 176
 177   <para>
 178    Attach a comment to the table <literal>mytable</literal>:
 179
 180 <programlisting>
 181 COMMENT ON TABLE mytable IS 'This is my table.';
 182 </programlisting>
 183
 184    Remove it again:
 185
 186 <programlisting>
 187 COMMENT ON TABLE mytable IS NULL;
 188 </programlisting>
 189   </para>
 190
 191   <para>
 192    Some more examples:
 193
 194 <programlisting>
 195 COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
 196 COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
 197 COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
 198 COMMENT ON CONVERSION my_conv IS 'Conversion to Unicode';
 199 COMMENT ON DATABASE my_database IS 'Development Database';
 200 COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
 201 COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
 202 COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
 203 COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
 204 COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
 205 COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
 206 COMMENT ON OPERATOR ^ (NONE, text) IS 'This is a prefix operator on text';
 207 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
 208 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
 209 COMMENT ON SCHEMA my_schema IS 'Departmental data';
 210 COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
 211 COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
 212 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 213 COMMENT ON TYPE complex IS 'Complex number data type';
 214 COMMENT ON VIEW my_view IS 'View of departmental costs';
 215 </programlisting>
 216   </para>
 217  </refsect1>
 218
 219  <refsect1>
 220   <title>Compatibility</title>
 221
 222   <para>
 223    There is no <command>COMMENT</command> command in the SQL standard.
 224   </para>
 225  </refsect1>
 226 </refentry>
 227
 228 <!-- Keep this comment at the end of the file
 229 Local variables:
 230 mode: sgml
 231 sgml-omittag:t
 232 sgml-shorttag:t
 233 sgml-minimize-attributes:nil
 234 sgml-always-quote-attributes:t
 235 sgml-indent-step:1
 236 sgml-indent-data:t
 237 sgml-parent-document:nil
 238 sgml-default-dtd-file:"../reference.ced"
 239 sgml-exposed-tags:nil
 240 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 241 sgml-local-ecat-files:nil
 242 End:
 243 -->