beads/examples/bd-example-extension-go
Chris Sells 54a7547b0d docs: canonical concept page, section overviews, and concept diagrams
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
  canonical concept page (modeled on Gas City's how-gas-city-works):
  problem-first framing, the bead -> dependencies -> ready-work loop, hash
  IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
  federation, and storage modes, led by four mermaid diagrams. Other pages
  link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
  hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
  not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
  surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
  wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
  external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
  SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
  multi-agent, and integrations indexes to list every child with one-line
  summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
  (core-concepts/hash-ids) and embedded-vs-server mode
  (architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
  status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
2026-07-12 10:37:07 -07:00
..
.gitignore examples: Add complete Go extension example with documentation (#15) 2025-10-14 01:08:00 -07:00
go.mod /{examples,go.mod}: bump go 2026-04-22 12:10:31 -07:00
go.sum feat(init): add --database flag to configure existing server database (#2102) 2026-02-24 22:26:07 -08:00
main.go Dolt-native cleanup: remove legacy code, rename API, add server watchdog 2026-02-15 23:43:20 -08:00
README.md docs: canonical concept page, section overviews, and concept diagrams 2026-07-12 10:37:07 -07:00
schema.sql examples: Add complete Go extension example with documentation (#15) 2025-10-14 01:08:00 -07:00

BD Extension Example (Go)

This legacy example demonstrates how to extend SQLite-backed bd databases with custom tables for application-specific orchestration.

Note: Custom SQLite table extensions are a legacy pattern. Current Dolt-backed beads workflows should prefer standalone integration tools that call bd --json commands or use bd query for SQL access. See Extensible Database for the current guidance.

What This Example Shows

  1. Schema Extension: Adding custom tables (example_executions, example_checkpoints) to bd's SQLite database
  2. Foreign Key Integration: Linking extension tables to bd's issues table with proper cascading
  3. Dual-Layer Access: Using bd's Go API for issue management while directly querying extension tables
  4. Complex Queries: Joining bd's issues with extension tables for powerful insights
  5. Execution Tracking: Implementing agent assignment, checkpointing, and crash recovery patterns

Key Patterns Illustrated

Pattern 1: Namespace Your Tables

All tables are prefixed with example_ to avoid conflicts:

CREATE TABLE example_executions (...)
CREATE TABLE example_checkpoints (...)

Pattern 2: Foreign Key Relationships

Extension tables link to bd's issues with cascading deletes:

FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE

Pattern 3: Index Common Queries

Indexes are created for frequent query patterns:

CREATE INDEX idx_executions_status ON example_executions(status);
CREATE INDEX idx_executions_issue ON example_executions(issue_id);

Pattern 4: Layer Separation

  • bd layer: Issue tracking, dependencies, ready work
  • Extension layer: Execution state, agent assignments, checkpoints

Pattern 5: Join Queries

Powerful queries join both layers:

SELECT i.id, i.title, i.priority, e.status, e.agent_id, COUNT(c.id)
FROM issues i
LEFT JOIN example_executions e ON i.id = e.issue_id
LEFT JOIN example_checkpoints c ON e.id = c.execution_id
GROUP BY i.id, e.id

Building and Running

Prerequisites

  • Go 1.24 or later
  • bd initialized in a directory (run bd init --prefix demo)

Install

# Install from the repository
go install github.com/steveyegge/beads/examples/bd-example-extension-go@latest

# Or install from local source
cd examples/bd-example-extension-go
go install .

The binary will be installed as bd-example-extension-go in your $GOPATH/bin (or $GOBIN if set).

Running

# Auto-discover database and run
bd-example-extension-go

# Or specify database path
bd-example-extension-go -db .beads/demo.db

Output:

Claiming: demo-5
  ✓ assess
  ✓ implement
  ✓ test

Status:
  demo-4: Fix memory leak [closed] agent=agent-demo checkpoints=3
  demo-1: Implement auth [in_progress] agent=agent-alice checkpoints=0
  demo-5: Test minimized [closed] agent=demo-agent checkpoints=3

Code Structure

Just 116 lines total - minimal, focused extension example.

  • main.go (93 lines): Complete workflow with embedded schema
  • schema.sql (23 lines): Extension tables (example_executions, example_checkpoints) with foreign keys and indexes

Demonstrates:

  1. Auto-discover database (beads.FindDatabasePath)
  2. Dual-layer access (bd API + direct SQL)
  3. Execution tracking with checkpoints
  4. Complex joined queries across layers

Example Queries

Find Running Executions with Checkpoint Count

query := `
    SELECT i.id, i.title, e.status, e.agent_id, COUNT(c.id) as checkpoints
    FROM issues i
    INNER JOIN example_executions e ON i.id = e.issue_id
    LEFT JOIN example_checkpoints c ON e.id = c.execution_id
    WHERE e.status = 'running'
    GROUP BY i.id, e.id
`

Find Failed Executions

query := `
    SELECT i.id, i.title, e.error, e.completed_at
    FROM issues i
    INNER JOIN example_executions e ON i.id = e.issue_id
    WHERE e.status = 'failed'
    ORDER BY e.completed_at DESC
`

Get Latest Checkpoint for Recovery

query := `
    SELECT checkpoint_data
    FROM example_checkpoints
    WHERE execution_id = ?
    ORDER BY created_at DESC
    LIMIT 1
`

Integration with bd

Using bd's Go API

// Auto-discover database path
dbPath := beads.FindDatabasePath()
if dbPath == "" {
    log.Fatal("No bd database found")
}

// Open bd storage
store, err := beads.Open(ctx, dbPath)

// Find ready work
readyIssues, err := store.GetReadyWork(ctx, beads.WorkFilter{Limit: 10})

// Update issue status
updates := map[string]interface{}{"status": beads.StatusInProgress}
err = store.UpdateIssue(ctx, issueID, updates, "agent-name")

// Close issue
err = store.CloseIssue(ctx, issueID, "Completed", "agent-name")

// Find corresponding JSONL path (for git hooks, monitoring, etc.)
jsonlPath := beads.FindJSONLPath(dbPath)

Direct Database Access

// Open same database for extension tables
db, err := sql.Open("sqlite3", dbPath)

// Initialize extension schema
_, err = db.Exec(Schema)

// Query extension tables
rows, err := db.Query("SELECT * FROM example_executions WHERE status = ?", "running")

Testing the Example

  1. Initialize bd:

    bd init --prefix demo
    
  2. Create some test issues:

    bd create "Implement authentication" -p 1 -t feature
    bd create "Add API documentation" -p 1 -t task
    bd create "Refactor database layer" -p 2 -t task
    
  3. Run the demo:

    bd-example-extension-go -cmd demo
    
  4. Check the results:

    bd list
    sqlite3 .beads/demo.db "SELECT * FROM example_executions"
    

Real-World Usage

This pattern is used in production by:

  • VC (VibeCoder): Multi-agent orchestration with state machines
  • CI/CD Systems: Build tracking and artifact management
  • Task Runners: Parallel execution with dependency resolution

Next Steps

  1. Add Your Own Tables: Extend the schema with application-specific tables
  2. Implement State Machines: Use checkpoints for resumable workflows
  3. Add Metrics: Track execution times, retry counts, success rates
  4. Build Dashboards: Query joined data for visibility
  5. Integrate with Agents: Use bd's ready work queue for agent orchestration

See Also