Debian Codegraph @

doc/src/sgml/ref/comment.sgml

raw
1 <!--
2 doc/src/sgml/ref/comment.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-comment">
7 <indexterm zone="sql-comment">
8 <primary>COMMENT</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle>COMMENT</refentrytitle>
13 <manvolnum>7</manvolnum>
14 <refmiscinfo>SQL - Language Statements</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>COMMENT</refname>
19 <refpurpose>define or change the comment of an object</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <synopsis>
24 COMMENT ON
25 {
26 ACCESS METHOD <replaceable class="parameter">object_name</replaceable> |
27 AGGREGATE <replaceable class="parameter">aggregate_name</replaceable> ( <replaceable>aggregate_signature</replaceable> ) |
28 CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) |
29 COLLATION <replaceable class="parameter">object_name</replaceable> |
30 COLUMN <replaceable class="parameter">relation_name</replaceable>.<replaceable class="parameter">column_name</replaceable> |
31 CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
32 CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ON DOMAIN <replaceable class="parameter">domain_name</replaceable> |
33 CONVERSION <replaceable class="parameter">object_name</replaceable> |
34 DATABASE <replaceable class="parameter">object_name</replaceable> |
35 DOMAIN <replaceable class="parameter">object_name</replaceable> |
36 EXTENSION <replaceable class="parameter">object_name</replaceable> |
37 EVENT TRIGGER <replaceable class="parameter">object_name</replaceable> |
38 FOREIGN DATA WRAPPER <replaceable class="parameter">object_name</replaceable> |
39 FOREIGN TABLE <replaceable class="parameter">object_name</replaceable> |
40 FUNCTION <replaceable class="parameter">function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
41 INDEX <replaceable class="parameter">object_name</replaceable> |
42 LARGE OBJECT <replaceable class="parameter">large_object_oid</replaceable> |
43 MATERIALIZED VIEW <replaceable class="parameter">object_name</replaceable> |
44 OPERATOR <replaceable class="parameter">operator_name</replaceable> (<replaceable class="parameter">left_type</replaceable>, <replaceable class="parameter">right_type</replaceable>) |
45 OPERATOR CLASS <replaceable class="parameter">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
46 OPERATOR FAMILY <replaceable class="parameter">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
47 POLICY <replaceable class="parameter">policy_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
48 [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">object_name</replaceable> |
49 PROCEDURE <replaceable class="parameter">procedure_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
50 PUBLICATION <replaceable class="parameter">object_name</replaceable> |
51 ROLE <replaceable class="parameter">object_name</replaceable> |
52 ROUTINE <replaceable class="parameter">routine_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
53 RULE <replaceable class="parameter">rule_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
54 SCHEMA <replaceable class="parameter">object_name</replaceable> |
55 SEQUENCE <replaceable class="parameter">object_name</replaceable> |
56 SERVER <replaceable class="parameter">object_name</replaceable> |
57 STATISTICS <replaceable class="parameter">object_name</replaceable> |
58 SUBSCRIPTION <replaceable class="parameter">object_name</replaceable> |
59 TABLE <replaceable class="parameter">object_name</replaceable> |
60 TABLESPACE <replaceable class="parameter">object_name</replaceable> |
61 TEXT SEARCH CONFIGURATION <replaceable class="parameter">object_name</replaceable> |
62 TEXT SEARCH DICTIONARY <replaceable class="parameter">object_name</replaceable> |
63 TEXT SEARCH PARSER <replaceable class="parameter">object_name</replaceable> |
64 TEXT SEARCH TEMPLATE <replaceable class="parameter">object_name</replaceable> |
65 TRANSFORM FOR <replaceable>type_name</replaceable> LANGUAGE <replaceable>lang_name</replaceable> |
66 TRIGGER <replaceable class="parameter">trigger_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
67 TYPE <replaceable class="parameter">object_name</replaceable> |
68 VIEW <replaceable class="parameter">object_name</replaceable>
69 } IS { <replaceable class="parameter">string_literal</replaceable> | NULL }
70
71 <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
72
73 * |
74 [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ] |
75 [ [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ] ] ORDER BY [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ]
76 </synopsis>
77 </refsynopsisdiv>
78
79 <refsect1>
80 <title>Description</title>
81
82 <para>
83 <command>COMMENT</command> stores, replaces, or removes the comment on a
84 database object.
85 </para>
86
87 <para>
88 Only one comment string is stored for each object. Issuing a new
89 <command>COMMENT</command> command for the same object replaces the
90 existing comment. Specifying <literal>NULL</literal> or an empty
91 string (<literal>''</literal>) removes the comment. Comments are
92 automatically dropped when their object is dropped.
93 </para>
94
95 <para>
96 A <literal>SHARE UPDATE EXCLUSIVE</literal> lock is acquired on the
97 object to be commented.
98 </para>
99
100 <para>
101 For most kinds of object, only the object's owner can set the comment.
102 Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</literal> is
103 that you must be superuser to comment on a superuser role, or have the
104 <literal>CREATEROLE</literal> privilege and have been granted
105 <literal>ADMIN OPTION</literal> on the target role.
106 Likewise, access methods don't have owners either; you must be superuser
107 to comment on an access method.
108 Of course, a superuser can comment on anything.
109 </para>
110
111 <para>
112 Comments can be viewed using <application>psql</application>'s
113 <command>\d</command> family of commands.
114 Other user interfaces to retrieve comments can be built atop
115 the same built-in functions that <application>psql</application> uses, namely
116 <function>obj_description</function>, <function>col_description</function>,
117 and <function>shobj_description</function>
118 (see <xref linkend="functions-info-comment-table"/>).
119 </para>
120 </refsect1>
121
122 <refsect1>
123 <title>Parameters</title>
124
125 <variablelist>
126 <varlistentry>
127 <term><replaceable class="parameter">object_name</replaceable></term>
128 <term><replaceable class="parameter">relation_name</replaceable>.<replaceable>column_name</replaceable></term>
129 <term><replaceable class="parameter">aggregate_name</replaceable></term>
130 <term><replaceable class="parameter">constraint_name</replaceable></term>
131 <term><replaceable class="parameter">function_name</replaceable></term>
132 <term><replaceable class="parameter">operator_name</replaceable></term>
133 <term><replaceable class="parameter">policy_name</replaceable></term>
134 <term><replaceable class="parameter">procedure_name</replaceable></term>
135 <term><replaceable class="parameter">routine_name</replaceable></term>
136 <term><replaceable class="parameter">rule_name</replaceable></term>
137 <term><replaceable class="parameter">trigger_name</replaceable></term>
138 <listitem>
139 <para>
140 The name of the object to be commented. Names of objects that reside in
141 schemas (tables, functions, etc.) can be
142 schema-qualified. When commenting on a column,
143 <replaceable class="parameter">relation_name</replaceable> must refer
144 to a table, view, composite type, or foreign table.
145 </para>
146 </listitem>
147 </varlistentry>
148
149 <varlistentry>
150 <term><replaceable class="parameter">table_name</replaceable></term>
151 <term><replaceable class="parameter">domain_name</replaceable></term>
152 <listitem>
153 <para>
154 When creating a comment on a constraint, a trigger, a rule or
155 a policy these parameters specify the name of the table or domain on
156 which that object is defined.
157 </para>
158 </listitem>
159 </varlistentry>
160
161 <varlistentry>
162 <term><replaceable>source_type</replaceable></term>
163 <listitem>
164 <para>
165 The name of the source data type of the cast.
166 </para>
167 </listitem>
168 </varlistentry>
169
170 <varlistentry>
171 <term><replaceable>target_type</replaceable></term>
172 <listitem>
173 <para>
174 The name of the target data type of the cast.
175 </para>
176 </listitem>
177 </varlistentry>
178
179 <varlistentry>
180 <term><replaceable class="parameter">argmode</replaceable></term>
181 <listitem>
182 <para>
183 The mode of a function, procedure, or aggregate
184 argument: <literal>IN</literal>, <literal>OUT</literal>,
185 <literal>INOUT</literal>, or <literal>VARIADIC</literal>.
186 If omitted, the default is <literal>IN</literal>.
187 Note that <command>COMMENT</command> does not actually pay
188 any attention to <literal>OUT</literal> arguments, since only the input
189 arguments are needed to determine the function's identity.
190 So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>,
191 and <literal>VARIADIC</literal> arguments.
192 </para>
193 </listitem>
194 </varlistentry>
195
196 <varlistentry>
197 <term><replaceable class="parameter">argname</replaceable></term>
198 <listitem>
199 <para>
200 The name of a function, procedure, or aggregate argument.
201 Note that <command>COMMENT</command> does not actually pay
202 any attention to argument names, since only the argument data
203 types are needed to determine the function's identity.
204 </para>
205 </listitem>
206 </varlistentry>
207
208 <varlistentry>
209 <term><replaceable class="parameter">argtype</replaceable></term>
210 <listitem>
211 <para>
212 The data type of a function, procedure, or aggregate argument.
213 </para>
214 </listitem>
215 </varlistentry>
216
217 <varlistentry>
218 <term><replaceable class="parameter">large_object_oid</replaceable></term>
219 <listitem>
220 <para>
221 The OID of the large object.
222 </para>
223 </listitem>
224 </varlistentry>
225
226 <varlistentry>
227 <term><replaceable class="parameter">left_type</replaceable></term>
228 <term><replaceable class="parameter">right_type</replaceable></term>
229 <listitem>
230 <para>
231 The data type(s) of the operator's arguments (optionally
232 schema-qualified). Write <literal>NONE</literal> for the missing argument
233 of a prefix operator.
234 </para>
235 </listitem>
236 </varlistentry>
237
238 <varlistentry>
239 <term><literal>PROCEDURAL</literal></term>
240 <listitem>
241 <para>
242 This is a noise word.
243 </para>
244 </listitem>
245 </varlistentry>
246
247 <varlistentry>
248 <term><replaceable>type_name</replaceable></term>
249
250 <listitem>
251 <para>
252 The name of the data type of the transform.
253 </para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term><replaceable>lang_name</replaceable></term>
259
260 <listitem>
261 <para>
262 The name of the language of the transform.
263 </para>
264 </listitem>
265 </varlistentry>
266
267 <varlistentry>
268 <term><replaceable class="parameter">string_literal</replaceable></term>
269 <listitem>
270 <para>
271 The new comment contents, written as a string literal. An empty string
272 (<literal>''</literal>) removes the comment.
273 </para>
274 </listitem>
275 </varlistentry>
276
277 <varlistentry>
278 <term><literal>NULL</literal></term>
279 <listitem>
280 <para>
281 Write <literal>NULL</literal> to remove the comment.
282 </para>
283 </listitem>
284 </varlistentry>
285
286 </variablelist>
287 </refsect1>
288
289 <refsect1>
290 <title>Notes</title>
291
292 <para>
293 There is presently no security mechanism for viewing comments: any user
294 connected to a database can see all the comments for objects in
295 that database. For shared objects such as
296 databases, roles, and tablespaces, comments are stored globally so any
297 user connected to any database in the cluster can see all the comments
298 for shared objects. Therefore, don't put security-critical
299 information in comments.
300 </para>
301 </refsect1>
302
303 <refsect1>
304 <title>Examples</title>
305
306 <para>
307 Attach a comment to the table <literal>mytable</literal>:
308
309 <programlisting>
310 COMMENT ON TABLE mytable IS 'This is my table.';
311 </programlisting>
312
313 Remove it again:
314
315 <programlisting>
316 COMMENT ON TABLE mytable IS NULL;
317 </programlisting>
318 </para>
319
320 <para>
321 Some more examples:
322
323 <programlisting>
324 COMMENT ON ACCESS METHOD gin IS 'GIN index access method';
325 COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
326 COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
327 COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
328 COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
329 COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
330 COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
331 COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain';
332 COMMENT ON DATABASE my_database IS 'Development Database';
333 COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
334 COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';
335 COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
336 COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
337 COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
338 COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
339 COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
340 COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
341 COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
342 COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';
343 COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
344 COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
345 COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
346 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
347 COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
348 COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';
349 COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';
350 COMMENT ON ROLE my_role IS 'Administration group for finance tables';
351 COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a function or procedure)';
352 COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
353 COMMENT ON SCHEMA my_schema IS 'Departmental data';
354 COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
355 COMMENT ON SERVER myserver IS 'my foreign server';
356 COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';
357 COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tables';
358 COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
359 COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
360 COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
361 COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish language';
362 COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
363 COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
364 COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore and Python dict';
365 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
366 COMMENT ON TYPE complex IS 'Complex number data type';
367 COMMENT ON VIEW my_view IS 'View of departmental costs';
368 COMMENT ON VIEW my_view IS NULL;
369 </programlisting></para>
370 </refsect1>
371
372 <refsect1>
373 <title>Compatibility</title>
374
375 <para>
376 There is no <command>COMMENT</command> command in the SQL standard.
377 </para>
378 </refsect1>
379 </refentry>