summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/man7/COMMENT.7
blob: 34cc997b1842bf01fa7aa00efdb585899ec72c0d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
'\" t
.\"     Title: COMMENT
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024
.\"    Manual: PostgreSQL 15.7 Documentation
.\"    Source: PostgreSQL 15.7
.\"  Language: English
.\"
.TH "COMMENT" "7" "2024" "PostgreSQL 15.7" "PostgreSQL 15.7 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
COMMENT \- define or change the comment of an object
.SH "SYNOPSIS"
.sp
.nf
COMMENT ON
{
  ACCESS METHOD \fIobject_name\fR |
  AGGREGATE \fIaggregate_name\fR ( \fIaggregate_signature\fR ) |
  CAST (\fIsource_type\fR AS \fItarget_type\fR) |
  COLLATION \fIobject_name\fR |
  COLUMN \fIrelation_name\fR\&.\fIcolumn_name\fR |
  CONSTRAINT \fIconstraint_name\fR ON \fItable_name\fR |
  CONSTRAINT \fIconstraint_name\fR ON DOMAIN \fIdomain_name\fR |
  CONVERSION \fIobject_name\fR |
  DATABASE \fIobject_name\fR |
  DOMAIN \fIobject_name\fR |
  EXTENSION \fIobject_name\fR |
  EVENT TRIGGER \fIobject_name\fR |
  FOREIGN DATA WRAPPER \fIobject_name\fR |
  FOREIGN TABLE \fIobject_name\fR |
  FUNCTION \fIfunction_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] |
  INDEX \fIobject_name\fR |
  LARGE OBJECT \fIlarge_object_oid\fR |
  MATERIALIZED VIEW \fIobject_name\fR |
  OPERATOR \fIoperator_name\fR (\fIleft_type\fR, \fIright_type\fR) |
  OPERATOR CLASS \fIobject_name\fR USING \fIindex_method\fR |
  OPERATOR FAMILY \fIobject_name\fR USING \fIindex_method\fR |
  POLICY \fIpolicy_name\fR ON \fItable_name\fR |
  [ PROCEDURAL ] LANGUAGE \fIobject_name\fR |
  PROCEDURE \fIprocedure_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] |
  PUBLICATION \fIobject_name\fR |
  ROLE \fIobject_name\fR |
  ROUTINE \fIroutine_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] |
  RULE \fIrule_name\fR ON \fItable_name\fR |
  SCHEMA \fIobject_name\fR |
  SEQUENCE \fIobject_name\fR |
  SERVER \fIobject_name\fR |
  STATISTICS \fIobject_name\fR |
  SUBSCRIPTION \fIobject_name\fR |
  TABLE \fIobject_name\fR |
  TABLESPACE \fIobject_name\fR |
  TEXT SEARCH CONFIGURATION \fIobject_name\fR |
  TEXT SEARCH DICTIONARY \fIobject_name\fR |
  TEXT SEARCH PARSER \fIobject_name\fR |
  TEXT SEARCH TEMPLATE \fIobject_name\fR |
  TRANSFORM FOR \fItype_name\fR LANGUAGE \fIlang_name\fR |
  TRIGGER \fItrigger_name\fR ON \fItable_name\fR |
  TYPE \fIobject_name\fR |
  VIEW \fIobject_name\fR
} IS { \fIstring_literal\fR | NULL }

where \fIaggregate_signature\fR is:

