Skip to main content

Overview

Configure and manage Dolt database settings, server lifecycle, and version control operations. Beads uses a dolt sql-server that auto-starts transparently when needed.

Syntax

bd dolt <subcommand> [flags]

Subcommands

Server Lifecycle

start

Start the Dolt SQL server for this project:
bd dolt start
The server runs in the background on a per-project port derived from the project path. PID and logs are stored in .beads/.

stop

Stop the Dolt SQL server:
bd dolt stop
bd dolt stop --force  # Force stop even under Gas Town daemon

status

Show Dolt server status:
bd dolt status
bd dolt status --json

Configuration

show

Show current Dolt configuration with connection test:
bd dolt show
Output:
Dolt Configuration
==================
  Database: beads
  Host:     127.0.0.1
  Port:     3307
  User:     root

  ✓ Server connection OK

Remotes:
  origin         https://doltremoteapi.dolthub.com/user/repo

Config sources (priority order):
  1. Environment variables (BEADS_DOLT_*)
  2. metadata.json (local, gitignored)
  3. config.yaml (team defaults)

set

Set a configuration value:
bd dolt set <key> <value> [--update-config]
Configuration Keys:
KeyDescription
databaseDatabase name (default: issue prefix or “beads”)
hostServer host (default: 127.0.0.1)
portServer port (auto-detected; override if needed)
userMySQL user (default: root)
data-dirCustom dolt data directory (absolute path)
Examples:
bd dolt set database myproject
bd dolt set host 192.168.1.100 --update-config
bd dolt set port 3307
bd dolt set data-dir /home/user/.beads-dolt/myproject
Use --update-config to also write to config.yaml for team-wide defaults.

test

Test connection to Dolt server:
bd dolt test
Verifies:
  1. Server is reachable at configured host:port
  2. Connection can be established
  3. Remote connectivity (for configured remotes)

Version Control

commit

Create a Dolt commit from pending changes:
bd dolt commit                      # Auto-generated message
bd dolt commit -m "Batch update"    # Custom message
Useful in batch mode when changes accumulate across multiple bd commands. Also needed before push operations that require a clean working set.

push

Push commits to Dolt remote:
bd dolt push
bd dolt push --force  # Overwrite remote changes
For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment variables.

pull

Pull commits from Dolt remote:
bd dolt pull
Merges remote changes into local database.

Remote Management

remote add

Add a Dolt remote (both SQL server and CLI):
bd dolt remote add <name> <url>
Examples:
# DoltHub (recommended)
bd dolt remote add origin https://doltremoteapi.dolthub.com/user/repo

# Filesystem
bd dolt remote add backup file:///mnt/backup/beads

# SSH
bd dolt remote add origin git@github.com:user/repo.git
For Hosted Dolt:
export DOLT_REMOTE_USER=your-username
export DOLT_REMOTE_PASSWORD=your-token
bd dolt remote add origin https://doltremoteapi.dolthub.com/user/repo

remote list

List configured Dolt remotes (SQL server + CLI):
bd dolt remote list
bd dolt remote list --json
Shows remotes from both surfaces and detects discrepancies.

remote remove

Remove a Dolt remote (both SQL server and CLI):
bd dolt remote remove <name>
bd dolt remote remove <name> --force  # Force remove despite conflicts

Maintenance

clean-databases

Drop stale test/polecat databases from Dolt server:
bd dolt clean-databases
bd dolt clean-databases --dry-run
Removes leftover databases from interrupted tests (prefixes: testdb_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t*).

killall

Kill all orphan Dolt server processes:
bd dolt killall
Finds and terminates dolt sql-server processes not tracked by the canonical PID file.

Environment Variables

