docs(persistence): retire stale WAL v2 references — v3 shipped, v2 removed#372
Conversation
…moved docs/guides/persistence.md carried a "WAL v2 format" section and docs/comparison-valkey.md cited "Per-shard WAL v2 (src/persistence/wal.rs)" — that file and format were removed when the engine went WAL-v3-only (PRs #236/#238). Anyone evaluating Moon's durability story from the docs was reading a format that no longer exists. Both now describe WAL v3 (src/persistence/wal_v3/): segmented 16MB files with 64-byte headers, per-record LSNs (PITR/CDC foundation), checksummed records, lz4-compressed FPI, and the off-loop fsync agent. author: Tin Dang <tindang.ht97@gmail.com>
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
📝 WalkthroughWalkthroughPersistence documentation and changelog references are updated from WAL v2 to WAL v3, covering segmented files, LSN tracking, checksums, lz4 full-page images, corruption isolation, and off-loop fsync handling. ChangesWAL v3 documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guides/persistence.md`:
- Around line 47-48: Clarify the “Off-loop fsync” statement in the persistence
guide to specify that the sync agent performs fdatasync off the shard event
loop, while wait_durable(lsn, timeout) may still block it for checkpoint
ordering and shutdown. Replace the overly broad claim that the event loop never
blocks on durability waits with wording that preserves this distinction.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 422444b8-1d7d-4377-8c0b-841ad1a5dd88
📒 Files selected for processing (3)
CHANGELOG.mddocs/comparison-valkey.mddocs/guides/persistence.md
| - **Off-loop fsync** — a per-shard sync agent thread owns the fsync so the | ||
| shard event loop never blocks on durability waits |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify the off-loop fsync guarantee.
The sync agent moves fdatasync off the shard thread, but wait_durable(lsn, timeout) still blocks the shard thread for checkpoint ordering and shutdown. “Never blocks on durability waits” is therefore too broad.
Proposed wording
-- shard event loop never blocks on durability waits
+- regular fsync work runs off-loop; explicit durability waits remain for
+ checkpoint ordering and shutdown📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Off-loop fsync** — a per-shard sync agent thread owns the fsync so the | |
| shard event loop never blocks on durability waits | |
| - **Off-loop fsync** — a per-shard sync agent thread owns the fsync so the | |
| regular fsync work runs off-loop; explicit durability waits remain for | |
| checkpoint ordering and shutdown |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/persistence.md` around lines 47 - 48, Clarify the “Off-loop
fsync” statement in the persistence guide to specify that the sync agent
performs fdatasync off the shard event loop, while wait_durable(lsn, timeout)
may still block it for checkpoint ordering and shutdown. Replace the overly
broad claim that the event loop never blocks on durability waits with wording
that preserves this distinction.
2 participants
Found while answering "do the docs and defaults support long-term data storage?":
docs/guides/persistence.mdstill documented a WAL v2 format section anddocs/comparison-valkey.mdcitedsrc/persistence/wal.rs— both removed when the engine went WAL-v3-only (PRs #236/#238). Anyone evaluating Moon's durability story from the docs was reading a format that no longer exists. Both now describe WAL v3 (src/persistence/wal_v3/): segmented 16MB files, per-record LSNs, checksummed records, lz4 FPI, off-loop fsync agent. Docs-only change.Summary by CodeRabbit