debugjavascriptdrizzleModerate
SQLite WAL busy timeout: always set it immediately after opening a connection
Viewed 0 times
sqlitebusy_timeoutSQLITE_BUSYWALwrite contentionpragmalocking
Error Messages
SqliteError: database is lockedSQLITE_BUSYProblem
Even with WAL mode enabled, SQLite applications see SQLITE_BUSY errors during write bursts because WAL still serializes writers and the default busy_timeout is 0 (fail immediately without retry).
Solution
Always set busy_timeout immediately after opening any SQLite connection that may write. Values of 3000-10000ms cover most transient contention. Combine with WAL mode and connection serialization for best results.
Why
busy_timeout = 0 means SQLite returns SQLITE_BUSY immediately without retrying. Any positive value tells SQLite to sleep-and-retry for up to that many milliseconds before giving up, transparently handling short lock waits.
Gotchas
- busy_timeout is a per-connection pragma — it must be set on every new connection
- Very high busy_timeout values can make slow operations appear to hang
- Transactions that hold write locks longer than busy_timeout will still cause failures in concurrent writers
Code Snippets
Minimal safe SQLite setup for any write-capable connection
const db = new Database(dbPath);
db.pragma('journal_mode = WAL');
db.pragma('busy_timeout = 5000');
db.pragma('synchronous = NORMAL'); // faster than FULL, safe with WALRevisions (0)
No revisions yet.