examples/bd-example-extension-go/README.md
This example demonstrates how to extend bd with custom tables for application-specific orchestration, following the patterns described in EXTENDING.md.
example_executions, example_checkpoints) to bd's SQLite databaseissues table with proper cascadingAll tables are prefixed with example_ to avoid conflicts:
CREATE TABLE example_executions (...)
CREATE TABLE example_checkpoints (...)
Extension tables link to bd's issues with cascading deletes:
FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE
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);
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
bd init --prefix demo)# 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).
# 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
Just 116 lines total - minimal, focused extension example.
example_executions, example_checkpoints) with foreign keys and indexesDemonstrates:
beads.FindDatabasePath)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
`
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
`
query := `
SELECT checkpoint_data
FROM example_checkpoints
WHERE execution_id = ?
ORDER BY created_at DESC
LIMIT 1
`
// 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)
// 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")
Initialize bd:
bd init --prefix demo
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
Run the demo:
bd-example-extension-go -cmd demo
Check the results:
bd list
sqlite3 .beads/demo.db "SELECT * FROM example_executions"
This pattern is used in production by:
See EXTENDING.md for more patterns and the VC implementation example.