| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.33 2006/10/23 18:10:32 petere 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 object_name | |
| COLUMN table_name.column_name | |
| AGGREGATE agg_name (agg_type [, ...]) | |
| CAST (sourcetype AS targettype) | |
| CONSTRAINT constraint_name ON table_name | |
| CONVERSION object_name | |
| DATABASE object_name | |
| DOMAIN object_name | |
| FILESPACE object_name | |
| FUNCTION func_name ([[argmode] [argname] argtype [, ...]]) | |
| INDEX object_name | |
| LARGE OBJECT large_object_oid | |
| OPERATOR op (leftoperand_type, rightoperand_type) | |
| OPERATOR CLASS object_name USING index_method | |
| [PROCEDURAL] LANGUAGE object_name | |
| RESOURCE QUEUE object_name | |
| ROLE object_name | |
| RULE rule_name ON table_name | |
| SCHEMA object_name | |
| SEQUENCE object_name | |
| TABLESPACE object_name | |
| TRIGGER trigger_name ON table_name | |
| TYPE object_name | |
| VIEW object_name } |
| IS 'text' |
| |
| |
| </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</>, <function>col_description</>, |
| and <function>shobj_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> |
| An input data type on which the aggregate function operates. |
| To reference a zero-argument aggregate function, write <literal>*</> |
| in place of the list of input data types. |
| </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> |
| 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). For shared objects such as |
| databases, roles, and tablespaces comments are stored globally |
| and any user connected to any database can see all the comments |
| for shared objects. 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 ROLE my_role IS 'Administration group for finance tables'; |
| 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 TABLESPACE my_tablespace IS 'Tablespace for indexes'; |
| 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> |