* docs: clarify export versus database backup * docs: remove remaining JSONL backup wording
241 lines
5.8 KiB
Markdown
241 lines
5.8 KiB
Markdown
---
|
||
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 export refresh, legacy fallback, or safety 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)
|
||
|
||
Upgrade the binary and run:
|
||
|
||
```bash
|
||
bd migrate
|
||
```
|
||
|
||
If the project was initialized before `bd init` automatically wired git origin
|
||
as the Dolt remote, verify the remote after upgrading:
|
||
|
||
```bash
|
||
bd dolt remote list
|
||
```
|
||
|
||
When the list is empty, fix it on the machine whose local database is
|
||
authoritative:
|
||
|
||
```bash
|
||
bd export -o .beads/issues.pre-remote.jsonl # optional issue audit export
|
||
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
|
||
bd dolt push
|
||
```
|
||
|
||
Commit the resulting `.beads/config.yaml` change so other clones can run
|
||
`bd bootstrap` or `bd dolt pull`.
|
||
|
||
### 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
|
||
```
|