Repository navigation
Description
Summary
If a database is opened next to a WAL whose entries are all already in the file, checkpoint() does nothing and leaves the WAL in place. The WAL is removed only after a later write gets checkpointed. The data is correct the whole time: replay skips entries with tx_count <= last_checkpointed_tx_count, and #447 keeps the counter from rewinding. But a sidecar file that holds nothing still sits next to the database, and an explicit checkpoint() does not remove it.
This was found while building the golden-file corpus (#391). The fixtures tests/golden/v7_stale_wal.* and tests/golden/v8_stale_wal.* have this shape. Their manifests carry "stale_wal": true, so the harness does not require the WAL to be gone after a checkpoint.
How the WAL gets into this state
- A crash between a checkpoint's commit and its WAL delete (the Transaction counter rewinds after reopening next to an already-checkpointed WAL #447 window).
- A failed WAL delete (WAL-006).
- On v2.x and on
v3at23aa57c: closing a handle opened withwal_checkpoint_threshold(usize::MAX).Inner::dropskips the checkpoint, butPersistentFactStorage::dropstill saves dirty facts, so the facts reach the file and the WAL stays.
Cause
do_checkpoint (src/db.rs) returns early when wal_entry_count == 0 && !pfs.is_dirty(). Replay counts only the entries it applies. A WAL whose entries were all checkpointed already therefore gives wal_entry_count == 0, and the early return also skips deleting the WAL.
Behaviour on each branch
- v2.x (
main): the WAL stays. A later write appends to it, and the next checkpoint deletes it. v3: the same. For a v1 WAL next to a migrated v7 file, the WAL keeps being read as base generation 1. That still satisfies the v8 spec rule ("a v1 WAL can only sit next to a migrated file whose next checkpoint has not completed") only because no checkpoint with data has completed yet.
Proposal (v3)
When the early return fires and a WAL file exists, delete it and sync the parent directory, as the normal checkpoint path does. Every entry in it is already at or below the committed last_checkpointed_tx_count, so deleting it loses nothing. Then remove the stale_wal exemption from tests/golden_corpus_test.rs. The committed golden files stay as they are, and their manifests keep the flag as a description of the shape.
Whether to backport to v2.x: this is not a data-integrity bug, so under the support policy it probably stays v3-only.
Not affected
Query results, tx_count and :as-of history are all correct before and after the WAL is finally removed. The golden tests check this through open, checkpoint, reopen, and a write followed by a reopen.
Activity
Merge pull request #525 from project-minigraf/fix/457-stale-wal-check…
adityamukho commentedon Oct 10, 2026
Fixed on v3 by #525 (edd1fe7); ships in v3.0.0.
Merge pull request #540 from project-minigraf/fix/457-476-v2-backport
Merge pull request #541 from project-minigraf/docs/457-476-backport-note
adityamukho commentedon Oct 11, 2026
Backported to v2.x in #540 (merged to
main, 99410b1); ships in the next v2.x patch release.release: v2.0.5