diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index 3005b09f1..634c1ac99 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -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). @@ -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. Migrating is one-way for the fleet: after step 2, a client still on the older diff --git a/docs/recovery/init-safety.md b/docs/recovery/init-safety.md index 18aa6da05..1592552f7 100644 --- a/docs/recovery/init-safety.md +++ b/docs/recovery/init-safety.md @@ -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). ---