* |
[ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] |
[ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ]
.fi
.SH "DESCRIPTION"
.PP
\fBCOMMENT\fR
stores a comment about a database object\&.
.PP
Only one comment string is stored for each object, so to modify a comment, issue a new
\fBCOMMENT\fR
command for the same object\&. To remove a comment, write
NULL
in place of the text string\&. Comments are automatically dropped when their object is dropped\&.
.PP
A
SHARE UPDATE EXCLUSIVE
lock is acquired on the object to be commented\&.
.PP
For most kinds of object, only the object\*(Aqs owner can set the comment\&. Roles don\*(Aqt have owners, so the rule for
COMMENT ON ROLE
is that you must be superuser to comment on a superuser role, or have the
CREATEROLE
privilege to comment on non\-superuser roles\&. Likewise, access methods don\*(Aqt have owners either; you must be superuser to comment on an access method\&. Of course, a superuser can comment on anything\&.
.PP
Comments can be viewed using
psql\*(Aqs
\fB\ed\fR
family of commands\&. Other user interfaces to retrieve comments can be built atop the same built\-in functions that
psql
uses, namely
\fBobj_description\fR,
\fBcol_description\fR, and
\fBshobj_description\fR
(see
Table\ \&9.77)\&.
.SH "PARAMETERS"
.PP
\fIobject_name\fR
.br
\fIrelation_name\fR\&.\fIcolumn_name\fR
.br
\fIaggregate_name\fR
.br
\fIconstraint_name\fR
.br
\fIfunction_name\fR
.br
\fIoperator_name\fR
.br
\fIpolicy_name\fR
.br
\fIprocedure_name\fR
.br
\fIroutine_name\fR
.br
\fIrule_name\fR
.br
\fItrigger_name\fR
.RS 4
The name of the object to be commented\&. Names of objects that reside in schemas (tables, functions, etc\&.) can be schema\-qualified\&. When commenting on a column,
\fIrelation_name\fR
must refer to a table, view, composite type, or foreign table\&.
.RE
.PP
\fItable_name\fR
.br
\fIdomain_name\fR
.RS 4
When creating a comment on a constraint, a trigger, a rule or a policy these parameters specify the name of the table or domain on which that object is defined\&.
.RE
.PP
\fIsource_type\fR
.RS 4
The name of the source data type of the cast\&.
.RE
.PP
\fItarget_type\fR
.RS 4
The name of the target data type of the cast\&.
.RE
.PP
\fIargmode\fR
.RS 4
The mode of a function, procedure, or aggregate argument:
IN,
OUT,
INOUT, or
VARIADIC\&. If omitted, the default is
IN\&. Note that
\fBCOMMENT\fR
does not actually pay any attention to
OUT
arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the
IN,
INOUT, and
VARIADIC
arguments\&.
.RE
.PP
\fIargname\fR
.RS 4
The name of a function, procedure, or aggregate argument\&. Note that
\fBCOMMENT\fR
does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&.
.RE
.PP
\fIargtype\fR
.RS 4
The data type of a function, procedure, or aggregate argument\&.
.RE
.PP
\fIlarge_object_oid\fR
.RS 4
The OID of the large object\&.
.RE
.PP
\fIleft_type\fR
.br
\fIright_type\fR
.RS 4
The data type(s) of the operator\*(Aqs arguments (optionally schema\-qualified)\&. Write
NONE
for the missing argument of a prefix operator\&.
.RE
.PP
PROCEDURAL
.RS 4
This is a noise word\&.
.RE
.PP
\fItype_name\fR
.RS 4
The name of the data type of the transform\&.
.RE
.PP
\fIlang_name\fR
.RS 4
The name of the language of the transform\&.
.RE
.PP
\fIstring_literal\fR
.RS 4
The new comment contents, written as a string literal\&.
.RE
.PP
NULL
.RS 4
Write
NULL
to drop the comment\&.
.RE
.SH "NOTES"
.PP
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\*(Aqt put security\-critical information in comments\&.
.SH "EXAMPLES"
.PP
Attach a comment to the table
mytable:
.sp
.if n \{\
.RS 4
.\}
.nf
COMMENT ON TABLE mytable IS \*(AqThis is my table\&.\*(Aq;
.fi
.if n \{\
.RE
.\}
.sp
Remove it again:
.sp
.if n \{\
.RS 4
.\}
.nf
COMMENT ON TABLE mytable IS NULL;
.fi
.if n \{\
.RE
.\}
.PP
Some more examples:
.sp
.if n \{\
.RS 4
.\}
.nf
COMMENT ON ACCESS METHOD gin IS \*(AqGIN index access method\*(Aq;
COMMENT ON AGGREGATE my_aggregate (double precision) IS \*(AqComputes sample variance\*(Aq;
COMMENT ON CAST (text AS int4) IS \*(AqAllow casts from text to int4\*(Aq;
COMMENT ON COLLATION "fr_CA" IS \*(AqCanadian French\*(Aq;
COMMENT ON COLUMN my_table\&.my_column IS \*(AqEmployee ID number\*(Aq;
COMMENT ON CONVERSION my_conv IS \*(AqConversion to UTF8\*(Aq;
COMMENT ON CONSTRAINT bar_col_cons ON bar IS \*(AqConstrains column col\*(Aq;
COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS \*(AqConstrains col of domain\*(Aq;
COMMENT ON DATABASE my_database IS \*(AqDevelopment Database\*(Aq;
COMMENT ON DOMAIN my_domain IS \*(AqEmail Address Domain\*(Aq;
COMMENT ON EVENT TRIGGER abort_ddl IS \*(AqAborts all DDL commands\*(Aq;
COMMENT ON EXTENSION hstore IS \*(Aqimplements the hstore data type\*(Aq;
COMMENT ON FOREIGN DATA WRAPPER mywrapper IS \*(Aqmy foreign data wrapper\*(Aq;
COMMENT ON FOREIGN TABLE my_foreign_table IS \*(AqEmployee Information in other database\*(Aq;
COMMENT ON FUNCTION my_function (timestamp) IS \*(AqReturns Roman Numeral\*(Aq;
COMMENT ON INDEX my_index IS \*(AqEnforces uniqueness on employee ID\*(Aq;
COMMENT ON LANGUAGE plpython IS \*(AqPython support for stored procedures\*(Aq;
COMMENT ON LARGE OBJECT 346344 IS \*(AqPlanning document\*(Aq;
COMMENT ON MATERIALIZED VIEW my_matview IS \*(AqSummary of order history\*(Aq;
COMMENT ON OPERATOR ^ (text, text) IS \*(AqPerforms intersection of two texts\*(Aq;
COMMENT ON OPERATOR \- (NONE, integer) IS \*(AqUnary minus\*(Aq;
COMMENT ON OPERATOR CLASS int4ops USING btree IS \*(Aq4 byte integer operators for btrees\*(Aq;
COMMENT ON OPERATOR FAMILY integer_ops USING btree IS \*(Aqall integer operators for btrees\*(Aq;
COMMENT ON POLICY my_policy ON mytable IS \*(AqFilter rows by users\*(Aq;
COMMENT ON PROCEDURE my_proc (integer, integer) IS \*(AqRuns a report\*(Aq;
COMMENT ON PUBLICATION alltables IS \*(AqPublishes all operations on all tables\*(Aq;
COMMENT ON ROLE my_role IS \*(AqAdministration group for finance tables\*(Aq;
COMMENT ON ROUTINE my_routine (integer, integer) IS \*(AqRuns a routine (which is a function or procedure)\*(Aq;
COMMENT ON RULE my_rule ON my_table IS \*(AqLogs updates of employee records\*(Aq;
COMMENT ON SCHEMA my_schema IS \*(AqDepartmental data\*(Aq;
COMMENT ON SEQUENCE my_sequence IS \*(AqUsed to generate primary keys\*(Aq;
COMMENT ON SERVER myserver IS \*(Aqmy foreign server\*(Aq;
COMMENT ON STATISTICS my_statistics IS \*(AqImproves planner row estimations\*(Aq;
COMMENT ON SUBSCRIPTION alltables IS \*(AqSubscription for all operations on all tables\*(Aq;
COMMENT ON TABLE my_schema\&.my_table IS \*(AqEmployee Information\*(Aq;
COMMENT ON TABLESPACE my_tablespace IS \*(AqTablespace for indexes\*(Aq;
COMMENT ON TEXT SEARCH CONFIGURATION my_config IS \*(AqSpecial word filtering\*(Aq;
COMMENT ON TEXT SEARCH DICTIONARY swedish IS \*(AqSnowball stemmer for Swedish language\*(Aq;
COMMENT ON TEXT SEARCH PARSER my_parser IS \*(AqSplits text into words\*(Aq;
COMMENT ON TEXT SEARCH TEMPLATE snowball IS \*(AqSnowball stemmer\*(Aq;
COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS \*(AqTransform between hstore and Python dict\*(Aq;
COMMENT ON TRIGGER my_trigger ON my_table IS \*(AqUsed for RI\*(Aq;
COMMENT ON TYPE complex IS \*(AqComplex number data type\*(Aq;
COMMENT ON VIEW my_view IS \*(AqView of departmental costs\*(Aq;
.fi
.if n \{\
.RE
.\}
.SH "COMPATIBILITY"
.PP
There is no
\fBCOMMENT\fR
command in the SQL standard\&.