comment.sgml 4.84 KB
Newer Older
1
<!--
2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.10 2001/10/03 20:54:20 tgl Exp $
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
Postgres documentation
-->

<refentry id="SQL-COMMENT">
 <refmeta>
  <refentrytitle id="SQL-COMMENT-TITLE">
   COMMENT
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   COMMENT
  </refname>
  <refpurpose>
18
   define or change the comment of an object
19 20 21 22 23 24 25 26 27
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
COMMENT ON
[
28 29 30 31
  [ DATABASE | INDEX | RULE | SEQUENCE | TABLE | TYPE | VIEW ] <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>) |
  FUNCTION <replaceable class="PARAMETER">func_name</replaceable> (<replaceable class="PARAMETER">arg1</replaceable>, <replaceable class="PARAMETER">arg2</replaceable>, ...) |
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
  OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable> <replaceable class="PARAMETER">rightoperand_type</replaceable>) |
  TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable>
] IS <replaceable class="PARAMETER">'text'</replaceable>
  </synopsis>
  
  <refsect2 id="R2-SQL-COMMENT-1">
   <refsect2info>
    <date>1999-10-25</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">object_name, table_name,
      column_name, agg_name, func_name, op, trigger_name</replaceable></term>
      <listitem>
       <para>
	The name of the object to be be commented.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">text</replaceable></term>
      <listitem>
       <para>
	The comment to add.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
  
  <refsect2 id="R2-SQL-COMMENT-2">
   <refsect2info>
    <date>1998-09-08</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
COMMENT
       </computeroutput></term>
      <listitem>
       <para>
	Message returned if the table is successfully commented.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-COMMENT-1">
  <refsect1info>
   <date>1998-10-25</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>COMMENT</command> adds a comment to an object that can be 
102 103
    easily retrieved with <command>psql</command>'s
    <command>\dd</command>, <command>\d+</command>, or <command>\l+</command> commands.
104
    To remove a comment, write <literal>NULL</literal>.
Bruce Momjian's avatar
Bruce Momjian committed
105
    Comments are automatically dropped when the object is dropped.
106 107 108 109 110 111 112 113
  </para>
 </refsect1>

 <refsect1 id="R1-SQL-COMMENT-2">
  <title>
   Usage
  </title>
  <para>
Bruce Momjian's avatar
Bruce Momjian committed
114
   Comment the table <literal>mytable</literal>:
115 116 117 118 119

   <programlisting>
COMMENT ON mytable IS 'This is my table.';
   </programlisting>
  </para>
Bruce Momjian's avatar
Bruce Momjian committed
120 121 122 123 124 125 126 127 128 129 130 131 132

  <para>
   Some more examples:

   <programlisting>
COMMENT ON DATABASE my_database IS 'Development Database';
COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee id';
COMMENT ON RULE my_rule IS 'Logs UPDATES of employee records';
COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
COMMENT ON TABLE my_table IS 'Employee Information';
COMMENT ON TYPE my_type IS 'Complex Number support';
COMMENT ON VIEW my_view IS 'View of departmental costs';
COMMENT ON COLUMN my_table.my_field IS 'Employee ID number';
133 134
COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
Bruce Momjian's avatar
Bruce Momjian committed
135 136 137 138
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two text';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for R.I.';
   </programlisting>
  </para>
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
 </refsect1>
 
 <refsect1 id="R1-SQL-COMMENT-3">
  <title>
   Compatibility
  </title>
  
  <refsect2 id="R2-SQL-COMMENT-4">
   <refsect2info>
    <date>1998-09-08</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>COMMENT</command> in <acronym>SQL92</acronym>.
   </para>
  </refsect2>
 </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:
-->