comment.sgml 5.68 KB
Newer Older
1
<!--
Bruce Momjian's avatar
Bruce Momjian committed
2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.13 2002/03/06 20:34:44 momjian Exp $
3
PostgreSQL documentation
4 5 6 7 8 9 10 11 12 13 14 15 16 17
-->

<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
[
Bruce Momjian's avatar
Bruce Momjian committed
28
  [ DATABASE | DOMAIN | INDEX | RULE | SEQUENCE | TABLE | TYPE | VIEW ] <replaceable class="PARAMETER">object_name</replaceable> |
29 30 31
  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
  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>
Bruce Momjian's avatar
Bruce Momjian committed
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
  <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>
Bruce Momjian's avatar
Bruce Momjian committed
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
  <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>
101
   <command>COMMENT</command> stores a comment about a database object.
Bruce Momjian's avatar
Bruce Momjian committed
102
    Comments can be
103
    easily retrieved with <command>psql</command>'s
104 105 106 107 108 109 110 111 112 113 114
    <command>\dd</command>, <command>\d+</command>, or <command>\l+</command>
    commands.  Other user interfaces to retrieve comments can be built atop
    the same built-in functions that <command>psql</command> 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.
Bruce Momjian's avatar
Bruce Momjian committed
115
    Comments are automatically dropped when the object is dropped.
116
  </para>
117 118 119 120 121 122 123 124

  <para>
    It should be noted that 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>
125 126 127 128 129 130 131
 </refsect1>

 <refsect1 id="R1-SQL-COMMENT-2">
  <title>
   Usage
  </title>
  <para>
Bruce Momjian's avatar
Bruce Momjian committed
132
   Comment the table <literal>mytable</literal>:
133 134 135 136 137

   <programlisting>
COMMENT ON mytable IS 'This is my table.';
   </programlisting>
  </para>
Bruce Momjian's avatar
Bruce Momjian committed
138 139 140 141 142 143

  <para>
   Some more examples:

   <programlisting>
COMMENT ON DATABASE my_database IS 'Development Database';
Bruce Momjian's avatar
Bruce Momjian committed
144
COMMENT ON DOMAIN my_domain IS 'Domains are like abstracted fields';
Bruce Momjian's avatar
Bruce Momjian committed
145 146 147 148 149 150 151
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';
152 153
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
154 155 156 157
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>
158
 </refsect1>
Bruce Momjian's avatar
Bruce Momjian committed
159

160 161 162 163
 <refsect1 id="R1-SQL-COMMENT-3">
  <title>
   Compatibility
  </title>
Bruce Momjian's avatar
Bruce Momjian committed
164

165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
  <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:
-->