Repository navigation
docs: durability, recovery and operations guide #398
Description
Problem
A team that puts Minigraf in a high-stakes system has no single page that answers:
- What survives a process crash, and what survives a power loss? The answer differs for
SyncMode::FullandSyncMode::Normal, and depends on when the last checkpoint ran. - What happens on open after a crash: WAL replay, index rebuild (bug: after a kill during an active run the EAVT index silently loses most entities' entries while AEVT stays intact — entity-bound lookups return [] and no rebuild path exists #370), and how long each takes as the graph grows.
- Which filesystems and setups are supported: local disk, NFS, containers, PID namespaces (FileLock refuses stale lock under PID namespaces (Kubernetes): every container is PID 1 #317), Windows locking.
- How to take a safe backup of a live database. Is copying the file safe after
checkpoint()? What about the.walsidecar? - How to check a file for damage and repair it (Add index integrity check (verify) and public rebuild-indexes-from-fact-pages #373).
- How to upgrade across a format change (v2 → v3), and how to roll back.
- Which errors mean "retry", which mean "reopen", and which mean "restore from backup".
The facts are spread across the README, the wiki, ERROR_REFERENCE.md and closed issues.
Ask
Add docs/DURABILITY.md (and a wiki page) covering the points above. Include a short "known limitations" section that lists the open data-integrity issues and their workarounds. Link it from the README.
Activity
Merge pull request #536 from project-minigraf/docs/398-durability-guide
adityamukho commentedon Oct 14, 2026
Done on
v3in d932196:docs/DURABILITY.md. Closed under the close-on-merge rule forv3(#585).