(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 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?
Attachments:
0001-document-ShareLock-behaviour-when-using-a-deferred-u.patchapplication/octet-stream; name=0001-document-ShareLock-behaviour-when-using-a-deferred-u.patch; x-unix-mode=0644Download+5-1
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
Attachments:
document-ShareLock-when-using-deferred-unique.patchapplication/octet-stream; name=document-ShareLock-when-using-deferred-unique.patch; x-unix-mode=0644Download+7-0
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