What is Dolt and How Beads Uses It as a Version-Controlled Database

Dolt is a version-controlled SQL database that combines Git-style branching with relational data storage, and Beads uses it exclusively as its persistence layer to enable Git-like workflows for issue tracking.

Beads is an AI-native issue tracker that reimagines how development teams manage tasks and workflows. At its core, Beads uses Dolt—a version-controlled SQL database—as its sole persistence layer to store, version, and sync all issue-tracking data. This architectural choice enables Git-like branching, commit history, and collaborative workflows directly on relational data without requiring a separate database server.

Understanding Dolt as a Version-Controlled SQL Database

Dolt functions as a SQL database with Git semantics. It stores tables, rows, and schema using the same content-addressed storage as Git, allowing you to branch, commit, merge, and diff data just like code. Unlike traditional databases that overwrite data in place, Dolt maintains complete history of every change, making it ideal for collaborative workflows where tracking the evolution of issues is critical.

How Beads Integrates Dolt for Issue Tracking

Beads embeds Dolt directly into its architecture, treating issue data as versioned content rather than static rows in a conventional database.

Local Database Storage

The Dolt database resides in the project's .beads/dolt/ directory, which is automatically Git-ignored to prevent conflicts with your source code repository. This location serves as the embedded database file, allowing Beads to operate offline while maintaining full version history locally.

Dolt SQL Server Lifecycle

Beads manages a local Dolt SQL-server process through the doltserver package found in internal/doltserver/doltserver.go. When you execute any bd command requiring database access, Beads automatically starts this server if it isn't already running. The server handles auto-port allocation (configurable via the BEADS_DOLT_SERVER_PORT environment variable) and supports shared-server mode for concurrent command execution.

Storage Layer Implementation

All high-level Beads operations—such as bd create, bd update, and bd sync—translate into SQL statements executed against the Dolt store via the storage/dolt implementation. The DoltStore struct in internal/storage/dolt provides CRUD helpers for issues, comments, and metadata, abstracting the SQL interface into Go APIs.

Key Architectural Components

The integration relies on several specific components:

• internal/doltserver/doltserver.go: Manages the Dolt SQL-server lifecycle, including Start(), Stop(), and IsSharedServerMode() functions for process management.
• internal/storage/dolt/dolt_test.go: Demonstrates store instantiation patterns, including the requirement to set MaxOpenConns: 1 due to Dolt's session-level checkout constraints.
• internal/storage/dolt/config.go: Implements configuration persistence through SetConfig and GetConfig functions that read and write to Dolt tables.
• internal/testutil/testdoltserver.go: Provides Docker-based test containers via StartIsolatedDoltContainer for integration testing.

Working with Dolt in Beads

Beads abstracts Dolt complexity while exposing its power through both APIs and CLI commands.

Creating a Dolt store (as used internally by most bd commands):

import (
    "context"
    "github.com/steveyegge/beads/internal/storage/dolt"
)

func exampleStore() (*dolt.DoltStore, error) {
    ctx := context.Background()
    cfg := &dolt.Config{
        Path:           "/tmp/beads-dolt",   // directory that holds the .dolt repo
        Database:       "beads",             // logical DB name
        CommitterName:  "example-bot",
        CommitterEmail: "bot@example.com",
        MaxOpenConns:   1,                   // required for Dolt's session-level checkout
    }
    return dolt.New(ctx, cfg)
}

Starting the Dolt SQL-server automatically:

import "github.com/steveyegge/beads/internal/doltserver"

func ensureServer() error {
    // Will start the server if it isn't already running.
    // Port is chosen automatically unless overridden by BEADS_DOLT_SERVER_PORT.
    return doltserver.Start(context.Background())
}

Using the CLI to leverage Dolt's versioning features:

# Record a new issue

bd create "Bug: login fails on Chrome"

# Push local commits to the remote Dolt repository

bd dolt push

# Pull new commits made by teammates

bd dolt pull

Configuration and Metadata in Dolt

Beads stores configuration data—including custom issue types and status pipelines—in dedicated Dolt tables such as config, metadata, and local_metadata. When you run commands like bd config set status.custom "triage,backlog,in-progress,done", the system invokes SetConfig from internal/storage/dolt/config.go, which writes to the Dolt config table and triggers view rebuilds. Changes are auto-committed to the database, enabling replication to remote Dolt repositories and providing built-in conflict resolution and history tracking.

Summary

• Dolt functions as a version-controlled SQL database that brings Git semantics to relational data.
• Beads uses Dolt as its sole persistence layer, storing all issue data in a local .beads/dolt/ directory.
• The doltserver package automatically manages the SQL-server lifecycle, enabling concurrent access without manual setup.
• All Beads operations translate to SQL statements against the Dolt store, with configuration and metadata persisted in dedicated tables.
• Built-in auto-commit and replication features enable offline-first operation and seamless multi-user collaboration through standard Git-like push/pull workflows.

Frequently Asked Questions

What makes Dolt different from a traditional SQL database?

Traditional SQL databases overwrite data in place and require external tools for versioning. Dolt maintains complete history using Git-style content addressing, allowing you to branch, merge, and diff data directly within the database engine using familiar SQL syntax.

Where does Beads store the Dolt database files?

Beads stores the Dolt database in the .beads/dolt/ directory within your project root. This directory is automatically Git-ignored to prevent your issue data from conflicting with your source code version control.

Can multiple Beads commands run simultaneously?

Yes. Beads implements a shared-server mode in internal/doltserver/doltserver.go that allows multiple processes to connect to the same Dolt SQL-server instance concurrently. The server auto-allocates ports and handles graceful shutdown when the last client disconnects.

How does Beads handle configuration changes?

Configuration changes are stored in Dolt tables via the methods in internal/storage/dolt/config.go. When you modify settings using bd config set, Beads writes to the config table and automatically commits the change, preserving history and enabling synchronization with remote repositories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}