Subject: Is this paragraph in the pg_locks section still correct/accurate?

From: "Daniel Westermann (DWE)" <[email-masked]>
Date: Thu, 8 Jan 2026 09:49:09 +0000

Hi, 

while playing a bit with pg_locks I came across this:

https://www.postgresql.org/docs/current/view-pg-locks.html

"Although tuples are a lockable type of object, information about row-level 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 transaction ID of the current holder of that row lock."

Given this? (I've just updated the same row in two transactions):

postgres=# select locktype,database::regdatabase,relation::regclass,pid,mode,granted,waitstart,page,tuple from pg_locks where pid != pg_backend_pid() order by pid;
   locktype    | database | relation | pid  |       mode       | granted |           waitstart           | page | tuple 
---------------+----------+----------+------+------------------+---------+-------------------------------+------+-------
 relation      | postgres | t        | 9673 | RowExclusiveLock | t       |                               |      |      
 virtualxid    |          |          | 9673 | ExclusiveLock    | t       |                               |      |      
 transactionid |          |          | 9673 | ExclusiveLock    | t       |                               |      |      
 virtualxid    |          |          | 9691 | ExclusiveLock    | t       |                               |      |      
 transactionid |          |          | 9691 | ShareLock        | f       | 2026-01-08 09:58:38.867534+01 |      |      
 tuple         | postgres | t        | 9691 | ExclusiveLock    | t       |                               |    0 |     5
 transactionid |          |          | 9691 | ExclusiveLock    | t       |                               |      |      
 relation      | postgres | t        | 9691 | RowExclusiveLock | t       |                               |      |      
(8 rows)

... 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.

Regards
Daniel

---

From: Laurenz Albe <[email-masked]>
Date: Thu, 08 Jan 2026 22:18:30 +0100

On Thu, 2026-01-08 at 09:49 +0000, Daniel Westermann (DWE) wrote:
> "Although tuples are a lockable type of object, information about row-level 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 transaction ID of the current holder of that row lock."
> 
> ... 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 in detail should read heap_lock_tuple()
in the source.  Adding too much detail might confuse the average reader more than it helps.

Yours,
Laurenz Albe