# How Gas Town Stores and Manages Bead Data with the Dolt SQL Server

> Discover how Gas Town stores and manages bead data using Dolt SQL Server. Learn about versioned rows, local directories, and Git-style syncing for efficient data handling.

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

---

**Gas Town stores each bead as a versioned row in a Dolt SQL database, using a local `.beads/` directory that syncs to a remote Dolt SQL Server via Git-style push and pull operations.**

The Gas Town rig system treats every unit of work as a "bead" tracked within a **Dolt SQL Server** backend. By leveraging Dolt's Git-compatible database engine, the platform combines standard SQL queries with immutable version history. This architecture enables distributed collaboration across multiple rigs while maintaining strict audit trails for every bead modification.

## The .beads Directory and Dolt SQL Database Structure

Every Gas Town rig initializes a hidden `.beads/` directory at its root. This directory contains a full Dolt repository that functions as a SQL database, housing tables including **beads**, **bead_attachments**, **bead_comments**, and auxiliary indexing tables. According to the Gas Town source code, the `beads.New()` function in [`internal/beads/beads.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/beads.go) resolves this directory and establishes the connection to the local Dolt instance.

## How Bead Data Flows Through the Dolt SQL Server

The lifecycle of bead data moves from local initialization to remote synchronization through four distinct phases.

### Initializing the Local Database

When a rig initializes, `beads.New(cwd)` creates a `Beads` handle that points to the resolved `.beads/` directory. This handle serves as the primary interface for all subsequent CRUD operations against the Dolt SQL tables.

### Creating and Persisting Beads

Creating a bead triggers `beads.Store.Create()`, which translates the bead structure into a Dolt SQL `INSERT` statement. The system executes this via the Dolt CLI (`dolt sql`), followed by `dolt add` and `dolt commit` operations. Each modification becomes a Git commit object, preserving complete version history for fields like ID, Title, Status, and Assignee.

### Querying Bead Data

Local agents such as `refinery` and `witness` retrieve bead data using `beads.Query()`, implemented in [`internal/beads/database.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/database.go). This method runs standard `SELECT` statements against the local Dolt database, ensuring offline-capable access to the most recently synced state.

### Synchronizing with the Remote Server

The `bd.Push()` operation transmits the local `.beads/` repository to the remote Dolt SQL Server using `dolt push origin master`. Once pushed, the server updates its SQL tables, making the bead data available to other rigs and web interfaces while maintaining the Git-based commit history.

## Schema Evolution and Version Control

Gas Town handles schema migrations through [`internal/cmd/wl_schema_evolution.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/wl_schema_evolution.go), which executes `ALTER TABLE` statements via Dolt SQL when adding new fields like `priority`. Because Dolt tracks schema changes as versioned commits, every structural modification preserves an auditable trail compatible with standard Git workflows.

## Working with Bead Data: Code Examples

The following examples demonstrate how to interact with the Dolt SQL Server backend using the Gas Town beads package.

Create a new bead and persist it to the local Dolt database:

```go
bd, _ := beads.New(".")               // resolve .beads/ directory
newIssue := beads.Issue{
    Title:    "Implement feature X",
    Status:   beads.StatusOpen,
    Assignee: "alice",
}
created, err := bd.Create(beads.CreateOptions{
    Issue: newIssue,
})
if err != nil {
    log.Fatalf("bead creation failed: %v", err)
}
fmt.Printf("Created bead %s\n", created.ID)

```

Query open beads using standard SQL:

```go
rows, err := bd.Query(`SELECT id, title FROM beads WHERE status = 'open'`)
if err != nil {
    log.Fatalf("query failed: %v", err)
}
for _, r := range rows {
    fmt.Printf("Open bead %s: %s\n", r["id"], r["title"])
}

```

Push local changes to the remote Dolt SQL Server:

```go
if err := bd.Push(); err != nil {
    log.Fatalf("push to Dolt server failed: %v", err)
}

```

## Key Implementation Files

Understanding the Dolt SQL Server integration requires familiarity with these specific source files:

- **[`internal/beads/beads.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/beads.go)**: Entry point for the `Beads` object; resolves the `.beads/` directory and provides high-level APIs.
- **[`internal/beads/store.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/store.go)**: Implements CRUD operations; translates bead actions into Dolt CLI commands.
- **[`internal/beads/database.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/database.go)**: Low-level wrapper around `dolt sql`; provides `Query` and transaction helpers.
- **[`internal/beads/beads_mr.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/beads_mr.go)**: Manages "merge-request" beads; merges branches in Dolt and records the MR bead.
- **[`plugins/dolt-snapshots/main.go`](https://github.com/gastownhall/gastown/blob/main/plugins/dolt-snapshots/main.go)**: Creates immutable tags and branches on the Dolt server for snapshotting bead state.
- **[`internal/wasteland/wasteland.go`](https://github.com/gastownhall/gastown/blob/main/internal/wasteland/wasteland.go)**: Demonstrates federation of rigs via DoltHub; each rig's bead DB is a Dolt repo that can be forked and synced.
- **[`internal/cmd/wl_schema_evolution.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/wl_schema_evolution.go)**: Handles schema changes for bead tables; runs `ALTER TABLE` via Dolt SQL.

## Summary

- **Dolt SQL Server** serves as the backend for Gas Town's bead management system, providing both SQL query capabilities and Git-style version control.
- Each rig maintains a local `.beads/` directory containing a full Dolt repository with tables for beads, attachments, and comments.
- The `beads` package translates high-level operations into Dolt CLI commands (`dolt sql`, `dolt commit`, `dolt push`) to persist and sync data.
- Schema evolution is managed through versioned SQL migrations, ensuring structural changes remain auditable.
- Remote synchronization makes bead data available across distributed rigs while preserving complete history.

## Frequently Asked Questions

### How does the Dolt SQL Server store bead data in Gas Town?

The Dolt SQL Server stores bead data as rows in standard SQL tables (primarily the **beads** table) within a Git-backed repository. Each Gas Town rig maintains a local `.beads/` directory that functions as a Dolt database; when synchronized, the server replicates these tables and their complete version history, making the data queryable via SQL while retaining Git commit semantics.

### What happens when a bead is created or updated?

When a bead is created or modified, the `beads.Store.Create()` method in [`internal/beads/store.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/store.go) generates a SQL `INSERT` or `UPDATE` statement and executes it via `dolt sql`. The change is then staged with `dolt add` and committed with `dolt commit`, creating an immutable Git commit that captures the exact state of the bead data at that moment.

### How does Gas Town handle schema changes for bead tables?

Schema modifications are handled by [`internal/cmd/wl_schema_evolution.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/wl_schema_evolution.go), which executes `ALTER TABLE` statements against the Dolt database. Because Dolt versions schema changes as commits, every structural evolution (such as adding a `priority` column) is recorded in the Git history, allowing rollbacks and audit trails for database migrations.

### Can bead data be queried offline?

Yes. Because Dolt is a fully embedded SQL database, the `beads.Query()` method in [`internal/beads/database.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/database.go) executes `SELECT` statements against the local `.beads/` repository without requiring network connectivity. Rigs can query, create, and modify beads offline; changes sync to the remote Dolt SQL Server when `bd.Push()` is invoked.