281 lines
11 KiB
Plaintext
281 lines
11 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.36 2007/08/21 21:08:47 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> |
|
|
OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
|
|
[ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
|
|
ROLE <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> |
|
|
TABLESPACE <replaceable class="PARAMETER">object_name</replaceable> |
|
|
TEXT SEARCH CONFIGURATION <replaceable class="PARAMETER">object_name</replaceable> |
|
|
TEXT SEARCH DICTIONARY <replaceable class="PARAMETER">object_name</replaceable> |
|
|
TEXT SEARCH PARSER <replaceable class="PARAMETER">object_name</replaceable> |
|
|
TEXT SEARCH TEMPLATE <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 viewed using <application>psql</application>'s
|
|
<command>\d</command> family of commands.
|
|
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,
|
|
operator families, sequences, text search objects, types, and views can
|
|
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 OPERATOR FAMILY integer_ops USING btree IS 'all 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 TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
|
|
COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for swedish language';
|
|
COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
|
|
COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
|
|
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>
|