beads/examples/bd-example-extension-go
matt wilkie 57a4cab9f0
docs: fix broken xref to docs/EXTENDING.md in extension example (#3713)
* docs: fix broken xref to docs/EXTENDING.md in extension example

The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.

Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.

Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.

Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo

Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.

Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):

- docs/ADVANCED.md (3 refs):
  * Note in Extensible Database section: drop trailing "See
    EXTENDING.md for details" — the surrounding sentence about
    Dolt-era alternatives stands on its own.
  * Bold "See EXTENDING.md for complete documentation" line:
    redirect to the canonical working example
    (examples/bd-example-extension-go).
  * Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
  * Namespace doc for compact_*: replace "(see EXTENDING.md)" with
    "(used by `bd admin compact`)" — the doc itself describes the
    keys, no external reference needed.
  * See Also bullet: replace with link to docs/ADVANCED.md
    (Extensible Database section).
- examples/library-usage/README.md (1 ref):
  * See Also bullet: replace EXTENDING.md link with link to the
    sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
  * Custom Tables section: replace EXTENDING.md link with link to
    the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
  * Same fix as the live docs. EXTENDING.md was deleted before
    v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
    so this versioned snapshot has been broken since cut and a fix
    here doesn't violate frozen-in-time correctness — the link was
    never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
  * Updated to match the corrected source so the on-disk artifact
    isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
  * Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
    pointer to examples/bd-example-extension-go. These were real
    broken pointers in published Go source comments.

CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).

Verification:
  grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.

Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 13:18:43 -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: fix broken xref to docs/EXTENDING.md in extension example (#3713) 2026-05-05 13:18:43 -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 example demonstrates how to extend bd with custom tables for application-specific orchestration.

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