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

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
index 5cdbcfa4d6499704298907ddf791bd153783d40a..d51641079a0e5de269afa2ce457b129c927e91fa 100644 (file)
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -950,11 +950,12 @@ 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 <command>ALTER
-         INDEX</command> and <command>ALTER TABLE</command> variants (for full
-         details see <xref linkend="sql-alterindex"/> and <xref
-         linkend="sql-altertable"/>).
+         and certain <command>ALTER INDEX</command> and
+         <command>ALTER TABLE</command> variants
+         (for full details see <xref linkend="sql-alterindex"/> and
+         <xref linkend="sql-altertable"/>).
         </para>
        </listitem>
       </varlistentry>

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index fd7492a25567e5379909ad6f917042238fb423b4..138cf718ce11ea2973e065fd3c779c2964e47dd4 100644 (file)
--- 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