begriffs open source - ai-pg/blob - full-docs/man7/COMMENT.7

   1 '\" t
   2 .\"     Title: COMMENT
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "COMMENT" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 COMMENT \- define or change the comment of an object
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 COMMENT ON
  36 {
  37   ACCESS METHOD \fIobject_name\fR |
  38   AGGREGATE \fIaggregate_name\fR ( \fIaggregate_signature\fR ) |
  39   CAST (\fIsource_type\fR AS \fItarget_type\fR) |
  40   COLLATION \fIobject_name\fR |
  41   COLUMN \fIrelation_name\fR\&.\fIcolumn_name\fR |
  42   CONSTRAINT \fIconstraint_name\fR ON \fItable_name\fR |
  43   CONSTRAINT \fIconstraint_name\fR ON DOMAIN \fIdomain_name\fR |
  44   CONVERSION \fIobject_name\fR |
  45   DATABASE \fIobject_name\fR |
  46   DOMAIN \fIobject_name\fR |
  47   EXTENSION \fIobject_name\fR |
  48   EVENT TRIGGER \fIobject_name\fR |
  49   FOREIGN DATA WRAPPER \fIobject_name\fR |
  50   FOREIGN TABLE \fIobject_name\fR |
  51   FUNCTION \fIfunction_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] |
  52   INDEX \fIobject_name\fR |
  53   LARGE OBJECT \fIlarge_object_oid\fR |
  54   MATERIALIZED VIEW \fIobject_name\fR |
  55   OPERATOR \fIoperator_name\fR (\fIleft_type\fR, \fIright_type\fR) |
  56   OPERATOR CLASS \fIobject_name\fR USING \fIindex_method\fR |
  57   OPERATOR FAMILY \fIobject_name\fR USING \fIindex_method\fR |
  58   POLICY \fIpolicy_name\fR ON \fItable_name\fR |
  59   [ PROCEDURAL ] LANGUAGE \fIobject_name\fR |
  60   PROCEDURE \fIprocedure_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] |
  61   PUBLICATION \fIobject_name\fR |
  62   ROLE \fIobject_name\fR |
  63   ROUTINE \fIroutine_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] |
  64   RULE \fIrule_name\fR ON \fItable_name\fR |
  65   SCHEMA \fIobject_name\fR |
  66   SEQUENCE \fIobject_name\fR |
  67   SERVER \fIobject_name\fR |
  68   STATISTICS \fIobject_name\fR |
  69   SUBSCRIPTION \fIobject_name\fR |
  70   TABLE \fIobject_name\fR |
  71   TABLESPACE \fIobject_name\fR |
  72   TEXT SEARCH CONFIGURATION \fIobject_name\fR |
  73   TEXT SEARCH DICTIONARY \fIobject_name\fR |
  74   TEXT SEARCH PARSER \fIobject_name\fR |
  75   TEXT SEARCH TEMPLATE \fIobject_name\fR |
  76   TRANSFORM FOR \fItype_name\fR LANGUAGE \fIlang_name\fR |
  77   TRIGGER \fItrigger_name\fR ON \fItable_name\fR |
  78   TYPE \fIobject_name\fR |
  79   VIEW \fIobject_name\fR
  80 } IS { \fIstring_literal\fR | NULL }
  81
  82 where \fIaggregate_signature\fR is:
  83
  84 * |
  85 [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] |
  86 [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ]
  87 .fi
  88 .SH "DESCRIPTION"
  89 .PP
  90 \fBCOMMENT\fR
  91 stores a comment about a database object\&.
  92 .PP
  93 Only one comment string is stored for each object, so to modify a comment, issue a new
  94 \fBCOMMENT\fR
  95 command for the same object\&. To remove a comment, write
  96 NULL
  97 in place of the text string\&. Comments are automatically dropped when their object is dropped\&.
  98 .PP
  99 A
 100 SHARE UPDATE EXCLUSIVE
 101 lock is acquired on the object to be commented\&.
 102 .PP
 103 For most kinds of object, only the object\*(Aqs owner can set the comment\&. Roles don\*(Aqt have owners, so the rule for
 104 COMMENT ON ROLE
 105 is that you must be superuser to comment on a superuser role, or have the
 106 CREATEROLE
 107 privilege and have been granted
 108 ADMIN OPTION
 109 on the target role\&. 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\&.
 110 .PP
 111 Comments can be viewed using
 112 psql\*(Aqs
 113 \fB\ed\fR
 114 family of commands\&. Other user interfaces to retrieve comments can be built atop the same built\-in functions that
 115 psql
 116 uses, namely
 117 \fBobj_description\fR,
 118 \fBcol_description\fR, and
 119 \fBshobj_description\fR
 120 (see
 121 Table\ \&9.82)\&.
 122 .SH "PARAMETERS"
 123 .PP
 124 \fIobject_name\fR
 125 .br
 126 \fIrelation_name\fR\&.\fIcolumn_name\fR
 127 .br
 128 \fIaggregate_name\fR
 129 .br
 130 \fIconstraint_name\fR
 131 .br
 132 \fIfunction_name\fR
 133 .br
 134 \fIoperator_name\fR
 135 .br
 136 \fIpolicy_name\fR
 137 .br
 138 \fIprocedure_name\fR
 139 .br
 140 \fIroutine_name\fR
 141 .br
 142 \fIrule_name\fR
 143 .br
 144 \fItrigger_name\fR
 145 .RS 4
 146 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,
 147 \fIrelation_name\fR
 148 must refer to a table, view, composite type, or foreign table\&.
 149 .RE
 150 .PP
 151 \fItable_name\fR
 152 .br
 153 \fIdomain_name\fR
 154 .RS 4
 155 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\&.
 156 .RE
 157 .PP
 158 \fIsource_type\fR
 159 .RS 4
 160 The name of the source data type of the cast\&.
 161 .RE
 162 .PP
 163 \fItarget_type\fR
 164 .RS 4
 165 The name of the target data type of the cast\&.
 166 .RE
 167 .PP
 168 \fIargmode\fR
 169 .RS 4
 170 The mode of a function, procedure, or aggregate argument:
 171 IN,
 172 OUT,
 173 INOUT, or
 174 VARIADIC\&. If omitted, the default is
 175 IN\&. Note that
 176 \fBCOMMENT\fR
 177 does not actually pay any attention to
 178 OUT
 179 arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the
 180 IN,
 181 INOUT, and
 182 VARIADIC
 183 arguments\&.
 184 .RE
 185 .PP
 186 \fIargname\fR
 187 .RS 4
 188 The name of a function, procedure, or aggregate argument\&. Note that
 189 \fBCOMMENT\fR
 190 does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&.
 191 .RE
 192 .PP
 193 \fIargtype\fR
 194 .RS 4
 195 The data type of a function, procedure, or aggregate argument\&.
 196 .RE
 197 .PP
 198 \fIlarge_object_oid\fR
 199 .RS 4
 200 The OID of the large object\&.
 201 .RE
 202 .PP
 203 \fIleft_type\fR
 204 .br
 205 \fIright_type\fR
 206 .RS 4
 207 The data type(s) of the operator\*(Aqs arguments (optionally schema\-qualified)\&. Write
 208 NONE
 209 for the missing argument of a prefix operator\&.
 210 .RE
 211 .PP
 212 PROCEDURAL
 213 .RS 4
 214 This is a noise word\&.
 215 .RE
 216 .PP
 217 \fItype_name\fR
 218 .RS 4
 219 The name of the data type of the transform\&.
 220 .RE
 221 .PP
 222 \fIlang_name\fR
 223 .RS 4
 224 The name of the language of the transform\&.
 225 .RE
 226 .PP
 227 \fIstring_literal\fR
 228 .RS 4
 229 The new comment contents, written as a string literal\&.
 230 .RE
 231 .PP
 232 NULL
 233 .RS 4
 234 Write
 235 NULL
 236 to drop the comment\&.
 237 .RE
 238 .SH "NOTES"
 239 .PP
 240 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\&.
 241 .SH "EXAMPLES"
 242 .PP
 243 Attach a comment to the table
 244 mytable:
 245 .sp
 246 .if n \{\
 247 .RS 4
 248 .\}
 249 .nf
 250 COMMENT ON TABLE mytable IS \*(AqThis is my table\&.\*(Aq;
 251 .fi
 252 .if n \{\
 253 .RE
 254 .\}
 255 .sp
 256 Remove it again:
 257 .sp
 258 .if n \{\
 259 .RS 4
 260 .\}
 261 .nf
 262 COMMENT ON TABLE mytable IS NULL;
 263 .fi
 264 .if n \{\
 265 .RE
 266 .\}
 267 .PP
 268 Some more examples:
 269 .sp
 270 .if n \{\
 271 .RS 4
 272 .\}
 273 .nf
 274 COMMENT ON ACCESS METHOD gin IS \*(AqGIN index access method\*(Aq;
 275 COMMENT ON AGGREGATE my_aggregate (double precision) IS \*(AqComputes sample variance\*(Aq;
 276 COMMENT ON CAST (text AS int4) IS \*(AqAllow casts from text to int4\*(Aq;
 277 COMMENT ON COLLATION "fr_CA" IS \*(AqCanadian French\*(Aq;
 278 COMMENT ON COLUMN my_table\&.my_column IS \*(AqEmployee ID number\*(Aq;
 279 COMMENT ON CONVERSION my_conv IS \*(AqConversion to UTF8\*(Aq;
 280 COMMENT ON CONSTRAINT bar_col_cons ON bar IS \*(AqConstrains column col\*(Aq;
 281 COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS \*(AqConstrains col of domain\*(Aq;
 282 COMMENT ON DATABASE my_database IS \*(AqDevelopment Database\*(Aq;
 283 COMMENT ON DOMAIN my_domain IS \*(AqEmail Address Domain\*(Aq;
 284 COMMENT ON EVENT TRIGGER abort_ddl IS \*(AqAborts all DDL commands\*(Aq;
 285 COMMENT ON EXTENSION hstore IS \*(Aqimplements the hstore data type\*(Aq;
 286 COMMENT ON FOREIGN DATA WRAPPER mywrapper IS \*(Aqmy foreign data wrapper\*(Aq;
 287 COMMENT ON FOREIGN TABLE my_foreign_table IS \*(AqEmployee Information in other database\*(Aq;
 288 COMMENT ON FUNCTION my_function (timestamp) IS \*(AqReturns Roman Numeral\*(Aq;
 289 COMMENT ON INDEX my_index IS \*(AqEnforces uniqueness on employee ID\*(Aq;
 290 COMMENT ON LANGUAGE plpython IS \*(AqPython support for stored procedures\*(Aq;
 291 COMMENT ON LARGE OBJECT 346344 IS \*(AqPlanning document\*(Aq;
 292 COMMENT ON MATERIALIZED VIEW my_matview IS \*(AqSummary of order history\*(Aq;
 293 COMMENT ON OPERATOR ^ (text, text) IS \*(AqPerforms intersection of two texts\*(Aq;
 294 COMMENT ON OPERATOR \- (NONE, integer) IS \*(AqUnary minus\*(Aq;
 295 COMMENT ON OPERATOR CLASS int4ops USING btree IS \*(Aq4 byte integer operators for btrees\*(Aq;
 296 COMMENT ON OPERATOR FAMILY integer_ops USING btree IS \*(Aqall integer operators for btrees\*(Aq;
 297 COMMENT ON POLICY my_policy ON mytable IS \*(AqFilter rows by users\*(Aq;
 298 COMMENT ON PROCEDURE my_proc (integer, integer) IS \*(AqRuns a report\*(Aq;
 299 COMMENT ON PUBLICATION alltables IS \*(AqPublishes all operations on all tables\*(Aq;
 300 COMMENT ON ROLE my_role IS \*(AqAdministration group for finance tables\*(Aq;
 301 COMMENT ON ROUTINE my_routine (integer, integer) IS \*(AqRuns a routine (which is a function or procedure)\*(Aq;
 302 COMMENT ON RULE my_rule ON my_table IS \*(AqLogs updates of employee records\*(Aq;
 303 COMMENT ON SCHEMA my_schema IS \*(AqDepartmental data\*(Aq;
 304 COMMENT ON SEQUENCE my_sequence IS \*(AqUsed to generate primary keys\*(Aq;
 305 COMMENT ON SERVER myserver IS \*(Aqmy foreign server\*(Aq;
 306 COMMENT ON STATISTICS my_statistics IS \*(AqImproves planner row estimations\*(Aq;
 307 COMMENT ON SUBSCRIPTION alltables IS \*(AqSubscription for all operations on all tables\*(Aq;
 308 COMMENT ON TABLE my_schema\&.my_table IS \*(AqEmployee Information\*(Aq;
 309 COMMENT ON TABLESPACE my_tablespace IS \*(AqTablespace for indexes\*(Aq;
 310 COMMENT ON TEXT SEARCH CONFIGURATION my_config IS \*(AqSpecial word filtering\*(Aq;
 311 COMMENT ON TEXT SEARCH DICTIONARY swedish IS \*(AqSnowball stemmer for Swedish language\*(Aq;
 312 COMMENT ON TEXT SEARCH PARSER my_parser IS \*(AqSplits text into words\*(Aq;
 313 COMMENT ON TEXT SEARCH TEMPLATE snowball IS \*(AqSnowball stemmer\*(Aq;
 314 COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS \*(AqTransform between hstore and Python dict\*(Aq;
 315 COMMENT ON TRIGGER my_trigger ON my_table IS \*(AqUsed for RI\*(Aq;
 316 COMMENT ON TYPE complex IS \*(AqComplex number data type\*(Aq;
 317 COMMENT ON VIEW my_view IS \*(AqView of departmental costs\*(Aq;
 318 .fi
 319 .if n \{\
 320 .RE
 321 .\}
 322 .SH "COMPATIBILITY"
 323 .PP
 324 There is no
 325 \fBCOMMENT\fR
 326 command in the SQL standard\&.