Repository navigation
docs: durability, recovery and operations guide (#398) - #536
Merged
Merged
Conversation
docs/DURABILITY.md covers what survives a process crash and a power loss under SyncMode::Full and Normal, recovery on open and its cost, failures while running (WAL-007, STG-046), supported filesystems and containers, backups (offline copy, volume snapshot, fact_log into LogWriter from the running process) and restores, verify() and rebuild_indexes(), upgrading from v2.x and rolling back, a retry/reopen/restore table for the storage errors, and known limitations. Linked from the README; published on the docs site as a snapshot page. A log-writer test runs the documented online backup while another thread writes past the automatic checkpoint threshold. Writing it found #535 (a .wal from a later checkpoint is replayed onto an older .graph without an error); the restore steps remove any .wal first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/DURABILITY.mdfor issue #398, for teams running Minigraf where data loss matters:SyncMode::FullandSyncMode::Normal, and what durability assumes about storage. Also coversBrowserDband WASI.WAL-007,STG-046), including an automatic checkpoint that fails after its transaction is already committed.fact_log→LogWriterfrom the running process. Restore steps.verify()/rebuild_indexes(), upgrading from v2.x and rolling back, and upgrades within v3.x (STG-034).The guide is linked from the README, and ROADMAP, CHANGELOG and TEST_COVERAGE are updated. The docs site publishes it as a snapshot page (
since = "v3.0.0") in a companion minigraf-docs PR. That PR must merge after this one because the site readsorigin/v3.Found while writing it: #535. Restoring an older
.graphnext to a newer.walopens without an error and replays the WAL on top, which leaves a gap in the history. The restore steps remove any.walfirst, and the known limitations list #535.Test:
online_backup_while_writes_continueintests/log_writer_test.rsruns the documented online backup. It copies a live read-write handle that has an uncheckpointed transaction while another thread writes past the automatic checkpoint threshold. It checks that the backup verifies, holds exactly what the log returned and has the expected counter, and that every concurrent write reaches the source file after the log is dropped.Full suite: 1418 passed, 0 failed, 10 ignored.
cargo clippy --all-features -D warningsandcargo fmt --checkare clean.#398 stays open until v3.0.0 ships (durability label).
🤖 Generated with Claude Code
https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h