beads/docs/recovery/database-corruption.md
Chris Sells a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00

979 B

title description
Database Corruption Recover from Dolt database corruption

This runbook helps you recover from database corruption in Beads.

Symptoms

  • Error messages during bd commands
  • "database is locked" errors that persist
  • Missing issues that should exist
  • Inconsistent database state

Diagnosis

# Check database integrity
bd doctor

# Check Dolt server health
bd dolt show

Solution

Step 1: Stop the Dolt server

bd dolt stop

Step 2: Back up current state

cp -r .beads .beads.backup

Step 3: Preview what doctor would fix

bd doctor --dry-run

Step 4: Rebuild database

bd doctor --fix

Step 5: Verify recovery

bd doctor
bd list

Step 6: Restart the Dolt server

dolt sql-server

Prevention

  • Let the Dolt server handle synchronization
  • Use bd dolt stop before system shutdown
  • Run bd doctor periodically to catch issues early