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

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 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. 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, 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:

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:

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:

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: Entry point for the Beads object; resolves the .beads/ directory and provides high-level APIs.
• internal/beads/store.go: Implements CRUD operations; translates bead actions into Dolt CLI commands.
• internal/beads/database.go: Low-level wrapper around dolt sql; provides Query and transaction helpers.
• internal/beads/beads_mr.go: Manages "merge-request" beads; merges branches in Dolt and records the MR bead.
• plugins/dolt-snapshots/main.go: Creates immutable tags and branches on the Dolt server for snapshotting bead state.
• 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: 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 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, 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 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.

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