Compare commits

...
Sign in to create a new pull request.

1 commit

Author SHA1 Message Date
Chris Sells
602f4582c5 docs(upgrading): adopt a migrated remote without relying on bd bootstrap
The upgrade docs told every non-migrating clone to adopt the migrated
database with `bd bootstrap`, claiming it replaces the local database.
On a clone that already has one, bootstrap prints "Nothing to do." and
exits 0, leaving the clone on the old schema (#6687).

Document the flow that works: every clone backs up with the old binary,
other clones `bd dolt pull` on the old binary after the migrator pushes
and then upgrade; a clone that already upgraded moves its local database
aside, re-clones with `bd bootstrap`, and re-imports the backup. Align
the gate description, shared-server note, and init-safety summary.

Also add a post-migration step to run `bd recompute-blocked` once per
database, since migration 0059 can over-set is_blocked and silently hide
ready work (#7037).

Refs #6687, #7037
2026-10-05 21:41:01 -07:00
2 changed files with 81 additions and 29 deletions

View file

@ -37,8 +37,11 @@ bd info --whats-new
`bd migrate`
`bd dolt push`
Other clones should install the new binary and run `bd bootstrap`, not
independently migrate. The full procedure is below.
Other clones must not migrate independently. After the migrator pushes, each
other clone runs `bd dolt pull` with its current binary, then installs the new
one. A clone that already has the new binary adopts the migrated database by
moving its local database aside and running `bd bootstrap`; `bd bootstrap` on
its own leaves an existing database untouched. The full procedure is below.
## Upgrading
@ -196,6 +199,23 @@ and picks up where it left off.
Those lines go to stderr, and only when stderr is a terminal, so a piped or CI
upgrade prints nothing at all. Silence there is not a stall either.
#### Repair blocked flags after migrating
Migration 0059 can mark issues as blocked when they are not, which drops them
out of `bd ready` without any error
([#7037](https://github.com/gastownhall/beads/issues/7037)). It happens on a
Dolt server older than 2.4.0, and the embedded engine is likely affected too.
Once a database has migrated, run this once for that database on every clone:
```bash
bd recompute-blocked --json
```
It recomputes the flag from the dependency graph, so it is safe on any
database, and `"rows_corrected"` greater than zero means the database was hit.
It works in embedded, server and proxied-server mode, so run it even where
`bd doctor` cannot check blocked state.
#### Upgrade every client that shares a store, together
A bd binary refuses a database migrated past the schema it knows, rather than
@ -226,8 +246,8 @@ a Dolt remote configured. Migrating more than one clone of a shared remote
independently forks the schema, after which `bd dolt pull` can no longer merge —
the break is silent and, across a primary-key-reshaping migration, unrecoverable
([#4259](https://github.com/gastownhall/beads/issues/4259)). The supported flow
is: one machine migrates and publishes; every other clone re-clones the migrated
database.
is: one machine migrates and publishes; every other clone takes the migrated
database from the remote instead of migrating its own.
This applies to **every** upgrade that crosses a pending migration on a
remote-backed database — the same procedure whether you are moving to a
@ -244,7 +264,10 @@ The gate is **state-aware by default**
server always stops for consent, because migrating it changes the schema
every connected client sees (see [Shared servers](#shared-servers) below).
- **stops and directs you to adopt** (`bd bootstrap`) when the remote has
already been migrated by another clone.
already been migrated by another clone. On a clone that already has a local
database, `bd bootstrap` by itself reports `Nothing to do.` and changes
nothing; adopt with the steps under *Multiple clones sharing one remote*
below.
- **stops for a human decision** when this clone and the remote applied
different content for the same migration (a genuine fork), or when the
remote's schema state cannot be read from the cached ref.
@ -302,28 +325,53 @@ the situation.
**Multiple clones sharing one remote:**
```bash
# 1. With your CURRENT (old) binary, on EVERY clone: publish all work and get in
# sync, then stop editing until the upgrade is done.
# 1. With your CURRENT (old) binary, on EVERY clone: publish all work, get in
# sync and back up, then stop editing until the upgrade is done.
bd dolt push
bd dolt pull
# 2. Designated migrator ONLY: back up, install the new binary, then migrate
# and publish.
bd export --all -o .beads/backup/pre-migrate.jsonl
# 2. Designated migrator ONLY: install the new binary, then migrate and publish.
bd migrate
bd dolt push
# 3. Every OTHER clone: install the new binary, then ADOPT the migrated database.
# (bd dolt pull is refused here — the clone still has pending migrations — so
# re-clone instead. Safe because step 1 already pushed all work.)
bd bootstrap
# 3. Every OTHER clone, after the migrator has pushed: pull the migrated
# database while still on the CURRENT binary, then install the new binary.
bd dolt pull
bd version # after installing: confirm the new version
```
`bd bootstrap` replaces the local database, so any work not pushed in step 1 is
lost — that is why step 1 publishes everything first. If a clone was instead
migrated independently and `bd dolt pull` later fails with `cannot merge because
table dependencies has different primary keys in its common ancestor`, the
schema has already forked — follow the recovery playbook:
The pull in step 3 brings the migrated schema down with the data, so the new
binary finds nothing to migrate and the clone keeps its local state. Between
that pull and the install, the old binary refuses the database (it is now
newer than the schema the old binary knows), so install straight away.
**A clone that already runs the new binary** cannot take step 3 as written: the
gate refuses `bd dolt pull` while the clone has pending migrations. Adopt the
migrated database by re-cloning it. `bd bootstrap` never replaces an existing
database — run against one, it prints `Database already exists` and
`Nothing to do.` and leaves the clone on the old schema — so move the local
database aside first, then re-apply the step 1 backup:
```bash
mv .beads/embeddeddolt .beads/backup/embeddeddolt.pre-adopt # embedded mode (the default)
bd bootstrap # clones the migrated database from the remote
bd import .beads/backup/pre-migrate.jsonl # restores what a re-clone cannot bring
```
The re-clone brings only what the remote has, so the import restores this
clone's clone-local beads (wisps, for example) and anything step 1 did not
push; rows the remote already holds in a newer version are skipped as stale.
The backup has to come from the old binary, as in step 1: on a clone with
pending migrations the new binary's `bd export` fails. Keep the moved-aside
directory until you have checked the result — the old binary can still open
it. In server mode the database lives under `.beads/dolt/` instead; stop the
server and move the database outside `.beads/dolt/` (see
[re-clone-gotchas](/recovery/init-safety#re-clone-gotchas)).
If a clone was instead migrated independently and `bd dolt pull` later fails
with `cannot merge because table dependencies has different primary keys in its
common ancestor`, the schema has already forked — follow the recovery playbook:
[the pk-fork-refused runbook](/recovery/init-safety#pk-fork-refused).
<Note>
@ -415,10 +463,12 @@ hazards now apply at once — the co-resident lockout above and the cross-clone
fork of [Remote-backed databases](#remote-backed-databases-and-multiple-clones)
— so `bd` requires the stronger designated-migrator consent it describes:
`bd migrate --force`, from exactly one machine, followed by `bd dolt push`. If
another clone has already migrated and pushed, adopt its database with
`bd bootstrap` instead of migrating. On a shared server, adopting also promotes
the schema for every client of that server, so step 1 still comes first either
way.
another clone has already migrated and pushed, adopt its database instead of
migrating, as described under
[Remote-backed databases](#remote-backed-databases-and-multiple-clones) —
`bd bootstrap` alone does not replace an existing database. On a shared
server, adopting also promotes the schema for every client of that server, so
step 1 still comes first either way.
<Warning>
Migrating is one-way for the fleet: after step 2, a client still on the older

View file

@ -427,12 +427,14 @@ skipping straight to `bd list`) can hit either of two live gotchas — see
has the recipe. Plan for the rule, not the exception.
- **One designated migrator**: upgrade one machine, let it migrate, then
`bd dolt push`.
- **Every other clone adopts, does not pull**: after the migrator pushes, each
other clone upgrades the binary and runs `bd bootstrap` to adopt the migrated
database. `bd dolt pull` is *refused* while the clone still has pending
migrations, so do not rely on it; the "sync before" step above is what
preserves these clones' work, because `bd bootstrap` replaces the local
database.
- **Every other clone takes the migrated database, does not migrate**: after
the migrator pushes, each other clone runs `bd dolt pull` while still on the
*old* binary, then upgrades. Once the new binary is installed that pull is
*refused* while the clone has pending migrations, and `bd bootstrap` never
replaces an existing database — on its own it reports `Nothing to do.` — so
a clone that upgraded first must move its local database aside before
`bd bootstrap` can re-clone. The recipe is in
[Remote-backed databases and multiple clones](/getting-started/upgrading#remote-backed-databases-and-multiple-clones).
---