beads/website/docs/recovery/database-corruption.md
maphew 39e2b40109 docs: reconcile bd doctor --fix contradiction between architecture and recovery pages
Fix #2084: Architecture page said 'Never Use bd doctor --fix' while
recovery pages recommended it as a standard step. Reconciled by:

- Architecture: Downgrade from 'danger/never' to 'warning/use with care',
  add backup + dry-run precautions, explain the actual risk (circular dep
  false positives)
- Recovery pages: Add backup and --dry-run steps before --fix, creating a
  consistent decision tree across all docs
- Also fix stale references in recovery pages: SQLite → Dolt terminology,
  bd sync → bd dolt push/pull, bd dolt start → dolt sql-server

Amp-Thread-ID: https://ampcode.com/threads/T-019ca749-d4f2-7289-b085-52e17436e950
Co-authored-by: Amp <amp@ampcode.com>
2026-02-28 19:58:29 -07:00

1 KiB

sidebar_position title description
2 Database Corruption Recover from Dolt database corruption

Database Corruption Recovery

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