Stop deadlocks between parallel step and image saves (#43) #46

Merged
miko merged 2 commits from feature/43-write-conflict-row-locks into development 2026-11-02 19:29:27 +01:00
Owner

Closes #43.

Root cause

The database is MySQL 8.4, not MariaDB. Prisma reports MySQL error 1213 (deadlock) as TransactionWriteConflict; the queryRaw in the stack trace is the adapter's own method, not lockStep. The statement that failed was stepLine.create in saveStep.

Under REPEATABLE READ, deleteMany({where: {stepId}}) on a step with no lines takes a gap lock on the (stepId, position) index. When two parallel tests save empty steps whose ids fall in the same gap, both get the gap lock and each insert waits for the other. A two-connection script reproduces this: 1213 under REPEATABLE READ, no error under READ COMMITTED. Annotations are replaced the same way (delete, then insert).

Changes

  • READ COMMITTED for all transactions (src/db.ts, the client's default transactionOptions). Transactions already serialise on parent-row locks, so the gap locks guarded nothing.
  • One lock order. saveStep locked the guide and then the step; image and annotation changes locked the step and then the guide (via touchGuide), so they could deadlock on each other. lockStep is gone: every change inside a guide takes lockGuide first. addStep now takes it too, so two adds at once can't get the same position.
  • ADR-0013 records the rule.

Verification

  • Before: the full parallel suite failed on its first run.
  • After: 8 full parallel runs and 6 runs with --repeat-each=3, with no retries, every one passing and no write-conflict lines in the server log.
  • Typecheck, lint and the 272 unit tests pass.

🤖 Generated with Claude Code

Closes #43. ## Root cause The database is MySQL 8.4, not MariaDB. Prisma reports MySQL error 1213 (deadlock) as `TransactionWriteConflict`; the `queryRaw` in the stack trace is the adapter's own method, not `lockStep`. The statement that failed was `stepLine.create` in `saveStep`. Under REPEATABLE READ, `deleteMany({where: {stepId}})` on a step with no lines takes a gap lock on the `(stepId, position)` index. When two parallel tests save empty steps whose ids fall in the same gap, both get the gap lock and each insert waits for the other. A two-connection script reproduces this: 1213 under REPEATABLE READ, no error under READ COMMITTED. Annotations are replaced the same way (delete, then insert). ## Changes - **READ COMMITTED for all transactions** (`src/db.ts`, the client's default `transactionOptions`). Transactions already serialise on parent-row locks, so the gap locks guarded nothing. - **One lock order.** `saveStep` locked the guide and then the step; image and annotation changes locked the step and then the guide (via `touchGuide`), so they could deadlock on each other. `lockStep` is gone: every change inside a guide takes `lockGuide` first. `addStep` now takes it too, so two adds at once can't get the same position. - **ADR-0013** records the rule. ## Verification - Before: the full parallel suite failed on its first run. - After: 8 full parallel runs and 6 runs with `--repeat-each=3`, with no retries, every one passing and no write-conflict lines in the server log. - Typecheck, lint and the 272 unit tests pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Saving two empty steps at once deadlocked (MySQL 1213, which Prisma reports
as TransactionWriteConflict): deleting each step's lines by stepId under
REPEATABLE READ locks the same index gap, and each first insert then waits
for the other's gap lock. Transactions already serialise by locking their
parent row first, so the gap locks guarded nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Saving a step locked the guide and then wrote the step, while image and
annotation changes locked the step and then wrote the guide as its last
editor, so the two could deadlock on each other. Every change inside a guide
now takes the guide's lock first; addStep takes it too, so concurrent adds
cannot get the same position. ADR-0013 records the rule, and the db.ts
comment points to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit be6482f9c0 into development 2026-11-02 19:29:27 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!46
No description provided.