SQLite WAL and SHM files: what to keep, what to copy

A SQLite database in WAL mode can have two companions: database.db-wal and database.db-shm. They are part of SQLite’s working state, not unrelated clutter.

What each file does

• The main database stores database pages.
• The -wal file is the write-ahead log. Committed changes can remain here until a checkpoint transfers them into the main database.
• The -shm file supports coordination and the WAL index used by connections sharing the database.

These files can appear and disappear as connections open, checkpoint and close. Do not delete them to “clean up” a database that may still be in use. SQLite documents the details in its WAL reference.

Why copying only database.db can lose recent changes

If a committed transaction is still in the WAL, a copy of the main file alone can miss it. Separately copying all three files while writes continue is not a reliable snapshot either: they may be copied at different points in time.

Make a SQLite-aware snapshot

Prefer the owning application’s backup function. Alternatively, the SQLite shell’s backup command creates a database snapshot through SQLite’s backup API. Choose a new destination filename; do not overwrite a backup you need.

sqlite3 -readonly "/path/to/database.db"
.backup '/path/to/new-snapshot.sqlite'
.quit

The source connection is read-only; the backup command writes the destination. A busy database or insufficient file permissions can still prevent the operation. The online backup documentation explains how SQLite coordinates the copy.

Inspect the main file with its companions in place

Open the main database in Petti, leaving its sidecars in the same directory. Petti starts read-only. Read-only WAL access can still require usable sidecar files or directory permissions; it is not a way around every access restriction.

If recent changes do not appear, refresh your view or make a fresh snapshot. Do not force an immutable connection for a file another application can change. A large WAL also does not mean the grid should load everything: large-database browsing and checkpoint management are separate concerns.