path: root/doc/src/sgml/ref/comment.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.29 2005/06/08 21:15:27 tgl Exp $
PostgreSQL documentation
-->

<refentry id="SQL-COMMENT">
 <refmeta>
  <refentrytitle id="SQL-COMMENT-TITLE">COMMENT</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>COMMENT</refname>
  <refpurpose>define or change the comment of an object</refpurpose>
 </refnamediv>

 <indexterm zone="sql-comment">
  <primary>COMMENT</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
COMMENT ON
{
  TABLE <replaceable class="PARAMETER">object_name</replaceable> |
  COLUMN <replaceable class="PARAMETER">table_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable> |
  AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable>) |
  CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>) |
  CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
  DATABASE <replaceable class="PARAMETER">object_name</replaceable> |
  DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
  FUNCTION <replaceable class="PARAMETER">func_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
  INDEX <replaceable class="PARAMETER">object_name</replaceable> |
  LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> |
  OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable>, <replaceable class="PARAMETER">rightoperand_type</replaceable>) |
  OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
  [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
  RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  SCHEMA <replaceable class="PARAMETER">object_name</replaceable> |
  SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> |
  TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
  TYPE <replaceable class="PARAMETER">object_name</replaceable> |
  VIEW <replaceable class="PARAMETER">object_name</replaceable>
} IS <replaceable class="PARAMETER">'text'</replaceable>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>COMMENT</command> stores a comment about a database object.
  </para>

  <para>
    To modify a comment, issue a new <command>COMMENT</> command for the
    same object.  Only one comment string is stored for each object.
    To remove a comment, write <literal>NULL</literal> in place of the text
    string.
    Comments are automatically dropped when the object is dropped.
  </para>

  <para>
    Comments can be
    easily retrieved with the <application>psql</application> commands
    <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
    Other user interfaces to retrieve comments can be built atop
    the same built-in functions that <application>psql</application> uses, namely
    <function>obj_description</> and <function>col_description</>
    (see <xref linkend="functions-info-comment-table">).
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="parameter">object_name</replaceable></term>
    <term><replaceable class="parameter">table_name.column_name</replaceable></term>
    <term><replaceable class="parameter">agg_name</replaceable></term>
    <term><replaceable class="parameter">constraint_name</replaceable></term>
    <term><replaceable class="parameter">func_name</replaceable></term>
    <term><replaceable class="parameter">op</replaceable></term>
    <term><replaceable class="parameter">rule_name</replaceable></term>
    <term><replaceable class="parameter">trigger_name</replaceable></term>
    <listitem>
     <para>
      The name of the object to be commented.  Names of tables,
      aggregates, domains, functions, indexes, operators, operator classes,
      sequences, types, and views may be schema-qualified.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">agg_type</replaceable></term>
    <listitem>
     <para>
      The argument data type of the aggregate function, or
      <literal>*</literal> if the function accepts any data type.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry>
     <term><replaceable>sourcetype</replaceable></term>
     <listitem>
      <para>
       The name of the source data type of the cast.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>targettype</replaceable></term>
     <listitem>
      <para>
       The name of the target data type of the cast.
      </para>
     </listitem>
    </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">argmode</replaceable></term>

    <listitem>
     <para>
      The mode of a function argument: either <literal>IN</>, <literal>OUT</>,
      or <literal>INOUT</>.  If omitted, the default is <literal>IN</>.
      Note that <command>COMMENT ON FUNCTION</command> does not actually pay
      any attention to <literal>OUT</> arguments, since only the input
      arguments are needed to determine the function's identity.
      So it is sufficient to list the <literal>IN</> and <literal>INOUT</>
      arguments.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">argname</replaceable></term>

    <listitem>
     <para>
      The name of a function argument.
      Note that <command>COMMENT ON FUNCTION</command> does not actually pay
      any attention to argument names, since only the argument data
      types are needed to determine the function's identity.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">argtype</replaceable></term>

    <listitem>
     <para>
      The data type(s) of the function's arguments (optionally 
      schema-qualified), if any.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">large_object_oid</replaceable></term>
    <listitem>
     <para>
      The OID of the large object.
     </para>
    </listitem>
   </varlistentry>

    <varlistentry>
     <term><literal>PROCEDURAL</literal></term>

     <listitem>
      <para>
       This is a noise word.
      </para>
     </listitem>
    </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">text</replaceable></term>
    <listitem>
     <para>
      The new comment, written as a string literal; or <literal>NULL</>
      to drop the comment.
     </para>
    </listitem>
   </varlistentry>
    
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   A comment for a database can only be created in that database,
   and will only be visible in that database, not in other databases.
  </para>

  <para>
   There is presently no security mechanism for comments: any user
   connected to a database can see all the comments for objects in
   that database (although only superusers can change comments for
   objects that they don't own).  Therefore, don't put
   security-critical information in comments.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   Attach a comment to the table <literal>mytable</literal>:

<programlisting>
COMMENT ON TABLE mytable IS 'This is my table.';
</programlisting>

   Remove it again:

<programlisting>
COMMENT ON TABLE mytable IS NULL;
</programlisting>
  </para>

  <para>
   Some more examples:

<programlisting>
COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
COMMENT ON DATABASE my_database IS 'Development Database';
COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR - (NONE, text) IS 'This is a prefix operator on text';
COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
COMMENT ON SCHEMA my_schema IS 'Departmental data';
COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
COMMENT ON TYPE complex IS 'Complex number data type';
COMMENT ON VIEW my_view IS 'View of departmental costs';
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   There is no <command>COMMENT</command> command in the SQL standard.
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->