v4-0001-Document-pg_get_multixact_members.patch

From 39f1f0f4f749d8b07a8987fa9b9986ec1b17172d Mon Sep 17 00:00:00 2001
From: Sami Imseih <simseih@amazon.com>
Date: Wed, 4 Jun 2025 14:33:38 -0500
Subject: [PATCH v4 1/1] Document pg_get_multixact_members

pg_get_multixact_members has widespread usage, yet lacks official
documentation in the system functions section. There was a desire
to document in the past but it appears to have slipped due to a
lack of reviews.

Discussion: https://www.postgresql.org/message-id/flat/CAA5RZ0seQ2KyoSxUQ80OS9f8Yphe1Fu-6cSDkVG1so4ko90Q_A%40mail.gmail.com#3458b5b0c79d44b420a469c7309ea77b
---
 doc/src/sgml/func.sgml        | 51 +++++++++++++++++++++++++++++++++++
 doc/src/sgml/maintenance.sgml |  4 ++-
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c67688cbf5f9..c5bae54c6708 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -27955,6 +27955,57 @@ acl      | {postgres=arwdDxtm/postgres,foo=r/postgres}
 
   </sect2>
 
+  <sect2 id="functions-info-multixact">
+   <title>Multixact Information Functions</title>
+
+   <para>
+    The functions shown in <xref linkend="functions-multixact"/>
+    provide information about multixacts in the system.
+   </para>
+
+   <table id="functions-multixact">
+    <title>Multixact Information Functions</title>
+    <tgroup cols="1">
+     <thead>
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        Function
+       </para>
+       <para>
+        Description
+       </para></entry>
+      </row>
+     </thead>
+
+     <tbody>
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_get_multixact_members</primary>
+        </indexterm>
+        <function>pg_get_multixact_members</function> ( <type>xid</type> )
+        <returnvalue>setof record</returnvalue>
+        ( <parameter>xid</parameter> <type>xid</type>,
+        <parameter>mode</parameter> <type>text</type> )
+       </para>
+       <para>
+        Returns the transaction ID and lock mode for each member of the specified
+        multixact ID. The lock modes <literal>forupd</literal>, <literal>fornokeyupd</literal>,
+        <literal>sh</literal>, and <literal>keysh</literal> correspond to
+        the row-level locks <literal>FOR UPDATE</literal>, <literal>FOR NO KEY UPDATE</literal>,
+        <literal>FOR SHARE</literal>, and <literal>FOR KEY SHARE</literal>, respectively,
+        as described in <xref linkend="locking-rows"/>. Two additional modes are specific to
+        multixacts: <literal>nokeyupd</literal>, used by updates that do not modify key
+        columns, and <literal>upd</literal>, used by updates or deletes that modify key
+        columns.
+       </para></entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+  </sect2>
+
   <sect2 id="functions-info-controldata">
    <title>Control Data Functions</title>
 
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 600e4b3f2f3b..94f75f3da8fe 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -779,7 +779,9 @@ HINT:  Execute a database-wide VACUUM in that database.
      careful aging management, storage cleanup, and wraparound handling.
      There is a separate storage area which holds the list of members in
      each multixact, which also uses a 32-bit counter and which must also
-     be managed.
+     be managed. The system function <function>pg_get_multixact_members()</function>
+     described in <xref linkend="functions-info-multixact"/> can be used to
+     examine the transaction IDs associated with a multixact ID.
     </para>
 
     <para>
-- 
2.39.5 (Apple Git-154)