[SylonZero]

Summary

Parallel CodePlans MCP writes against a SQLite database failed with SQLITE_BUSY. This was seen on the multi-tenant MindStaq instance, where each workspace has its own SQLite file. Tracked as the CodePlans work item "SQLite mode: concurrent MCP writes interleave on the shared libsql connection and silently lose rows". Releases as v0.7.8: app and CLI.

Root cause

The work item blamed statements interleaving on one shared connection. That isn't what @libsql/client 0.17.3 does:

• client.transaction() handed its connection to the transaction and lazily opened a new connection for later statements.
• That new connection had a busy timeout of 0, because PRAGMA busy_timeout=5000 only ever applied to the first one. So after the first transaction in a process, any write that overlapped an open transaction failed immediately.
• The transaction's connection was never closed. In a measurement, 200 transactions left about 400 file handles open until garbage collection.

Change

• Write queue (lib/db/sqlite-writes.ts, new): one WriteQueue per local SQLite file, so one per workspace database in multi-tenant deployments.
  • db.transaction() and every statement that isn't a SELECT run one at a time.
  • Reads aren't queued; WAL lets them run beside a writer.
  • A write through db inside db.transaction() now throws NestedWriteError instead of deadlocking. None of the 10 existing transaction sites do this.
• @libsql/client 0.17.3 → 0.18.0.
  • It pools connections. A transaction borrows one and returns it on commit or rollback, and a connection left mid-transaction is rolled back or closed rather than kept.
  • Its new timeout option sets the busy timeout on every pooled connection, so the PRAGMA workaround is gone.
  • Released 2026-09-02, so it passes the deploy's minimum-release-age rule.
• lib/db/index.ts: creates the queue for file: and :memory: URLs and sends db.transaction() through it from the existing proxy. Postgres and hosted libsql (Turso) are unchanged.
• Version 0.7.8 in package.json and cli/package.json.

Why the queue is still needed with 0.18

libsql runs statements synchronously. With a pool, a write that overlaps a transaction runs on another connection and busy-waits on the lock, blocking the event loop the transaction needs in order to commit. With the queue disabled on 0.18, the parallel test took 41.7 s and still failed with SQLITE_BUSY.

Alternatives considered

Switching to better-sqlite3 was set aside. Drizzle's better-sqlite3 driver requires synchronous transaction callbacks, and all of ours await. It would also add a native build to deploys.

Testing

• New tests/lib/db/concurrent-writes.test.ts covers:
  • the busy timeout surviving a transaction
  • 100 transactions not leaving connections open
  • a parallel batch of 8 work items, a task, a spec and 2 spec links all saving and showing up in search
  • a write arriving during an open transaction waiting its turn instead of failing
  • reads not being blocked by an open transaction
  • the nested-write error
  • ordering and failure handling in WriteQueue
• These tests fail with SQLITE_BUSY against the old lib/db/index.ts.
• Full suite: 637/637. tsc --noEmit is clean (apart from stale .next/ output).
• Clean pnpm@10.33.0 install --frozen-lockfile: the only strict-build warning is sharp, the same as on master.

After merge

Tag v0.7.8 and publish the GitHub release; the Publish Release workflow also publishes the CLI.

Not addressed

The work item's "returned an id, then the row vanished" symptom never reproduced.

🤖 Generated with Claude Code