Database & ORM · Developer Error Resolution Lab

Fix SQLite Error: 'SQLITE_BUSY: database is locked'

Resolve SQLite file lock contention during concurrent write transactions by enabling Write-Ahead Logging (WAL) and setting busy_timeout.

Fix Guide:

Triggered Error Message:

SqliteError: database is locked (code 5, SQLITE_BUSY)

Customize Solution for Your Environment

Busy Timeout (ms)

// Better-SQLite3 / Prisma SQLite WAL Configuration
import Database from 'better-sqlite3';

const db = new Database('app.db', { timeout: 5000 });

// 1. Enable Write-Ahead Logging for high concurrency
db.pragma('journal_mode = WAL');

// 2. Set retry timeout to prevent immediate lock exceptions
db.pragma('busy_timeout = 5000');

// 3. Normal synchronous mode provides optimal performance with WAL
db.pragma('synchronous = NORMAL');

Root Cause & Mechanism Analysis

Why does this error occur?

SQLite is a serverless single-file database. Standard rollback journal locks the entire database file during writes. Multiple concurrent processes trying to write simultaneously trigger SQLITE_BUSY.