beads/website/docs/getting-started/upgrading.md
matt wilkie e2e4975044
Document supported go install modes (bd-o5a) (#3480)
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
    website docs, plugin/npm docs, examples, and doctor hints.
  - Standardized on:
      - CGO_ENABLED=0 go install ... for server-mode only
      - CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
        capable
  - Added scripts/check-go-install-guidance.sh and wired it into CI.
  - Updated default.nix to use gms_pure_go instead of ICU flags.

  Validation passed locally:

  - make test
  - golangci-lint run --build-tags=gms_pure_go ./...
  - ./scripts/check-go-install-guidance.sh
  - ./scripts/check-build-tags.sh
  - go test -tags gms_pure_go ./cmd/bd/doctor
  - doc flag check
2026-04-25 11:30:19 -07:00

222 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
id: upgrading
title: Upgrading
sidebar_position: 4
---
# Upgrading bd
How to upgrade bd and keep your projects in sync.
## Checking for Updates
```bash
# Current version
bd version
# What's new in recent versions
bd info --whats-new
bd info --whats-new --json # Machine-readable
```
## Upgrading
Use the command that matches your install method.
| Install method | Platforms | Command |
|---|---|---|
| Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` |
| PowerShell installer | Windows | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` |
| Homebrew | macOS, Linux | `brew upgrade beads` |
| go install (server-mode only) | macOS, Linux, FreeBSD, Windows | `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` |
| go install (embedded-capable) | macOS, Linux, Windows | `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` |
| npm | macOS, Linux, Windows | `npm update -g @beads/bd` |
| bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` |
| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && make build` |
### Quick install script (macOS/Linux/FreeBSD)
```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```
### PowerShell installer (Windows)
```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
```
### Homebrew
```bash
brew upgrade beads
```
### go install
```bash
# Server-mode only
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
# Embedded-capable
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
```
### From Source
```bash
cd beads
git pull
make build
sudo mv bd /usr/local/bin/
```
## After Upgrading
**Important:** After upgrading, update your hooks:
```bash
# 1. Check what changed
bd info --whats-new
# 2. Update git hooks to match new version
bd hooks install
# 3. Check for any outdated hooks
bd info # Shows warnings if hooks are outdated
# 4. If using Dolt backend, restart the server
bd dolt stop && bd dolt start
```
**Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes.
## Database Migrations
After major upgrades, check for database migrations:
```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json
# Preview migration changes
bd migrate --dry-run
# Apply migrations
bd migrate
# Migrate and clean up old files
bd migrate --cleanup --yes
```
## Cross-era Upgrades
If you're upgrading from a much older version of bd, your project may use a different storage backend. bd has gone through several storage eras:
| Era | Versions | Storage |
|---|---|---|
| SQLite | v0.30–v0.50 | `.beads/beads.db` |
| Dolt server | v0.50–v0.58 | `.beads/dolt/` (external server) |
| Embedded Dolt (old) | v0.59–v0.63.2 | `.beads/dolt/` (in-process) |
| Embedded Dolt (current) | v0.63.3+ | `.beads/embeddeddolt/` |
### From v0.63.3+ (current era)
No special steps needed. Just upgrade the binary and run:
```bash
bd migrate
```
### From v0.59–v0.63.2 (old embedded)
Direct upgrade works automatically:
```bash
# Just use the new binary — it handles the conversion
bd list
```
### From v0.50–v0.58 (Dolt server era)
The old binary used an external Dolt SQL server. The new binary uses an embedded engine.
```bash
# 1. Export your data while the old binary still works
bd list --json -n 0 --all > .beads/issues.jsonl
# 2. Stop the Dolt server
dolt sql-server --stop # or kill the process
# 3. Remove stale server metadata and old storage directories
rm -f .beads/metadata.json .beads/config.json
rm -rf .beads/dolt .beads/embeddeddolt
# 4. Initialize with the new binary
bd init --from-jsonl --quiet
# 5. Verify
bd list --all
```
### From v0.30–v0.50 (SQLite era)
The old binary stored data in SQLite. The new binary uses Dolt.
**Recommended: use the migration script** (requires `sqlite3` and `jq`):
```bash
# Download the script from the beads repo
curl -fsSLO https://raw.githubusercontent.com/gastownhall/beads/main/scripts/migrate-sqlite-to-current.sh
chmod +x migrate-sqlite-to-current.sh
# Run it in your project directory
./migrate-sqlite-to-current.sh
```
The script exports issues, dependencies, and labels from SQLite, handles type normalization, and imports everything into the new Dolt backend.
**Alternative: manual export with the old binary.** Old binaries are always available on [GitHub Releases](https://github.com/gastownhall/beads/releases). Download the version that matches your project, then:
```bash
# 1. Export with the old binary
./bd-old list --json -n 0 --all > .beads/issues.jsonl
# 2. Import with the current binary
bd init --from-jsonl --quiet
# 3. Verify
bd list --all
```
> **Note:** The manual export preserves issue content but not dependencies or labels. Use the migration script for a more complete transfer.
## Troubleshooting Upgrades
### Hooks out of date
```bash
bd hooks install
```
### Database schema changed
```bash
bd migrate --dry-run
bd migrate
```
### Recovery after upgrade
If you need to restore from a backup:
```bash
bd init
bd backup restore [path] --force
```
Or pull from a Dolt remote:
```bash
bd dolt pull
```