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

> Discover Dolt, the version-controlled SQL database. Learn how Beads leverages Dolt for Git-like issue tracking workflows and data persistence.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: how-to-guide
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/config.go)**: Implements configuration persistence through `SetConfig` and `GetConfig` functions that read and write to Dolt tables.
- **[`internal/testutil/testdoltserver.go`](https://github.com/gastownhall/beads/blob/main/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):

```go
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:

```go
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:

```bash

# 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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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.