SQLite WAL Lock Contention Triage Runbook Builder

Create a SQLite WAL lock contention triage runbook for mobile, desktop, edge, or embedded apps with busy timeouts, long readers, checkpoints, and safe fixes.

Prompt Template

You are a senior database reliability engineer debugging SQLite Write-Ahead Logging lock contention. Build a triage runbook for:

Application context: [iOS app, Android app, desktop app, Electron app, CLI, edge worker, embedded device, local-first app]
SQLite wrapper or ORM: [raw sqlite3, better-sqlite3, Room, GRDB, Core Data SQLite store, SQLDelight, Drizzle, Prisma adapter, custom]
Runtime and threading model: [single process, worker threads, multiprocess, background sync, UI thread, cron job, service worker]
Database mode and settings: [WAL enabled, rollback journal, busy_timeout, synchronous mode, mmap, cache size, checkpoint settings]
Symptoms: [database is locked, SQLITE_BUSY, slow writes, checkpoint stalls, UI freezes, sync failures, battery drain, startup delay]
Workload pattern: [frequent small writes, batch import, background sync, analytics queue, search index, attachment metadata, offline edits]
Transaction behavior: [implicit transactions, long read transaction, BEGIN IMMEDIATE, batch writes, nested transaction helper, unknown]
File system context: [local disk, app sandbox, network drive, cloud-synced folder, removable storage, encrypted volume]
Observability available: [logs, traces, sqlite pragmas, profiler, ORM query logs, production crash reports, local reproduction]
Recent changes: [new sync loop, migration, ORM update, background worker, checkpoint schedule, query change, cache change]
Constraints: [no data loss, mobile battery, offline use, low memory, release deadline, privacy-safe logs]

Create:
1. Fast safety checklist for backup, reproduction data, privacy, and migration risk.
2. Evidence plan to separate writer contention, long readers, checkpoint stalls, file-system issues, and ORM misuse.
3. Instrumentation checklist for busy events, transaction duration, connection count, thread/process ownership, and checkpoint timing.
4. SQLite PRAGMA and diagnostic query list with what each result means.
5. Transaction audit for implicit writes, long reads, batch size, BEGIN modes, and cursor lifetime.
6. Fix decision tree covering busy_timeout, single-writer queues, shorter transactions, read lifecycle, checkpoint strategy, batching, and schema/index changes.
7. Mobile and desktop edge-case checklist for app lifecycle, background tasks, cloud sync folders, and file locks.
8. Regression test plan with concurrent readers/writers, sync replay, app resume, and large import scenarios.
9. Rollout and rollback checklist with metrics to watch.
10. Escalation packet for app, backend sync, data, and QA owners.

Do not suggest deleting the database, disabling journaling blindly, or changing durability settings without naming the data-loss tradeoff. Mark platform-specific commands as examples to verify.

Example Output

Likely Contention Map

| Signal | Likely Cause | Next Check |

|---|---|---|

| SQLITE_BUSY during short writes | Another writer or long read | Log transaction duration and connection owner |

| WAL file grows without shrinking | Checkpoint blocked by reader | Inspect long-lived cursors and read transactions |

| UI freezes during import | Writes on main thread | Move batches to single writer queue |

First Fix Candidate

Route all writes through one serialized writer and cap batch transactions at [N] rows, then measure busy events, p95 write duration, WAL size, and app resume latency.

Regression Guard

Replay a background sync while a screen holds an active read cursor, then assert no write exceeds the agreed timeout budget.

Tips for Best Results

  • 💡Ask about the wrapper or ORM because SQLite lock bugs often come from connection lifecycle rather than SQL syntax.
  • 💡Separate checkpoint stalls from writer contention before changing busy_timeout.
  • 💡Treat WAL settings as durability decisions; performance fixes should not silently weaken data safety.