How do I fix "database is locked" in SQLite?

If another connection wrote and committed in the meantime, this transaction's snapshot is out of date. Waiting can't help, because the data it read has changed, so SQLite returns SQLITE_BUSY immediately and ignores busy_timeout. (In WAL mode this is SQLITE_BUSY_SNAPSHOT.)

The fix: start every transaction that will write with BEGIN IMMEDIATE:

BEGIN IMMEDIATE;   -- take the write lock now; waits (busy_timeout) if it's held
SELECT balance FROM accounts WHERE id = 1;
UPDATE accounts SET balance = balance - 10 WHERE id = 1;
COMMIT;

The wait now happens at BEGIN, where the busy handler applies, and the transaction never has to upgrade. Most frameworks let you configure this. For example, Django 5.1+ has "transaction_mode": "IMMEDIATE" in the SQLite OPTIONS, and recent Rails versions use immediate transactions for SQLite by default.

Enable WAL mode

In the default rollback-journal mode, a writer blocks readers and readers block the writer from committing. WAL mode lets readers and the writer work at the same time:

PRAGMA journal_mode = WAL;       -- persistent: set once per database
PRAGMA synchronous = NORMAL;     -- safe with WAL, much faster commits

It's still one writer at a time, but reads no longer cause lock errors for writes.

Keep write transactions short

Every millisecond a write transaction is open, every other writer waits.

• Don't do network calls, file I/O or heavy computation inside a write transaction.
• Batch many small writes into one transaction. 1,000 inserts in one transaction is dramatically faster than 1,000 auto-committed ones.
• Close cursors and finalize statements. An unfinished SELECT (a cursor you didn't read to the end, or a statement that was never reset) keeps a read transaction open. In rollback-journal mode that blocks writers from committing, and in WAL mode it stops checkpoints from resetting the WAL file.

Serialize writers in the app

When many threads or workers write, it's often simplest to send all writes through one connection (or a mutex or queue) and use a pool of separate read-only connections. That removes lock contention between writers entirely and matches SQLite's model.

Things that cause locking you can't fix

• Network filesystems (NFS, SMB, some Docker volume drivers on macOS and Windows). File locking is often unreliable there, so you get spurious lock errors or, worse, corruption. Keep the database on a local disk.
• Very high write concurrency from many machines. SQLite is an embedded database. If writes must come from many hosts, you've outgrown it: move to a client/server database or a replicated SQLite service.

A good baseline for every connection

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA busy_timeout = 5000;
PRAGMA foreign_keys = ON;

Add BEGIN IMMEDIATE for write transactions, and most "database is locked" errors go away.

Checklist

1. Set busy_timeout on every connection. The default is 0.
2. Start write transactions with BEGIN IMMEDIATE to avoid lock-upgrade failures.
3. Enable WAL mode with synchronous = NORMAL.
4. Keep write transactions short and batched, and close cursors.
5. Use a single writer connection, and keep the file on a local disk.

How do I fix SQLITE_BUSY ("database is locked") in Python?

Why Python raises "database is locked", how timeout, isolation_level and autocommit interact, and the working pattern for threads, worker processes, SQLAlchemy, Django and aiosqlite.

#concurrency#locking#orm