Skip to content

WAL whose entries are all checkpointed survives checkpoint() until the next write #457

Closed

Description

@adityamukho

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

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

  1. added this to the v3.0.0 milestone on Oct 6, 2026
  2. added a commit that references this issue on Oct 10, 2026
  3. adityamukho commented on Oct 10, 2026

    @adityamukho
    CollaboratorAuthor

    Fixed on v3 by #525 (edd1fe7); ships in v3.0.0.

  4. added 2 commits that reference this issue on Oct 11, 2026
  5. adityamukho commented on Oct 11, 2026

    @adityamukho
    CollaboratorAuthor

    Backported to v2.x in #540 (merged to main, 99410b1); ships in the next v2.x patch release.

  6. added a commit that references this issue on Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    stabilityStability/panic issue

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions