mirror of https://github.com/postgres/postgres
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
303 lines
12 KiB
303 lines
12 KiB
<!--
|
|
doc/src/sgml/ref/comment.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="SQL-COMMENT">
|
|
<refmeta>
|
|
<refentrytitle>COMMENT</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<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>source_type</replaceable> AS <replaceable>target_type</replaceable>) |
|
|
COLLATION <replaceable class="PARAMETER">object_name</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> |
|
|
EXTENSION <replaceable class="PARAMETER">object_name</replaceable> |
|
|
FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> |
|
|
FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> |
|
|
FUNCTION <replaceable class="PARAMETER">function_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">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_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> |
|
|
SERVER <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>
|
|
Only one comment string is stored for each object, so to modify a comment,
|
|
issue a new <command>COMMENT</> command for the same object. To remove a
|
|
comment, write <literal>NULL</literal> in place of the text string.
|
|
Comments are automatically dropped when their object is dropped.
|
|
</para>
|
|
|
|
<para>
|
|
For most kinds of object, only the object's owner can set the comment.
|
|
Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</> is
|
|
that you must be superuser to comment on a superuser role, or have the
|
|
<literal>CREATEROLE</> privilege to comment on non-superuser roles.
|
|
Of course, a superuser can comment on anything.
|
|
</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">function_name</replaceable></term>
|
|
<term><replaceable class="parameter">operator_name</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, collations, conversions, domains, foreign tables, 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>source_type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the source data type of the cast.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>target_type</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: <literal>IN</>, <literal>OUT</>,
|
|
<literal>INOUT</>, or <literal>VARIADIC</>.
|
|
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</>, <literal>INOUT</>,
|
|
and <literal>VARIADIC</> 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><replaceable class="parameter">left_type</replaceable></term>
|
|
<term><replaceable class="parameter">right_type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The data type(s) of the operator's arguments (optionally
|
|
schema-qualified). Write <literal>NONE</> for the missing argument
|
|
of a prefix or postfix operator.
|
|
</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 viewing comments: any user
|
|
connected to a database can see all the comments for objects in
|
|
that database. For shared objects such as
|
|
databases, roles, and tablespaces, comments are stored globally so any
|
|
user connected to any database in the cluster 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 COLLATION "fr_CA" IS 'Canadian French';
|
|
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 FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
|
|
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, integer) IS 'Unary minus';
|
|
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>
|
|
|