Doc: clarify pg_locks descriptions of classid/objid/objsubid
Hackorum builds and tests every patch posted to the lists, not only commitfest submissions. This is Hackorum's own CI rather than the PostgreSQL project's, and it is still under testing - please report anything that looks wrong.
You can run a PostgreSQL built from this patch straight from Docker, with no checkout and no build:
docker run --rm -p 5432:5432 ghcr.io/hackorum-dev/postgres-patch:t139168psql -h localhost -U postgresBuilt from patchset v2 (message #2), August 30, 2026 at 04:59 AM.
Every patchset is also pushed to a branch of our PostgreSQL fork, so you can check out the same tree CI built. Without a PostgreSQL checkout:
git clone --branch t139168_2 https://github.com/hackorum-dev/postgres.gitIn a checkout you already have, add the fork once:
git remote add hackorum https://github.com/hackorum-dev/postgres.gitthen, for this patchset and every later one:
git fetch hackorum t139168_2 && git checkout t139168_2Patchset v2 (message #2) is on t139168_2
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
On Mon, Mar 30, 2026 at 5:48 PM Hiroki Takamatsu
<hiroki.takamatsu.my@gmail.com> wrote:
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.
Thanks for the patch! I agree with the direction.
I made a few additional tweaks in the attached version:
- Scoped the "references ..." notes for classid and objid to the
general database object case as well.
- Changed "see below" to point explicitly to the descriptions of the
specific lock types below.
- Updated the introductory paragraph to mention speculative insertion
locks and apply transaction locks.
- Linked the subscription OID shown for apply transaction locks to
pg_subscription.oid.
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.
Agreed. The updated patch also avoids enumerating them in the column
descriptions and keeps those details in the per-lock-type descriptions.
Regards,
--
Fujii Masao