Home • Explore • Blog • CI
☰



postgresql
2nd chunk of `doc/src/sgml/ref/comment.sgml`
e085bf076d465470a49c11b9c032e544c49a4d798da8d8c20000000100000fb7
 [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
  PUBLICATION <replaceable class="parameter">object_name</replaceable> |
  ROLE <replaceable class="parameter">object_name</replaceable> |
  ROUTINE <replaceable class="parameter">routine_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
  RULE <replaceable class="parameter">rule_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
  SCHEMA <replaceable class="parameter">object_name</replaceable> |
  SEQUENCE <replaceable class="parameter">object_name</replaceable> |
  SERVER <replaceable class="parameter">object_name</replaceable> |
  STATISTICS <replaceable class="parameter">object_name</replaceable> |
  SUBSCRIPTION <replaceable class="parameter">object_name</replaceable> |
  TABLE <replaceable class="parameter">object_name</replaceable> |
  TABLESPACE <replaceable class="parameter">object_name</replaceable> |
  TEXT SEARCH CONFIGURATION <replaceable class="parameter">object_name</replaceable> |
  TEXT SEARCH DICTIONARY <replaceable class="parameter">object_name</replaceable> |
  TEXT SEARCH PARSER <replaceable class="parameter">object_name</replaceable> |
  TEXT SEARCH TEMPLATE <replaceable class="parameter">object_name</replaceable> |
  TRANSFORM FOR <replaceable>type_name</replaceable> LANGUAGE <replaceable>lang_name</replaceable> |
  TRIGGER <replaceable class="parameter">trigger_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
  TYPE <replaceable class="parameter">object_name</replaceable> |
  VIEW <replaceable class="parameter">object_name</replaceable>
} IS { <replaceable class="parameter">string_literal</replaceable> | NULL }

<phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>

* |
[ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ] |
[ [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ] ] ORDER BY [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>COMMENT</command> stores a comment about a database object.
  </para>

  <para>
   Only one comment string is stored for each object, so to modify a comment,
   issue a new <command>COMMENT</command> command for the same object.  To remove a
   comment, write <literal>NULL</literal> in place of the text string.
   Comments are automatically dropped when their object is dropped.
  </para>

  <para>
   A <literal>SHARE UPDATE EXCLUSIVE</literal> lock is acquired on the
   object to be commented.
  </para>

  <para>
   For most kinds of object, only the object's owner can set the comment.
   Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</literal> is
   that you must be superuser to comment on a superuser role, or have the
   <literal>CREATEROLE</literal> privilege and have been granted
   <literal>ADMIN OPTION</literal> on the target role.
   Likewise, access methods don't have owners either; you must be superuser
   to comment on an access method.
   Of course, a superuser can comment on anything.
  </para>

  <para>
    Comments can be viewed using <application>psql</application>'s
    <command>\d</command> family of commands.
    Other user interfaces to retrieve comments can be built atop
    the same built-in functions that <application>psql</application> uses, namely
    <function>obj_description</function>, <function>col_description</function>,
    and <function>shobj_description</function>
    (see <xref linkend="functions-info-comment-table"/>).
Title: COMMENT Syntax and Description
Summary
This section continues the definition of the COMMENT SQL command syntax, listing the object types that can be commented on (TABLE, TABLESPACE, TEXT SEARCH CONFIGURATION, etc.) and how to specify the comment string or NULL to remove a comment. It describes the command's functionality: storing a comment about a database object, replacing existing comments, automatically dropping comments when the object is dropped, and acquiring a SHARE UPDATE EXCLUSIVE lock. It also covers permissions, stating that only the object's owner or a superuser can set the comment, with specific rules for roles and access methods. Finally, it mentions how to view comments using psql's \d commands and the underlying functions obj_description, col_description, and shobj_description.