comment.sgml

PostgreSQL7.4.6 for Linux

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.23 2003/09/09 18:28:52 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>) |
  CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ON <replaceable class="PARAMETER">table_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">arg1_type</replaceable>, <replaceable class="PARAMETER">arg2_type</replaceable>, ...) |
  INDEX <replaceable class="PARAMETER">object_name</replaceable> |
  OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable>, <replaceable class="PARAMETER">rightoperand_type</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.
    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</>.
  </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>
 </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">aggname</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 be commented.  Names of tables,
      aggregates, domains, functions, indexes, operators, sequences,
      types, and views may be schema-qualified.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">text</replaceable></term>
    <listitem>
     <para>
      The new comment.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <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 COLUMN my_table.my_column IS 'Employee ID number';
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 OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR ^ (NONE, text) IS 'This is a prefix operator on text';
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:
-->