VariableDescription
BEADS_DOLT_DATABASEOverride database name
BEADS_DOLT_HOSTOverride server host
BEADS_DOLT_PORTOverride server port
BEADS_DOLT_USEROverride MySQL user
BEADS_DOLT_PASSWORDMySQL password (if needed)
BEADS_DOLT_DATA_DIROverride data directory
DOLT_REMOTE_USERRemote authentication username
DOLT_REMOTE_PASSWORDRemote authentication token

Configuration Precedence

Settings are resolved in order:
  1. Environment variables (BEADS_DOLT_*) - highest priority
  2. metadata.json - local overrides (gitignored)
  3. config.yaml - team defaults (committed)

Dolt Sync Workflows

Team Collaboration

Setup (once per developer):
# Configure remote
bd dolt remote add origin https://doltremoteapi.dolthub.com/team/project

# Set credentials
export DOLT_REMOTE_USER=your-username
export DOLT_REMOTE_PASSWORD=your-token
Daily workflow:
# Start day: pull latest
bd dolt pull

# Work on issues
bd update bd-42 --status in_progress

# Push changes
bd dolt push

# End day: ensure pushed
bd dolt status

Backup and Recovery

Setup backup remote:
bd dolt remote add backup https://doltremoteapi.dolthub.com/user/backup
Regular backups:
# Push to backup remote
bd dolt push backup

# Verify backup
bd dolt remote list
Restore from backup:
# Initialize new repository
bd init

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

# Pull from backup
bd dolt pull backup

Multi-Machine Sync

Machine A:
# Make changes
bd create "New feature" -t feature -p 1

# Push to remote
bd dolt push
Machine B:
# Pull changes
bd dolt pull

# Verify sync
bd list --json

Examples

View Current Configuration

bd dolt show

Change Database Name

bd dolt set database myproject
bd dolt set database myproject --update-config  # Save to config.yaml

Configure Remote Access

# For remote server
bd dolt set host 192.168.1.100 --update-config
bd dolt set port 3307

# Test connectivity
bd dolt test

Setup Custom Data Directory

# Move database to external drive
bd dolt set data-dir /mnt/external/beads-data

# Verify
bd dolt show

Batch Commit Workflow

# Configure batch mode
bd config set dolt.auto-commit batch

# Make multiple changes
bd create "Task 1" -t task
bd create "Task 2" -t task
bd update bd-42 --status closed

# Commit all at once
bd dolt commit

# Push
bd dolt push

Setup DoltHub Remote

# Configure credentials
export DOLT_REMOTE_USER=myusername
export DOLT_REMOTE_PASSWORD=my_token_abc123

# Add remote
bd dolt remote add origin https://doltremoteapi.dolthub.com/myusername/myrepo

# Push initial state
bd dolt push

# Verify
bd dolt remote list

Troubleshoot Connection Issues

# Check server status
bd dolt status

# Test connection
bd dolt test

# Restart server if needed
bd dolt stop
bd dolt start

# Verify
bd dolt status

Troubleshooting

Server Connection Failed

Cause: Server not running or wrong port Solution:
bd dolt status         # Check if running
bd dolt start          # Start if stopped
bd dolt test           # Test connection

Remote Not Found

Cause: Remote registered in CLI but not SQL server Solution:
bd dolt remote list    # Check both surfaces
bd dolt remote add origin <url>  # Re-register

Push Failed: Uncommitted Changes

Cause: Dolt requires clean working set Solution:
bd dolt commit         # Commit pending changes
bd dolt push           # Retry push

Data Directory Not Found

Cause: Custom data-dir path doesn’t exist Solution:
mkdir -p /path/to/data-dir
bd dolt set data-dir /path/to/data-dir

Orphan Server Processes

Cause: Server crashed or PID file lost Solution:
bd dolt killall        # Kill orphan processes
bd dolt start          # Start fresh
  • bd init - Initialize with Dolt backend
  • bd backup - Backup operations (alternative to remotes)
  • bd doctor - Health checks including Dolt connectivity
  • bd compact - Includes Dolt garbage collection

See Also

Build docs developers (and LLMs) love