codekingpro/portable-devtools
115k
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 16.3 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">3COMMENT ON4{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 a60 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 the64 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> is68 that you must be superuser to comment on a superuser role, or have the69 <code class="literal">CREATEROLE</code> privilege and have been granted70 <code class="literal">ADMIN OPTION</code> on the target role.71 Likewise, access methods don't have owners either; you must be superuser72 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>'s76 <code class="command">\d</code> family of commands.77 Other user interfaces to retrieve comments can be built atop78 the same built-in functions that <span class="application">psql</span> uses, namely79 <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.78. Comment Information Functions">Table 9.78</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 in84 schemas (tables, functions, etc.) can be85 schema-qualified. When commenting on a column,86 <em class="replaceable"><code>relation_name</code></em> must refer87 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 or90 a policy these parameters specify the name of the table or domain on91 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 aggregate98 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 pay102 any attention to <code class="literal">OUT</code> arguments, since only the input103 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 pay109 any attention to argument names, since only the argument data110 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 (optionally117 schema-qualified). Write <code class="literal">NONE</code> for the missing argument118 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 user131 connected to a database can see all the comments for objects in132 that database. For shared objects such as133 databases, roles, and tablespaces, comments are stored globally so any134 user connected to any database in the cluster can see all the comments135 for shared objects. Therefore, don't put security-critical136 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">141COMMENT ON TABLE mytable IS 'This is my table.';142</pre><p>143 144 Remove it again:145 146</p><pre class="programlisting">147COMMENT ON TABLE mytable IS NULL;148</pre><p>149 </p><p>150 Some more examples:151 152</p><pre class="programlisting">153COMMENT ON ACCESS METHOD gin IS 'GIN index access method';154COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';155COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';156COMMENT ON COLLATION "fr_CA" IS 'Canadian French';157COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';158COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';159COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';160COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain';161COMMENT ON DATABASE my_database IS 'Development Database';162COMMENT ON DOMAIN my_domain IS 'Email Address Domain';163COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';164COMMENT ON EXTENSION hstore IS 'implements the hstore data type';165COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';166COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';167COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';168COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';169COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';170COMMENT ON LARGE OBJECT 346344 IS 'Planning document';171COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';172COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';173COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';174COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';175COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';176COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';177COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';178COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';179COMMENT ON ROLE my_role IS 'Administration group for finance tables';180COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a function or procedure)';181COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';182COMMENT ON SCHEMA my_schema IS 'Departmental data';183COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';184COMMENT ON SERVER myserver IS 'my foreign server';185COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';186COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tables';187COMMENT ON TABLE my_schema.my_table IS 'Employee Information';188COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';189COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';190COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish language';191COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';192COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';193COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore and Python dict';194COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';195COMMENT ON TYPE complex IS 'Complex number data type';196COMMENT 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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COMMIT</td></tr></table></div></body></html>