v3-0001-Document-pg_get_multixact_members.patch

From 5129e28c268e2f4088b6d6d4b2c304c7f76ff7ca Mon Sep 17 00:00:00 2001
From: Sami Imseih <simseih@amazon.com>
Date: Wed, 4 Jun 2025 14:33:38 -0500
Subject: [PATCH v3 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        | 48 +++++++++++++++++++++++++++++++++++
 doc/src/sgml/maintenance.sgml |  4 ++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c67688cbf5f..00f32d6ce3b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -28496,6 +28496,54 @@ 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 are abbreviated names for the types of row-level
+        locks described in <xref linkend="locking-rows"/>. Two additional modes are
+        specific to multixacts: <literal>nokeyupd</literal>, used for updates that
+        do not modify key columns, and <literal>upd</literal>, used for updates or
+        deletes that do.
+       </para></entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+  </sect2>
+
   </sect1>
 
   <sect1 id="functions-admin">
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 600e4b3f2f3..94f75f3da8f 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.43.0