From af46b2916622029cb62c463d475e41ec7f4251b0 Mon Sep 17 00:00:00 2001
From: Hiroki Takamatsu <hiroki.takamatsu.my@gmail.com>
Date: Mon, 30 Mar 2026 07:13:25 +0000
Subject: [PATCH v2] doc: clarify pg_locks object identifier columns

The pg_locks descriptions for classid, objid, and objsubid said that
these columns are null when the lock target is not a general database
object.  That is not true for all lock types: advisory locks store
key fields there, speculative insertion locks store the token in objid,
and apply transaction locks store subscription and subtype information
there.

Scope the catalog-reference descriptions to the general database object
case, point readers to the lock-type-specific descriptions, and document
the subscription OID shown for apply transaction locks.
---
 doc/src/sgml/system-views.sgml | 35 +++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 5ea19d68622..a24f09dfd69 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -1795,7 +1795,9 @@ AND c1.path[c2.level] = c2.path[c2.level];
    relation is represented as a separate lockable object, as is the right to
    update <structname>pg_database</structname>.<structfield>datfrozenxid</structfield>.
    Also, <quote>advisory</quote> locks can be taken on numbers that have
-   user-defined meanings.
+   user-defined meanings.  Speculative insertion locks are identified by a
+   transaction ID and token, and apply transaction locks are used by logical
+   replication subscribers.
   </para>
 
   <table>
@@ -1902,22 +1904,27 @@ AND c1.path[c2.level] = c2.path[c2.level];
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
        <structfield>classid</structfield> <type>oid</type>
-       (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
+       (for a general database object, references
+       <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
       </para>
       <para>
-       OID of the system catalog containing the lock target, or null if the
-       target is not a general database object
+       For a general database object, the OID of the system catalog
+       containing the lock target.
+       This column is also used for other lock types; see the descriptions of
+       specific lock types below.
       </para></entry>
      </row>
 
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
        <structfield>objid</structfield> <type>oid</type>
-       (references any OID column)
+       (for a general database object, references any OID column)
       </para>
       <para>
-       OID of the lock target within its system catalog, or null if the
-       target is not a general database object
+       For a general database object, the OID of the lock target within
+       its system catalog.
+       This column is also used for other lock types; see the descriptions of
+       specific lock types below.
       </para></entry>
      </row>
 
@@ -1926,11 +1933,13 @@ AND c1.path[c2.level] = c2.path[c2.level];
        <structfield>objsubid</structfield> <type>int2</type>
       </para>
       <para>
-       Column number targeted by the lock (the
+       For a general database object, the column number targeted by the
+       lock (the
        <structfield>classid</structfield> and <structfield>objid</structfield> refer to the
        table itself),
-       or zero if the target is some other general database object,
-       or null if the target is not a general database object
+       or zero if the target is some other general database object.
+       This column is also used for other lock types; see the descriptions of
+       specific lock types below.
       </para></entry>
      </row>
 
@@ -2053,7 +2062,11 @@ AND c1.path[c2.level] = c2.path[c2.level];
   <para>
    Apply transaction locks are used in parallel mode to apply the transaction
    in logical replication. The remote transaction ID is displayed in the
-   <structfield>transactionid</structfield> column. The <structfield>objsubid</structfield>
+   <structfield>transactionid</structfield> column.  The OID of the subscription,
+   corresponding to
+   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>.<structfield>oid</structfield>,
+   is displayed in the <structfield>objid</structfield> column.
+   The <structfield>objsubid</structfield>
    displays the lock subtype which is 0 for the lock used to synchronize the
    set of changes, and 1 for the lock used to wait for the transaction to
    finish to ensure commit order.
-- 
2.55.0