doc: Mention the level of locks taken on objects in COMMENT

michaelpq · michaelpq · commit b2a76bb7d055 · 2022-01-20T16:54:47.000+09:00
This information was nowhere to be found. This adds one note on the page of COMMENT, and one note in the section dedicated to explicit locking, both telling that a SHARE UPDATE EXCLUSIVE lock is taken on the object commented. Author: Nikolai Berkoff Reviewed-by: Laurenz Albe Discussion: https://postgr.es/m/_0HDHIGcCdCsUyXn22QwI2FEuNR6Fs71rtgGX6hfyBlUh5rrnE2qMmvIFu9EY4Pijr2gUmJEAXCjuNU2Oxku9TryLp9CdHllpsCfN3gD0-Y=@pm.me Backpatch-through: 10
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
@@ -950,10 +950,11 @@ ERROR:  could not serialize access due to read/write dependencies among transact
         <para>
          Acquired by <command>VACUUM</command> (without <option>FULL</option>),
          <command>ANALYZE</command>, <command>CREATE INDEX CONCURRENTLY</command>,
+         <command>CREATE STATISTICS</command>, <command>COMMENT ON</command>,
          <command>REINDEX CONCURRENTLY</command>,
-         <command>CREATE STATISTICS</command>, and certain <link linkend="sql-alterindex"><command>ALTER
-         INDEX</command></link> and <link linkend="sql-altertable"><command>ALTER TABLE</command></link> variants (for full
-         details see the documentation of these commands).
+         and certain <link linkend="sql-alterindex"><command>ALTER INDEX</command></link>
+         and <link linkend="sql-altertable"><command>ALTER TABLE</command></link> variants
+         (for full details see the documentation of these commands).
         </para>
        </listitem>
       </varlistentry>
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
@@ -90,6 +90,11 @@ COMMENT ON
    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
