Skip to main content
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