begriffs open source - ai-pg/blob - full-docs/html/sql-comment.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>COMMENT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-cluster.html" title="CLUSTER" /><link rel="next" href="sql-commit.html" title="COMMIT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">COMMENT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-cluster.html" title="CLUSTER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-commit.html" title="COMMIT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-COMMENT"><div class="titlepage"></div><a id="id-1.9.3.52.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">COMMENT</span></h2><p>COMMENT — define or change the comment of an object</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 COMMENT ON
   4 {
   5   ACCESS METHOD <em class="replaceable"><code>object_name</code></em> |
   6   AGGREGATE <em class="replaceable"><code>aggregate_name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) |
   7   CAST (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>) |
   8   COLLATION <em class="replaceable"><code>object_name</code></em> |
   9   COLUMN <em class="replaceable"><code>relation_name</code></em>.<em class="replaceable"><code>column_name</code></em> |
  10   CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
  11   CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ON DOMAIN <em class="replaceable"><code>domain_name</code></em> |
  12   CONVERSION <em class="replaceable"><code>object_name</code></em> |
  13   DATABASE <em class="replaceable"><code>object_name</code></em> |
  14   DOMAIN <em class="replaceable"><code>object_name</code></em> |
  15   EXTENSION <em class="replaceable"><code>object_name</code></em> |
  16   EVENT TRIGGER <em class="replaceable"><code>object_name</code></em> |
  17   FOREIGN DATA WRAPPER <em class="replaceable"><code>object_name</code></em> |
  18   FOREIGN TABLE <em class="replaceable"><code>object_name</code></em> |
  19   FUNCTION <em class="replaceable"><code>function_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
  20   INDEX <em class="replaceable"><code>object_name</code></em> |
  21   LARGE OBJECT <em class="replaceable"><code>large_object_oid</code></em> |
  22   MATERIALIZED VIEW <em class="replaceable"><code>object_name</code></em> |
  23   OPERATOR <em class="replaceable"><code>operator_name</code></em> (<em class="replaceable"><code>left_type</code></em>, <em class="replaceable"><code>right_type</code></em>) |
  24   OPERATOR CLASS <em class="replaceable"><code>object_name</code></em> USING <em class="replaceable"><code>index_method</code></em> |
  25   OPERATOR FAMILY <em class="replaceable"><code>object_name</code></em> USING <em class="replaceable"><code>index_method</code></em> |
  26   POLICY <em class="replaceable"><code>policy_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
  27   [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>object_name</code></em> |
  28   PROCEDURE <em class="replaceable"><code>procedure_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
  29   PUBLICATION <em class="replaceable"><code>object_name</code></em> |
  30   ROLE <em class="replaceable"><code>object_name</code></em> |
  31   ROUTINE <em class="replaceable"><code>routine_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
  32   RULE <em class="replaceable"><code>rule_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
  33   SCHEMA <em class="replaceable"><code>object_name</code></em> |
  34   SEQUENCE <em class="replaceable"><code>object_name</code></em> |
  35   SERVER <em class="replaceable"><code>object_name</code></em> |
  36   STATISTICS <em class="replaceable"><code>object_name</code></em> |
  37   SUBSCRIPTION <em class="replaceable"><code>object_name</code></em> |
  38   TABLE <em class="replaceable"><code>object_name</code></em> |
  39   TABLESPACE <em class="replaceable"><code>object_name</code></em> |
  40   TEXT SEARCH CONFIGURATION <em class="replaceable"><code>object_name</code></em> |
  41   TEXT SEARCH DICTIONARY <em class="replaceable"><code>object_name</code></em> |
  42   TEXT SEARCH PARSER <em class="replaceable"><code>object_name</code></em> |
  43   TEXT SEARCH TEMPLATE <em class="replaceable"><code>object_name</code></em> |
  44   TRANSFORM FOR <em class="replaceable"><code>type_name</code></em> LANGUAGE <em class="replaceable"><code>lang_name</code></em> |
  45   TRIGGER <em class="replaceable"><code>trigger_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
  46   TYPE <em class="replaceable"><code>object_name</code></em> |
  47   VIEW <em class="replaceable"><code>object_name</code></em>
  48 } IS { <em class="replaceable"><code>string_literal</code></em> | NULL }
  49
  50 <span class="phrase">where <em class="replaceable"><code>aggregate_signature</code></em> is:</span>
  51
  52 * |
  53 [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] |
  54 [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] ] ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ]
  55 </pre></div><div class="refsect1" id="id-1.9.3.52.5"><h2>Description</h2><p>
  56    <code class="command">COMMENT</code> stores a comment about a database object.
  57   </p><p>
  58    Only one comment string is stored for each object, so to modify a comment,
  59    issue a new <code class="command">COMMENT</code> command for the same object.  To remove a
  60    comment, write <code class="literal">NULL</code> in place of the text string.
  61    Comments are automatically dropped when their object is dropped.
  62   </p><p>
  63    A <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock is acquired on the
  64    object to be commented.
  65   </p><p>
  66    For most kinds of object, only the object's owner can set the comment.
  67    Roles don't have owners, so the rule for <code class="literal">COMMENT ON ROLE</code> is
  68    that you must be superuser to comment on a superuser role, or have the
  69    <code class="literal">CREATEROLE</code> privilege and have been granted
  70    <code class="literal">ADMIN OPTION</code> on the target role.
  71    Likewise, access methods don't have owners either; you must be superuser
  72    to comment on an access method.
  73    Of course, a superuser can comment on anything.
  74   </p><p>
  75     Comments can be viewed using <span class="application">psql</span>'s
  76     <code class="command">\d</code> family of commands.
  77     Other user interfaces to retrieve comments can be built atop
  78     the same built-in functions that <span class="application">psql</span> uses, namely
  79     <code class="function">obj_description</code>, <code class="function">col_description</code>,
  80     and <code class="function">shobj_description</code>
  81     (see <a class="xref" href="functions-info.html#FUNCTIONS-INFO-COMMENT-TABLE" title="Table 9.82. Comment Information Functions">Table 9.82</a>).
  82   </p></div><div class="refsect1" id="id-1.9.3.52.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>object_name</code></em><br /></span><span class="term"><em class="replaceable"><code>relation_name</code></em>.<em class="replaceable"><code>column_name</code></em><br /></span><span class="term"><em class="replaceable"><code>aggregate_name</code></em><br /></span><span class="term"><em class="replaceable"><code>constraint_name</code></em><br /></span><span class="term"><em class="replaceable"><code>function_name</code></em><br /></span><span class="term"><em class="replaceable"><code>operator_name</code></em><br /></span><span class="term"><em class="replaceable"><code>policy_name</code></em><br /></span><span class="term"><em class="replaceable"><code>procedure_name</code></em><br /></span><span class="term"><em class="replaceable"><code>routine_name</code></em><br /></span><span class="term"><em class="replaceable"><code>rule_name</code></em><br /></span><span class="term"><em class="replaceable"><code>trigger_name</code></em></span></dt><dd><p>
  83       The name of the object to be commented.  Names of objects that reside in
  84       schemas (tables, functions, etc.) can be
  85       schema-qualified. When commenting on a column,
  86       <em class="replaceable"><code>relation_name</code></em> must refer
  87       to a table, view, composite type, or foreign table.
  88      </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em><br /></span><span class="term"><em class="replaceable"><code>domain_name</code></em></span></dt><dd><p>
  89       When creating a comment on a constraint, a trigger, a rule or
  90       a policy these parameters specify the name of the table or domain on
  91       which that object is defined.
  92      </p></dd><dt><span class="term"><em class="replaceable"><code>source_type</code></em></span></dt><dd><p>
  93        The name of the source data type of the cast.
  94       </p></dd><dt><span class="term"><em class="replaceable"><code>target_type</code></em></span></dt><dd><p>
  95        The name of the target data type of the cast.
  96       </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
  97       The mode of a function, procedure, or aggregate
  98       argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
  99       <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
 100       If omitted, the default is <code class="literal">IN</code>.
 101       Note that <code class="command">COMMENT</code> does not actually pay
 102       any attention to <code class="literal">OUT</code> arguments, since only the input
 103       arguments are needed to determine the function's identity.
 104       So it is sufficient to list the <code class="literal">IN</code>, <code class="literal">INOUT</code>,
 105       and <code class="literal">VARIADIC</code> arguments.
 106      </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
 107       The name of a function, procedure, or aggregate argument.
 108       Note that <code class="command">COMMENT</code> does not actually pay
 109       any attention to argument names, since only the argument data
 110       types are needed to determine the function's identity.
 111      </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
 112       The data type of a function, procedure, or aggregate argument.
 113      </p></dd><dt><span class="term"><em class="replaceable"><code>large_object_oid</code></em></span></dt><dd><p>
 114       The OID of the large object.
 115      </p></dd><dt><span class="term"><em class="replaceable"><code>left_type</code></em><br /></span><span class="term"><em class="replaceable"><code>right_type</code></em></span></dt><dd><p>
 116       The data type(s) of the operator's arguments (optionally
 117       schema-qualified).  Write <code class="literal">NONE</code> for the missing argument
 118       of a prefix operator.
 119      </p></dd><dt><span class="term"><code class="literal">PROCEDURAL</code></span></dt><dd><p>
 120        This is a noise word.
 121       </p></dd><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
 122        The name of the data type of the transform.
 123       </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
 124        The name of the language of the transform.
 125       </p></dd><dt><span class="term"><em class="replaceable"><code>string_literal</code></em></span></dt><dd><p>
 126       The new comment contents, written as a string literal.
 127      </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
 128       Write <code class="literal">NULL</code> to drop the comment.
 129      </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.52.7"><h2>Notes</h2><p>
 130    There is presently no security mechanism for viewing comments: any user
 131    connected to a database can see all the comments for objects in
 132    that database.  For shared objects such as
 133    databases, roles, and tablespaces, comments are stored globally so any
 134    user connected to any database in the cluster can see all the comments
 135    for shared objects.  Therefore, don't put security-critical
 136    information in comments.
 137   </p></div><div class="refsect1" id="id-1.9.3.52.8"><h2>Examples</h2><p>
 138    Attach a comment to the table <code class="literal">mytable</code>:
 139
 140 </p><pre class="programlisting">
 141 COMMENT ON TABLE mytable IS 'This is my table.';
 142 </pre><p>
 143
 144    Remove it again:
 145
 146 </p><pre class="programlisting">
 147 COMMENT ON TABLE mytable IS NULL;
 148 </pre><p>
 149   </p><p>
 150    Some more examples:
 151
 152 </p><pre class="programlisting">
 153 COMMENT ON ACCESS METHOD gin IS 'GIN index access method';
 154 COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
 155 COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
 156 COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
 157 COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
 158 COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
 159 COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
 160 COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain';
 161 COMMENT ON DATABASE my_database IS 'Development Database';
 162 COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
 163 COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';
 164 COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
 165 COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
 166 COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
 167 COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
 168 COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
 169 COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
 170 COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
 171 COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';
 172 COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
 173 COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
 174 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
 175 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
 176 COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
 177 COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';
 178 COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';
 179 COMMENT ON ROLE my_role IS 'Administration group for finance tables';
 180 COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a function or procedure)';
 181 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
 182 COMMENT ON SCHEMA my_schema IS 'Departmental data';
 183 COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
 184 COMMENT ON SERVER myserver IS 'my foreign server';
 185 COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';
 186 COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tables';
 187 COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
 188 COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
 189 COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
 190 COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish language';
 191 COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
 192 COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
 193 COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore and Python dict';
 194 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 195 COMMENT ON TYPE complex IS 'Complex number data type';
 196 COMMENT ON VIEW my_view IS 'View of departmental costs';
 197 </pre></div><div class="refsect1" id="id-1.9.3.52.9"><h2>Compatibility</h2><p>
 198    There is no <code class="command">COMMENT</code> command in the SQL standard.
 199   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-cluster.html" title="CLUSTER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-commit.html" title="COMMIT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CLUSTER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COMMIT</td></tr></table></div></body></html>