bd dolt - Beads

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:

Key	Description
`database`	Database name (default: issue prefix or “beads”)
`host`	Server host (default: 127.0.0.1)
`port`	Server port (auto-detected; override if needed)
`user`	MySQL user (default: root)
`data-dir`	Custom 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:

Server is reachable at configured host:port
Connection can be established
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 [email protected]: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

Variable	Description
`BEADS_DOLT_DATABASE`	Override database name
`BEADS_DOLT_HOST`	Override server host
`BEADS_DOLT_PORT`	Override server port
`BEADS_DOLT_USER`	Override MySQL user
`BEADS_DOLT_PASSWORD`	MySQL password (if needed)
`BEADS_DOLT_DATA_DIR`	Override data directory
`DOLT_REMOTE_USER`	Remote authentication username
`DOLT_REMOTE_PASSWORD`	Remote authentication token

Configuration Precedence

Settings are resolved in order:

Environment variables (BEADS_DOLT_*) - highest priority
metadata.json - local overrides (gitignored)
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

Commands

Advanced Commands

Memory Commands

Molecule Commands

​Overview

​Syntax

​Subcommands

​Server Lifecycle

​start

​stop

​status

​Configuration

​show

​set

​test

​Version Control

​commit

​push

​pull

​Remote Management

​remote add

​remote list

​remote remove

​Maintenance

​clean-databases

​killall

​Environment Variables

​Configuration Precedence

​Dolt Sync Workflows

​Team Collaboration

​Backup and Recovery

​Multi-Machine Sync

​Examples

​View Current Configuration

​Change Database Name

​Configure Remote Access

​Setup Custom Data Directory

​Batch Commit Workflow

​Setup DoltHub Remote

​Troubleshoot Connection Issues

​Troubleshooting

​Server Connection Failed

​Remote Not Found

​Push Failed: Uncommitted Changes

​Data Directory Not Found

​Orphan Server Processes

​Related Commands

​See Also

Build docs developers (and LLMs) love