Обсуждение: (docs): add missing info about ShareLocks

Hello

I had a production incident a few weeks ago while using deferred indexes, where the Postgres docs lead me down the
wrongpath of investigation due to missing details. Specifically, the docs implied that a `ShareLock` was only acquired
whencreating indexes, but only after looking at the code did I learn that this lock is also acquired when transactions
arewaiting for other transactions to complete. I think this would be helpful to someone who might find themselves on
thesame path in the future, and as I understand it this mailing list is the way to submit patches to the docs? 

On Sat, 2025-11-22 at 09:07 +0100, Alpha Shuro wrote:
> I had a production incident a few weeks ago while using deferred indexes, where
> the Postgres docs lead me down the wrong path of investigation due to missing details.
> Specifically, the docs implied that a `ShareLock` was only acquired when creating
> indexes, but only after looking at the code did I learn that this lock is also
> acquired when transactions are waiting for other transactions to complete.
> I think this would be helpful to someone who might find themselves on the same path
> in the future, and as I understand it this mailing list is the way to submit patches
> to the docs?

No, that is wrong.  This section is about table locks, and a lock on a transaction ID
should, if anywhere, be documented elsewhere.  Actually, there is already something
about transaction ID locks in https://www.postgresql.org/docs/current/xact-locking.html

Perhaps you could improve that short documentation?

Yours,
Laurenz Albe

PS: There are also SHARE locks on rows.

Ah thanks for pointing this out, I've moved it to the xact-locking page instead



> Den 22. nov. 2025 kl. 13.07 skrev Laurenz Albe <laurenz.albe@cybertec.at>:
>
> On Sat, 2025-11-22 at 09:07 +0100, Alpha Shuro wrote:
>> I had a production incident a few weeks ago while using deferred indexes, where
>> the Postgres docs lead me down the wrong path of investigation due to missing details.
>> Specifically, the docs implied that a `ShareLock` was only acquired when creating
>> indexes, but only after looking at the code did I learn that this lock is also
>> acquired when transactions are waiting for other transactions to complete.
>> I think this would be helpful to someone who might find themselves on the same path
>> in the future, and as I understand it this mailing list is the way to submit patches
>> to the docs?
>
> No, that is wrong.  This section is about table locks, and a lock on a transaction ID
> should, if anywhere, be documented elsewhere.  Actually, there is already something
> about transaction ID locks in https://www.postgresql.org/docs/current/xact-locking.html
>
> Perhaps you could improve that short documentation?
>
> Yours,
> Laurenz Albe
>
> PS: There are also SHARE locks on rows.

On Thu, 2025-11-27 at 12:33 +0100, Alpha Shuro wrote:
> Ah thanks for pointing this out, I've moved it to the xact-locking page instead

I think that is too specific.  You can see a session waiting for a SHARE
lock on a transaction whenever it is waiting for a row lock, since row
locks are not permanently stored in the shared memory lock table.
Rather than adding a paragraph about the specific incident that happened
to you, you should describe the general mechanism.

Some reading material:
https://www.cybertec-postgresql.com/en/row-locks-in-postgresql/

Yours,
Laurenz Albe