Dolt is now the default (and only) storage backend for bd init. Add a --backend flag that accepts "dolt" (default) or "sqlite" (prints a deprecation notice with migration instructions and exits). Unknown backends produce a clear error. Update QUICKSTART.md and DOLT-BACKEND.md to reflect that SQLite is no longer supported and Dolt is the sole backend. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
7.9 KiB
Dolt Storage Backend
Beads uses Dolt as its default storage backend. Dolt provides Git-like version control for your database, enabling advanced workflows like branch-based development, time travel queries, and distributed sync.
Note: Dolt is the only supported backend. The legacy SQLite backend has been removed. To migrate from SQLite, see Migration from SQLite below.
Overview
| Feature | Dolt |
|---|---|
| Storage | Directory-based |
| Version control | Native (cell-level) |
| Branching | Yes |
| Time travel | Yes |
| Merge conflicts | SQL-based (cell-level merge) |
| Multi-user concurrent | Server mode |
| Sync | Native push/pull to Dolt remotes |
Quick Start
1. Install Dolt
# macOS
brew install dolt
# Linux
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
# Verify installation
dolt version
2. Initialize
# New project (Dolt is the default backend)
bd init
# Or convert existing SQLite database (legacy installations)
bd migrate --to-dolt
3. Configure Sync Mode
# .beads/config.yaml
sync:
mode: dolt-native # Default: use Dolt remotes
Server Mode (Recommended)
Server mode provides fast operations by running a persistent dolt sql-server that handles connections.
Server Mode is Enabled by Default
When Dolt backend is detected, server mode is automatically enabled. The server auto-starts if not already running.
Disable Server Mode (Not Recommended)
# Via environment variable
export BEADS_DOLT_SERVER_MODE=0
# Or in config.yaml
dolt:
server_mode: false
Server Configuration
| Environment Variable | Default | Description |
|---|---|---|
BEADS_DOLT_SERVER_MODE |
1 |
Enable/disable server mode (1/0) |
BEADS_DOLT_SERVER_HOST |
127.0.0.1 |
Server bind address |
BEADS_DOLT_SERVER_PORT |
3306 |
Server port (MySQL protocol) |
BEADS_DOLT_SERVER_USER |
root |
MySQL username |
BEADS_DOLT_SERVER_PASS |
(empty) | MySQL password |
Server Lifecycle
# Check server status
bd doctor
# Server auto-starts when needed
# PID stored in: .beads/dolt/sql-server.pid
# Logs written to: .beads/dolt/sql-server.log
# Manual stop (rarely needed)
kill $(cat .beads/dolt/sql-server.pid)
Sync Modes
Dolt supports multiple sync strategies:
dolt-native (Default)
sync:
mode: dolt-native
- Uses Dolt remotes (DoltHub, S3, GCS, etc.)
- Native database-level sync
- Supports branching and merging
belt-and-suspenders
sync:
mode: belt-and-suspenders
- Uses BOTH Dolt remotes AND JSONL export
- Maximum redundancy
- Useful for migration periods
git-portable (Legacy)
sync:
mode: git-portable
- Legacy JSONL-based sync for backward compatibility
- Dolt provides local version history only
Dolt Remotes
Configure a Remote
Use bd dolt remote add to configure remotes. This ensures the running Dolt SQL
server sees the remote immediately. Remotes added via the dolt CLI directly
are written to the filesystem but are not visible to the server until restart.
# DoltHub (public or private)
bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads
# S3
bd dolt remote add origin aws://[bucket]/path/to/repo
# GCS
bd dolt remote add origin gs://[bucket]/path/to/repo
# Git SSH (GitHub, GitLab, etc.)
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
# Local file system
bd dolt remote add origin file:///path/to/remote
Push/Pull
bd dolt push
bd dolt pull
For SSH remotes, bd dolt push and bd dolt pull automatically use the dolt
CLI instead of the SQL server to avoid MySQL connection timeouts during transfer.
bd dolt remote add registers the remote on both the SQL server and the
filesystem (CLI) config. This ensures dolt push/dolt pull via CLI can find
the remote. If either surface already has a remote with that name, you'll be
prompted before overwriting.
Also supports sharing a Git repo: Dolt stores data under
refs/dolt/data, separate from standard Git refs (refs/heads/,refs/tags/). You can safely point agit+ssh://remote at the same repository as your project source code. See Dolt Git Remotes for details.
List/Remove Remotes
bd dolt remote list # Shows remotes from both SQL server and CLI, flags discrepancies
bd dolt remote remove origin # Removes from both surfaces
Use bd doctor --fix to resolve any discrepancies between SQL and CLI remote configs.
Migration from SQLite (Legacy)
If upgrading from an older version that used SQLite:
Option 1: In-Place Migration (Recommended)
# Preview the migration
bd migrate --to-dolt --dry-run
# Run the migration
bd migrate --to-dolt
# Optionally clean up SQLite files
bd migrate --to-dolt --cleanup
Option 2: Fresh Start
# Export current state
bd export -o backup.jsonl
# Archive existing beads
mv .beads .beads-sqlite-backup
# Initialize fresh
bd init
# Import from backup
bd import -i backup.jsonl
Troubleshooting
Already Committed dolt/ to Git
If you committed .beads/dolt/ before this fix:
- Update gitignore:
bd doctor --fix - Remove from git tracking:
git rm --cached -r .beads/dolt/ .beads/dolt-access.lock - Commit the removal:
git commit -m "fix: remove accidentally committed dolt data" - To purge from history (optional): use BFG Repo-Cleaner or
git filter-repo
Server Won't Start
# Check if port is in use
lsof -i :3306
# Check server logs
cat .beads/dolt/sql-server.log
# Verify dolt installation
dolt version
# Try manual start
cd .beads/dolt && dolt sql-server --host 127.0.0.1 --port 3306
Connection Issues
# Test connection
mysql -h 127.0.0.1 -P 3306 -u root beads
# Check server is running
bd doctor
# Force restart
kill $(cat .beads/dolt/sql-server.pid) 2>/dev/null
bd list # Triggers auto-start
Performance Issues
- Ensure server mode is enabled (default)
- Check server logs for errors
- Run
bd doctorfor diagnostics - Consider
dolt gcfor database maintenance:cd .beads/dolt && dolt gc
Advanced Usage
Branching
cd .beads/dolt
# Create feature branch
dolt checkout -b feature/experiment
# Make changes via bd commands
bd create "experimental issue"
# Merge back
dolt checkout main
dolt merge feature/experiment
Time Travel
cd .beads/dolt
# List commits
dolt log --oneline
# Query at specific commit
dolt sql -q "SELECT * FROM issues AS OF 'abc123'"
# Checkout historical state
dolt checkout abc123
Diff and Blame
cd .beads/dolt
# See changes since last commit
dolt diff
# Diff between commits
dolt diff HEAD~5 HEAD -- issues
# Blame (who changed what)
dolt blame issues
Configuration Reference
Full Config Example
# .beads/config.yaml
backend: dolt
sync:
mode: dolt-native
auto_dolt_commit: true # Auto-commit after sync (default: true)
auto_dolt_push: false # Auto-push after sync (default: false)
dolt:
server_mode: true # Use sql-server (default: true)
server_host: "127.0.0.1"
server_port: 3306
server_user: "root"
server_pass: ""
# Lock settings
lock_retries: 30
lock_retry_delay: "100ms"
idle_timeout: "30s"
federation:
remote: "dolthub://myorg/beads"
sovereignty: "T3" # T1-T4
Environment Variables
| Variable | Description |
|---|---|
BEADS_DOLT_SERVER_MODE |
Server mode: 1 or 0 |
BEADS_DOLT_SERVER_HOST |
Server host |
BEADS_DOLT_SERVER_PORT |
Server port |
BEADS_DOLT_SERVER_USER |
Server user |
BEADS_DOLT_SERVER_PASS |
Server password |
See Also
- Troubleshooting - General troubleshooting
- Dolt Documentation - Official Dolt docs