Message-ID: <0018b6c34edba1360c618266c58292f9ff88e2f0.camel@cybertec.at>
Subject: Re: Is this paragraph in the pg_locks section still
 correct/accurate?
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: "Daniel Westermann (DWE)" <daniel.westermann@dbi-services.com>,
 PostgreSQL-documentation <pgsql-docs@lists.postgresql.org>
Date: Thu, 08 Jan 2026 22:18:30 +0100
In-Reply-To: 
 <ZR2PPFF1830B8773DF9667A61EB4EEF893ED285A@ZR2PPFF1830B877.CHEP278.PROD.OUTLOOK.COM>
References: 
	<ZR2PPFF1830B8773DF9667A61EB4EEF893ED285A@ZR2PPFF1830B877.CHEP278.PROD.OUTLOOK.COM>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.58.2 (3.58.2-1.fc43) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/0018b6c34edba1360c618266c58292f9ff88e2f0.camel%40cybertec.at>
Precedence: bulk

On Thu, 2026-01-08 at 09:49 +0000, Daniel Westermann (DWE) wrote:
> while playing a bit with pg_locks I came across this:
>=20
> https://www.postgresql.org/docs/current/view-pg-locks.html
>=20
> "Although tuples are a lockable type of object, information about row-lev=
el locks is stored on disk, not in memory,
>  and therefore row-level locks normally do not appear in this view. If a =
process is waiting for a row-level lock,
>  it will usually appear in the view as waiting for the permanent transact=
ion ID of the current holder of that row lock."
>=20
> Given this? (I've just updated the same row in two transactions):
>=20
> postgres=3D# select locktype,database::regdatabase,relation::regclass,pid=
,mode,granted,waitstart,page,tuple from pg_locks where pid !=3D pg_backend_=
pid() order by pid;
>    locktype    | database | relation | pid  |       mode       | granted =
|           waitstart           | page | tuple=20
> ---------------+----------+----------+------+------------------+---------=
+-------------------------------+------+-------
>  relation      | postgres | t        | 9673 | RowExclusiveLock | t       =
|                               |      |     =20
>  virtualxid    |          |          | 9673 | ExclusiveLock    | t       =
|                               |      |     =20
>  transactionid |          |          | 9673 | ExclusiveLock    | t       =
|                               |      |     =20
>  virtualxid    |          |          | 9691 | ExclusiveLock    | t       =
|                               |      |     =20
>  transactionid |          |          | 9691 | ShareLock        | f       =
| 2026-01-08 09:58:38.867534+01 |      |     =20
>  tuple         | postgres | t        | 9691 | ExclusiveLock    | t       =
|                               |    0 |     5
>  transactionid |          |          | 9691 | ExclusiveLock    | t       =
|                               |      |     =20
>  relation      | postgres | t        | 9691 | RowExclusiveLock | t       =
|                               |      |     =20
> (8 rows)
>=20
> ... I am wondering if that paragraph is still true or at least needs some=
 adjustments to explain what "normally"
> and "usually" means? There clearly is information about the tuple and the=
 row level lock.

A shared memory tuple lock is only taken if the row lock cannot be granted =
right away, to guarantee that
prospective lockers get served in a "first come, first served" fashion.  As=
 soon as the row is locked,
the heavyweight shared memory tuple lock is released again.

The weasel words you mention are there to avoid having to go into too much =
detail, without actively
lying to the reader.  My opinion is that whoever needs to understand this i=
n detail should read heap_lock_tuple()
in the source.  Adding too much detail might confuse the average reader mor=
e than it helps.

Yours,
Laurenz Albe