SQLite: database is locked

Result code

SQLITE_BUSY (5); extended SQLITE_BUSY_SNAPSHOT (517) in WAL mode; SQLITE_BUSY_RECOVERY (261) during WAL recovery

Product

SQLite library

Versions

SQLite 3.x (examples run on 3.39.2; shell output from 3.50.6); WAL mode from 3.7.0

Category

Locking & Transactions

Last reviewed

24 October 2026

What it means

This error means another connection was writing to (or, in rollback-journal mode, reading from) the database file, and your statement gave up waiting for the lock.

SQLite allows many readers but only one writer per database file at a time. A connection that starts writing takes a lock on the file; any other connection that also wants to write gets SQLITE_BUSY. In the default rollback-journal mode the conflict also runs the other way: a writer cannot commit while another connection holds an open read transaction, and nobody can read while a writer holds the EXCLUSIVE lock to update the file. The lock belongs to a connection, so a common cause is in the same program: a second connection, an unfinished transaction or an unread result set that keeps a read transaction open. A database browser left open on the same file with uncommitted changes has the same effect.

Whether you see the error at once depends on the busy timeout. With a timeout, SQLite retries until the lock clears or the time is up; with 0 it fails immediately. The C library, the PHP SQLite3 class and the sqlite3 shell start at 0; PHP PDO sets 60 seconds (we read 60000 ms from PRAGMA busy_timeout) and Python's sqlite3 module defaults to 5 seconds, so in those the error means the wait expired. In some cases SQLite returns SQLITE_BUSY without waiting, because waiting could never succeed: when a connection with an open read transaction tries to write while another connection is already committing, and in WAL mode when another connection has written since your transaction read its snapshot (extended code 517, SQLITE_BUSY_SNAPSHOT). A related message, "database table is locked" (SQLITE_LOCKED), is a conflict inside one connection: we reproduced it with the PHP SQLite3 class by running DROP TABLE while a SELECT on the same connection was still being read.

Common causes

• Two connections write at the same time: two processes, two threads with their own connections, or a web server handling requests in parallel.
• A transaction or result set is left open: no COMMIT after BEGIN, a cursor or statement that was not fully read or closed, or an exception path that skips the rollback.
• In rollback-journal mode, a long read in one connection blocks another connection's commit.
• A transaction that starts by reading (plain BEGIN, the default DEFERRED) later tries to write while another connection is already writing, so the upgrade fails at once.
• The database is on a network file system, where file locking is unreliable, or a tool such as a database browser keeps the file locked.

Diagnose it

Read-only These statements only read the schema (sqlite_schema and read-only PRAGMA queries) or your own data. They do not change data, settings or the database file, so they are safe to run first.

PRAGMA journal_mode;

PRAGMA busy_timeout;

PRAGMA database_list;

How to fix it

Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.

PRAGMA busy_timeout = 5000;  -- wait up to 5 seconds

BEGIN IMMEDIATE;
SELECT total FROM orders WHERE id = 1;
UPDATE orders SET total = total + 5 WHERE id = 1;
COMMIT;

PRAGMA journal_mode = WAL;

Examples

A second writer while another connection holds a write transaction

Session B received the error on its INSERT; its SELECT ran. With a busy timeout, B would wait until A commits or the timeout expires.

CREATE TABLE orders (id INTEGER PRIMARY KEY, total REAL);

-- Session A
BEGIN IMMEDIATE;
INSERT INTO orders (total) VALUES (20);

-- Session B: reading still works, writing does not
SELECT COUNT(*) FROM orders;
INSERT INTO orders (total) VALUES (30);

-- Session A
COMMIT;

database is locked

A reader blocked by an exclusive writer (rollback-journal mode)

Session B received the error on its SELECT. A writer also takes this exclusive lock while it commits, so a reader can briefly hit it in normal use. In WAL mode the same SELECT runs (we checked).

CREATE TABLE orders (id INTEGER PRIMARY KEY, total REAL);
INSERT INTO orders (total) VALUES (10);

-- Session A
BEGIN EXCLUSIVE;

-- Session B
SELECT COUNT(*) FROM orders;

-- Session A
COMMIT;

database is locked

An open read transaction blocks another connection's write

Session A received the error: in rollback-journal mode it cannot write the file while B holds a read lock. After B committed, the same INSERT succeeded. In WAL mode A's INSERT succeeds while B is reading.

CREATE TABLE orders (id INTEGER PRIMARY KEY, total REAL);
INSERT INTO orders (total) VALUES (10);

-- Session B: a read inside a transaction that is never committed
BEGIN;
SELECT COUNT(*) FROM orders;

-- Session A
INSERT INTO orders (total) VALUES (40);

-- Session B
COMMIT;

database is locked

WAL mode: a stale read transaction cannot write

Session B received the error at once, with extended code 517 (SQLITE_BUSY_SNAPSHOT) when read through the PHP SQLite3 class; PDO reports only 5. A busy timeout does not help here: roll back and retry the transaction.

PRAGMA journal_mode = WAL;
CREATE TABLE orders (id INTEGER PRIMARY KEY, total REAL);
INSERT INTO orders (total) VALUES (10);

-- Session B
BEGIN;
SELECT COUNT(*) FROM orders;

-- Session A: not blocked by B's read in WAL mode
INSERT INTO orders (total) VALUES (80);

-- Session B: its snapshot is now out of date
INSERT INTO orders (total) VALUES (90);
ROLLBACK;

database is locked

How to prevent it

Open a connection with a busy timeout of a few seconds, keep write transactions short, start them with BEGIN IMMEDIATE when they will write, and end every transaction on every code path. Use WAL mode for applications where reads and writes overlap, such as web applications and desktop apps with background sync.

Keep the database on a local disk, not a network share. If many processes write heavily at the same time, send the writes through one connection or a queue rather than letting them compete. Never delete the -journal or -wal file to "unlock" a database: they hold changes that are not in the main file yet, and removing them can lose committed data or corrupt the database.

Common questions

Learn more on CodeWithSQL

• SQL transactions and ACID explained
• Transactions and concurrency

Official documentation

• Write-Ahead Logging (WAL)
• Transactions: DEFERRED, IMMEDIATE and EXCLUSIVE
• File locking and concurrency in SQLite version 3
• sqlite3_busy_handler: when the busy handler is not called

Last technically reviewed 24 October 2026; examples and diagnostics run on SQLite 3.39.2 (PHP PDO_SQLITE) and the sqlite3 shell 3.50.6. Messages are the text the SQLite library itself returns (sqlite3_errmsg) for the versions shown.