[DOCS] document ShareLock behaviour when using a deferred unique index
The logs that were printed by Postgres when enforcing deferred unique indexes were misleading. This change should make it easier to understand or investigate when users see the `waits for ShareLock` log entry --- doc/src/sgml/mvcc.sgml | 5 + 1 file changed, 5 insertions(+) diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 049ee75a4ba..4e36c59776a 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -1003,32 +1003,37 @@ ERROR: could not serialize access due to read/write dependencies among transact SHARE (ShareLock) Conflicts with the ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE ROW EXCLUSIVE, EXCLUSIVE, and ACCESS EXCLUSIVE lock modes. This mode protects a table against concurrent data changes. Acquired by CREATE INDEX (without CONCURRENTLY). + + It is also acquired when enforcing a DEFERRED UNIQUE INDEX: + If a transaction detects another transaction that might cause + a potential conflict, it waits for the other transaction to complete, + by acquiring a ShareLock on the other transaction's transaction id. -- 2.51.0
(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? 0001-document-ShareLock-behaviour-when-using-a-deferred-u.patch Description: Binary data
Re: (docs): add missing info about ShareLocks
Ah thanks for pointing this out, I've moved it to the xact-locking page instead document-ShareLock-when-using-deferred-unique.patch Description: Binary data > Den 22. nov. 2025 kl. 13.07 skrev Laurenz Albe : > > 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.
