SQLite WAL Size: Checkpoint Progress Is Not File Shrinkage
A successful SQLite checkpoint can leave a large WAL file. Read the returned page counts and verify file size before choosing a stronger maintenance mode.
DM
Suppose your application’s maintenance task reports a successful SQLite checkpoint, but the app.db-wal file still looks enormous. You check the task again. It says success again. Before running something stronger, separate two questions: did SQLite move the available changes back into the database, and did it return disk space?
A completed checkpoint does not necessarily shrink a SQLite WAL file. Check the checkpoint’s returned counts, the lifetime of active transactions and the actual file size separately. SQLite can keep the file allocated for reuse. A large file alone doesn’t tell you which of those steps needs attention. The SQLite file-format reference describes that reuse.
This is a hypothetical application on a self-managed server. The SQL and output below are illustrative, not results from an executed workload. Before maintenance, have a recoverable backup. Don’t delete or rename the WAL to make the disk chart look better: SQLite’s corruption guidance explains that journal files may be necessary for recovery.
Make sure you’re looking at the application’s database
Start with the database path in the running application’s configuration. Check its mount or volume, especially if the application is containerized. A similarly named database on your laptop is an excellent place to get a convincing answer to the wrong question.
Run these queries through the application’s database connection or an authorized diagnostic connection to the verified existing file. They query the runtime and journal mode; they do not switch the database into WAL mode:
SELECT sqlite_version();
PRAGMA main.journal_mode;Record the application’s loaded SQLite version, not only the command-line tool’s version. Review the vendor’s WAL-reset bug notice: it identifies a rare concurrent write/checkpoint corruption issue fixed in 3.51.3 and later, with fixes also in 3.44.6 and 3.50.7. Verify your package’s maintenance status before experimenting; a large WAL is not evidence of that bug.
This guide assumes WAL mode on a supported local filesystem. SQLite’s WAL documentation requires the processes using that database to be on the same host; it is not a recipe for sharing a WAL database across machines over a network filesystem.
Read the result, not just the word success
An authorized checkpoint can help establish progress, but it is maintenance that can write the database and perform I/O. Rehearse on a disposable database and agree on production impact before invoking it. The example chooses PASSIVE, which attempts available work without waiting for readers or writers to finish. It may leave work incomplete, as the checkpoint API reference explains.
PRAGMA main.wal_checkpoint(PASSIVE);The PRAGMA reference defines three returned integers: a busy indicator, the number of pages in the WAL, and the number checkpointed. Keep all three, the mode and any error. Here are synthetic rows in that column order, not measurements:
| Illustrative row | What to conclude | What it does not establish |
|---|---|---|
0, 1200, 1200 | The reported WAL pages are checkpointed at this observation. | The file shrank or the filesystem regained space. |
0, 1200, 600 | Reported checkpoint progress is incomplete. | A zero first column means every page was processed. |
0, -1, -1 | There is no applicable WAL in this connection’s reported state. | The application’s intended file was inspected correctly. |
Treat those as observations at a moment, not a permanent state. New writes can arrive afterward. For the hypothetical application, save the returned row beside the exact database identity and observation time. Don’t turn the difference between page counts into a recovered-byte estimate.
SQLite’s WAL lifecycle description explains that normal checkpointing generally recycles the WAL rather than truncating it. That means the first row and a still-large file can both be expected. Compare subsequent growth and real filesystem headroom before declaring the checkpoint broken.
If progress is incomplete, inspect transaction ownership
A reader in WAL mode sees a snapshot that stays fixed for its transaction, according to SQLite’s isolation documentation. That gives the checkpoint an important boundary: it cannot replace data a current reader still needs. Investigate transaction lifetimes alongside checkpoint activity, rather than assuming every growing WAL means too many writes.
In the hypothetical app, examine the code path that begins a read and the path that releases its statements and transaction. SQLite’s transaction documentation distinguishes automatically started transactions from explicit ones. An explicit transaction generally lasts until COMMIT or ROLLBACK; unfinished statements can also affect implicit transaction lifetime. Use your driver’s documented resource handling.
Choose one application operation to investigate, and record when its transaction starts and ends. If it intentionally needs a stable snapshot, preserve that requirement. If unrelated slow work sits inside the transaction, consider moving it after the transaction finishes, then check that the application still returns the intended data. That’s an application design decision, not a universal instruction to close every connection.
Reclaim space only when that is the actual goal
The checkpoint modes reference gives TRUNCATE stronger behavior: it follows RESTART’s waiting requirements and additionally reduces the WAL to zero bytes on successful completion. It can contend with application work and can return busy. Selecting that mode needs an appropriate maintenance plan; calling it repeatedly is not a fix for a transaction that never ends.
For this investigation, keep three separate entries in your operating notes: checkpoint progress, WAL file length, and free space on the backing filesystem. Add the application errors and response behavior during the same interval. If storage figures still don’t explain the failure, use the Linux filesystem and inode checks on the actual mount.
A checkpoint also doesn’t create an independent recovery copy. SQLite’s Online Backup API provides a supported way to copy a live database into another database file. Whatever backup method you choose, verify recovery separately from the maintenance result.
On a Krova Cube, you control the application, guest storage and SQLite lifecycle. You also own the database’s transaction handling and recovery plan. Finish with a result you can explain: the right file, the loaded runtime, the complete checkpoint response, storage before and after, and a representative application check. “The command succeeded” is only one line in that record.
Creation context: this AI-assisted guide uses the linked primary documentation. The scenario and result rows are hypothetical. No checkpoint, database recovery or workload benchmark was performed for this article; the cover is a generated conceptual illustration.
Give your database rehearsal a separate Cube
Explore a self-managed Linux microVM for checking your application’s SQLite lifecycle with disposable data before planning production maintenance.




