Compare commits
1 commit
main
...
docs/fix-b
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
602f4582c5 |
2 changed files with 81 additions and 29 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue