* 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 (commitddeff314c) 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 commit508387377before 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 (commit508387377is 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>
182 lines
3.2 KiB
Markdown
182 lines
3.2 KiB
Markdown
---
|
|
id: advanced
|
|
title: Advanced Features
|
|
sidebar_position: 3
|
|
---
|
|
|
|
# Advanced Features
|
|
|
|
Advanced beads functionality.
|
|
|
|
## Issue Rename
|
|
|
|
Rename issues while preserving references:
|
|
|
|
```bash
|
|
bd rename bd-42 bd-new-id
|
|
bd rename bd-42 bd-new-id --dry-run # Preview
|
|
```
|
|
|
|
Updates:
|
|
- All dependencies pointing to old ID
|
|
- All references in other issues
|
|
- Comments and descriptions
|
|
|
|
## Issue Merge
|
|
|
|
Merge duplicate issues:
|
|
|
|
```bash
|
|
bd merge bd-42 bd-43 --into bd-41
|
|
bd merge bd-42 bd-43 --into bd-41 --dry-run
|
|
```
|
|
|
|
What gets merged:
|
|
- Dependencies → target
|
|
- Text references updated across all issues
|
|
- Source issues closed with merge reason
|
|
|
|
## Database Compaction
|
|
|
|
Reduce database size by compacting old issues:
|
|
|
|
```bash
|
|
# View compaction statistics
|
|
bd admin compact --stats
|
|
|
|
# Preview candidates (30+ days closed)
|
|
bd admin compact --analyze --json
|
|
|
|
# Apply agent-generated summary
|
|
bd admin compact --apply --id bd-42 --summary summary.txt
|
|
|
|
# Immediate deletion (CAUTION!)
|
|
bd admin cleanup --force
|
|
```
|
|
|
|
**When to compact:**
|
|
- Database > 10MB with old closed issues
|
|
- After major milestones
|
|
- Before archiving project phase
|
|
|
|
## Restore from History
|
|
|
|
View deleted or compacted issues from git:
|
|
|
|
```bash
|
|
bd restore bd-42 --show
|
|
bd restore bd-42 --to-file issue.json
|
|
```
|
|
|
|
## Database Inspection
|
|
|
|
```bash
|
|
# Schema info
|
|
bd info --schema --json
|
|
|
|
# Raw database query (advanced — requires dolt sql-server running)
|
|
bd dolt sql "SELECT * FROM issues LIMIT 5"
|
|
```
|
|
|
|
## Custom Tables
|
|
|
|
Extend the database with custom tables:
|
|
|
|
```go
|
|
// In Go code using beads as library
|
|
storage.UnderlyingDB().Exec(`
|
|
CREATE TABLE IF NOT EXISTS custom_table (...)
|
|
`)
|
|
```
|
|
|
|
See the [bd-example-extension-go example](https://github.com/gastownhall/beads/blob/main/examples/bd-example-extension-go/README.md) for a working extension.
|
|
|
|
## Event System
|
|
|
|
Subscribe to beads events:
|
|
|
|
```bash
|
|
# View recent events
|
|
bd events list --since 1h
|
|
|
|
# Watch events in real-time
|
|
bd events watch
|
|
```
|
|
|
|
Events:
|
|
- `issue.created`
|
|
- `issue.updated`
|
|
- `issue.closed`
|
|
- `dependency.added`
|
|
- `sync.completed`
|
|
|
|
## Batch Operations
|
|
|
|
### Create Multiple
|
|
|
|
```bash
|
|
# Bootstrap a new database from JSONL
|
|
bd init --from-jsonl issues.jsonl
|
|
```
|
|
|
|
### Update Multiple
|
|
|
|
```bash
|
|
bd list --status open --priority 4 --json | \
|
|
jq -r '.[].id' | \
|
|
xargs -I {} bd update {} --priority 3
|
|
```
|
|
|
|
### Close Multiple
|
|
|
|
```bash
|
|
bd list --label "sprint-1" --status open --json | \
|
|
jq -r '.[].id' | \
|
|
xargs -I {} bd close {} --reason "Sprint complete"
|
|
```
|
|
|
|
## API Access
|
|
|
|
Use beads as a Go library:
|
|
|
|
```go
|
|
import "github.com/steveyegge/beads/internal/storage/embeddeddolt"
|
|
|
|
store, _ := embeddeddolt.New(ctx, ".beads", "beads", "main")
|
|
defer store.Close()
|
|
issue, _ := store.GetIssue(ctx, "bd-a1b2")
|
|
```
|
|
|
|
## Performance Tuning
|
|
|
|
### Large Databases
|
|
|
|
```bash
|
|
# Enable WAL mode
|
|
bd config set database.wal_mode true
|
|
|
|
# Increase cache
|
|
bd config set database.cache_size 10000
|
|
```
|
|
|
|
### Many Concurrent Agents
|
|
|
|
Beads uses Dolt server mode to handle concurrent access from multiple agents.
|
|
The server manages transaction isolation automatically.
|
|
|
|
```bash
|
|
# Start the Dolt server
|
|
bd dolt start
|
|
|
|
# Check server health
|
|
bd doctor
|
|
```
|
|
|
|
### CI/CD Optimization
|
|
|
|
In CI/CD environments, beads uses embedded mode by default (no server required):
|
|
|
|
```bash
|
|
# Just run commands directly — no special flags needed
|
|
bd list
|
|
```
|