Concurrency control
Explain the invariant before the locking code
A maintainer can preserve the wrong lock and still break the system. Hand over the business rule, every writer that protects it and the evidence that it holds.
In this article
State the rule in ordinary language
For a reservation service, say that active reservations and confirmed bookings together cannot exceed capacity. Define which states count and when capacity is released.
This gives the next team something stable to preserve when implementation changes. A note saying the service uses row locks does not explain why those locks exist or which data belongs inside the boundary.
Include a small example of valid and invalid final state. Keep it close to the relevant code and tests.
Map all participating writers
List the API, background jobs, imports and repair tools that can affect the rule. Describe the concurrency mechanism each uses and where their shared implementation lives.
Identify any exceptional administrative path and the conditions under which it may run. A broad repair script can bypass protections that every normal request follows.
Assign ownership of the invariant to the domain team and database operation support to the appropriate platform team. Both may be needed during a contention incident, but their responsibilities differ.
Describe expected conflicts
Explain which conflicts are normal, which are retried and which reach the user. Include how drafts or operation identities are preserved after a timeout.
Show the metrics and diagnostic records used to distinguish deadlocks, stale edits and exhausted business capacity. An operator should not treat every rejected request as a database outage.
Document retry budgets and the reason for them. Increasing retries during an incident can make contention worse if the underlying resource is already saturated.
Rehearse one competing operation
Have the receiving team run the controlled race test and explain why the final state is valid. Then introduce a writer that omits the protocol and observe the test fail.
That exercise makes the dependency concrete. It also reveals whether the test protects the business rule or merely checks an implementation detail.
Keep the test and ownership map current when new integrations are added. Concurrency defects often arrive through a later writer that was never included in the original design, so the handover should show how future paths join the same protection.
Primary sources
PostgreSQL: explicit lockingReferences checked 11 September 2026.