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

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