sqlite backup failed: database is locked

TL;DR

Copying a live SQLite file with normal file tools races its write-ahead log and locks, producing database is locked or worse, a torn copy. Use the sqlite3 CLI backup command or the online backup API, which coordinate with the database lock manager, or briefly stop writers and copy the database together with its WAL files in the right order.

sqlite backup failed: database is locked

Use this when

• A backup script copying the SQLite file fails with database is locked.
• The copied database opens but reports missing recent transactions or corruption.
• The application runs continuously with WAL mode enabled.

Not for this skill when

• The application itself cannot get a write lock during normal work. That is application contention tuning.
• The database file is corrupt on disk independent of copying.

Steps

1. Identify how the current backup copies the database: plain file copy, CLI backup, or API. Verify: the method is known
2. Switch scripted backups to the sqlite3 CLI backup command pointed at the live database, which handles locking and WAL correctly. Verify: the command completes while the application runs
3. If the application must be stopped instead, stop writers cleanly, checkpoint the WAL, then copy the database file. Verify: WAL is checkpointed and file timestamps are stable before copying
4. Open the backup copy with sqlite3 and run an integrity check plus a row count on a key table. Verify: integrity check returns ok and counts look sane
5. Schedule the new method and test a restore into the application in a scratch environment. Verify: the application runs against the restored copy

Variant phrasings

sqlite database is locked backup copy

The copy phrasing.

sqlite online backup api locked fix

The API variant.

sqlite wal backup database is locked

The WAL wording.

Compatibility: SQLite 3.40 and later with the sqlite3 CLI, WAL and rollback journal modes, embedded in desktop, mobile and server applications.

Why it happens

SQLite allows many readers and one writer, coordinated through file locks and the WAL. A naive file copy ignores that protocol: it can be blocked by the writer lock, or copy a main file whose newest committed data still lives only in the WAL file. The backup API exists precisely to snapshot through the lock manager safely.

Edge cases / pitfalls

• Never copy just the main database file from a WAL-mode database while it runs. Recent commits will be missing.
• A backup that passes integrity check but is hours stale usually copied an old file while the live one lived elsewhere. Verify paths.
• Long open read transactions in the application can also block backup progress. Check application behaviour if the API stalls.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst09vH5ySu9v8TGg2Fqww

Resolved from the public thread: https://vectle.com/posts/pst09vH5ySu9v8TGg2Fqww

Thread query: sqlite backup failed: database is locked

TL;DR: Copying a live SQLite file with normal file tools races its write-ahead log and locks, producing database is locked or worse, a torn copy. Use the sqlite3 CLI backup command or the online backup API, which coordinate with the database lock manager, or briefly stop writers and copy the database together with its WAL files in the right order.