public inbox for [email protected]
help / color / mirror / Atom feedFrom: Hiroki Takamatsu <[email protected]>
To: [email protected]
Subject: Doc: clarify pg_locks descriptions of classid/objid/objsubid
Date: Mon, 30 Mar 2026 17:48:10 +0900
Message-ID: <CA+r=ywWUHOPgHp-tegoETpfjiEkE5Ytzi4g9orcKav8bWym+_Q@mail.gmail.com> (raw)
Hi hackers,
It seems that the descriptions of classid, objid, and objsubid in the
pg_locks documentation are not quite accurate for all lock types.
The documentation currently says these columns are null if the lock
target is not a general database object.
However, pg_lock_status() (lockfuncs.c) also populates these columns
for other lock types, including advisory locks,
speculative insertion locks, and apply transaction locks.
The detailed prose below the table already describes
some of these uses, so the table entries and the prose seem to be
inconsistent.
The attached patch:
1. rewrites each column description to scope it to the general database
object case, instead of making a false claim about NULL behavior for
all other lock types;
2. adds a pointer to the detailed per-lock-type prose below; and
3. documents that apply transaction locks show the subscription OID in
objid.
I chose not to enumerate all non-object lock types in the column
descriptions, since that seemed easy to let drift again as new lock
types are added.
Do you think?
Regards,
Hiroki Takamatsu
Attachments:
[application/octet-stream] 0001-clarify-pg_locks-descriptions-of-classid-objid-objsu.patch (3.0K, ../CA+r=ywWUHOPgHp-tegoETpfjiEkE5Ytzi4g9orcKav8bWym+_Q@mail.gmail.com/3-0001-clarify-pg_locks-descriptions-of-classid-objid-objsu.patch)
download | inline diff:
From b244129c2ec77aa96be423d6e859c29f1e319b0e Mon Sep 17 00:00:00 2001
From: Hiroki Takamatsu <[email protected]>
Date: Mon, 30 Mar 2026 07:13:25 +0000
Subject: [PATCH] clarify pg_locks descriptions of classid/objid/objsubid
---
doc/src/sgml/system-views.sgml | 21 +++++++++++++--------
1 file changed, 13 insertions(+), 8 deletions(-)
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 9ee1a2bfc6a..a72295801b7 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -1905,8 +1905,9 @@ AND c1.path[c2.level] = c2.path[c2.level];
(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 below.
</para></entry>
</row>
@@ -1916,8 +1917,9 @@ AND c1.path[c2.level] = c2.path[c2.level];
(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 below.
</para></entry>
</row>
@@ -1926,11 +1928,12 @@ 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 below.
</para></entry>
</row>
@@ -2053,7 +2056,9 @@ 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 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.47.3
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected]
Subject: Re: Doc: clarify pg_locks descriptions of classid/objid/objsubid
In-Reply-To: <CA+r=ywWUHOPgHp-tegoETpfjiEkE5Ytzi4g9orcKav8bWym+_Q@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox