bd backup

Back up and restore your beads database

Overview

Back up your beads database for off-machine recovery. Supports both JSONL exports (portable, git-friendly) and Dolt-native backups (preserves history, faster for large databases).

Syntax

bd backup [subcommand] [flags]

Backup Methods

JSONL Export (Default)

Without a subcommand, exports all tables to JSONL files in .beads/backup/:

bd backup
bd backup --force    # Export even if nothing changed

Exports:

• issues.jsonl - All issues
• events.jsonl - Issue events (incremental)
• comments.jsonl - Comments
• dependencies.jsonl - Dependency relationships
• labels.jsonl - Label associations
• config.jsonl - Configuration values
• state.json - Backup metadata

Dolt-Native Backup (Recommended)

For Dolt backends, use Dolt remotes for full history preservation:

# Setup backup destination
bd backup init <path>
bd backup init https://doltremoteapi.dolthub.com/user/repo

# Push to backup
bd backup sync

Advantages:

• Preserves full commit history
• Faster for large databases
• Native Dolt replication
• Branch and tag support

Subcommands

init

Set up a backup destination:

bd backup init <path>

Supports:

• Filesystem: file:///path/to/backup
• DoltHub: https://doltremoteapi.dolthub.com/user/repo
• SSH: ssh://user@host/path/to/repo

DoltHub Example:

export DOLT_REMOTE_USER=myusername
export DOLT_REMOTE_PASSWORD=my_token
bd backup init https://doltremoteapi.dolthub.com/myusername/myrepo

sync

Push to configured backup destination:

bd backup sync

Pushes current database state to the remote configured with bd backup init.

status

Show backup status (JSONL + Dolt):

bd backup status
bd backup status --json

Displays:

• Last JSONL backup timestamp
• JSONL backup counts
• Dolt backup configuration
• Database size
• Auto-backup settings

restore

Restore from JSONL backup files:

bd backup restore [path]

Restores database from JSONL files in .beads/backup/ or specified path.

Auto-Backup Configuration

Configure automatic backups via config.yaml:

backup:
  enabled: true              # Auto-backup on mutations (default: auto-detect)
  interval: 1h               # Backup frequency (default: 1h)
  git-push: true             # Push to git after backup (default: auto-detect)
  git-repo: origin           # Git remote name (default: origin)

Auto-detection:

• enabled: Defaults to true if git remote exists
• git-push: Defaults to true if git remote exists

Flags

Flag	Description
--force	Export even if nothing changed
--json	Output JSON format

Examples

Manual JSONL Backup

bd backup

Output:

Backup complete: 150 issues, 1234 events, 567 comments, 89 deps, 45 labels, 12 config

View Backup Status

bd backup status

Output:

JSONL Backup:
  Last backup: 2024-03-04T10:30:00Z (2 hours ago)
  Dolt commit: abc123def456
  Counts: 150 issues, 1234 events, 567 comments, 89 deps, 45 labels, 12 config

Config: enabled=true interval=1h git-push=true

Dolt Backup:
  Remote: backup
  URL: https://doltremoteapi.dolthub.com/user/repo
  Last push: 2024-03-04T10:30:00Z (2 hours ago)
  Status: ✓ in sync

Database Size:
  .beads/dolt/beads: 45.2 MB

Setup DoltHub Backup

# Configure credentials
export DOLT_REMOTE_USER=myusername
export DOLT_REMOTE_PASSWORD=my_token_from_dolthub

# Initialize backup remote
bd backup init https://doltremoteapi.dolthub.com/myusername/myrepo

# First backup
bd backup sync

# Verify
bd backup status

Setup Filesystem Backup

# Local directory
bd backup init file:///mnt/backup/beads

# Network share
bd backup init file:///Volumes/Backups/beads

# Push backup
bd backup sync

Restore from Backup

From JSONL:

# In place
bd backup restore

# From specific location
bd backup restore /path/to/backup

From Dolt remote:

# Initialize new repository
bd init

# Configure backup remote
bd dolt remote add backup https://doltremoteapi.dolthub.com/user/repo

# Pull from backup
bd dolt pull backup

Auto-Backup Configuration

Enable auto-backup:

bd config set backup.enabled true
bd config set backup.interval 30m

Disable git push:

bd config set backup.git-push false

Verify settings:

bd backup status

Force Backup (Testing)

bd backup --force

Exports even if no changes since last backup.

Backup Strategies

Local Development

JSONL backups are sufficient:

backup:
  enabled: true
  interval: 1h
  git-push: true

Team Collaboration

Use Dolt remote for shared backup:

# Each team member
bd backup init https://doltremoteapi.dolthub.com/team/project
bd backup sync  # After significant work

Production/Critical Data

Multiple backup methods:

# 1. JSONL for portability
bd backup

# 2. Dolt remote for history
bd backup sync

# 3. Git push for version control
git add .beads/backup/
git commit -m "Backup: 2024-03-04"
git push

Disaster Recovery

Regular offsite backups:

# Setup backup remote
bd backup init https://doltremoteapi.dolthub.com/user/backup

# Automated via cron/launchd
*/30 * * * * cd /path/to/repo && bd backup sync

JSONL Format

Backup files use newline-delimited JSON (JSONL):

{"id":"bd-1","title":"First issue","status":"open",...}
{"id":"bd-2","title":"Second issue","status":"closed",...}

Advantages:

• Human-readable
• Git-friendly (line-based diffs)
• Portable across backends
• Easy to inspect/edit

Incremental Backups

Events are backed up incrementally:

• First backup: Exports all events
• Subsequent backups: Only new events since last backup
• High-water mark tracked in state.json

Other tables are fully exported each time (relatively small).

Troubleshooting

”No changes to export”

Cause: Database unchanged since last backup

Solution: Use --force flag to export anyway:

bd backup --force

“Remote not configured”

Cause: No backup remote set up

Solution: Initialize backup destination:

bd backup init <url>

“Authentication failed” (DoltHub)

Cause: Missing or invalid credentials

Solution: Set environment variables:

export DOLT_REMOTE_USER=myusername
export DOLT_REMOTE_PASSWORD=my_token
bd backup sync

“Restore failed: corrupt JSONL”

Cause: JSONL file contains invalid JSON

Solution:

• Check file for syntax errors
• Use last known good backup
• Or restore from Dolt remote instead

”Backup directory not found”

Cause: .beads/backup/ doesn’t exist

Solution: Run first backup to create directory:

bd backup

Related Commands

• bd dolt - Direct Dolt operations (push, pull)
• bd compact - Reduce database size before backup
• bd doctor - Verify backup integrity

See Also

• Backup and Recovery Guide
• Dolt Backend Setup
• Federation Guide