Compare commits

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

1 commit

Author SHA1 Message Date
Chris Sells
054ae7ac85 docs(upgrading): reads fail too between upgrading clients and migrating a shared server
The shared-server upgrade steps said an upgraded client keeps reading the
old schema and only has writes refused. In practice most reads fail as
well: bd list, bd show and bd ready stop with "table not found: leases"
because 1.3 reads expect tables the old schema lacks. Say so, and tell
operators to run the migration as soon as the clients are upgraded
rather than treating the window as merely degraded.

Refs #6929, #7038
2026-10-05 21:54:45 -07:00

View file

@ -443,8 +443,8 @@ configured, though the two cases consent differently
Upgrade one server's clients like this: Upgrade one server's clients like this:
```bash ```bash
# 1. Upgrade bd on every client of the server. Reads keep working throughout — # 1. Upgrade bd on every client of the server. Until step 2, an upgraded
# an upgraded client reads the old schema, it just cannot write to it. # client refuses writes and most reads fail (see below).
bd version # on each client, confirm the new version bd version # on each client, confirm the new version
# 2. Once, from a workspace already set up against this server: consent. # 2. Once, from a workspace already set up against this server: consent.
@ -454,9 +454,11 @@ bd migrate schema # add --global for the shared global database
bd doctor bd doctor
``` ```
Between steps 1 and 2, an upgraded client reads normally and its writes are Between steps 1 and 2, an upgraded client refuses writes with the gate's
refused with the gate's guidance. Nothing is silently promoted, so there is no guidance, and most reads fail too: `bd list`, `bd show` and `bd ready` stop
deadline — but the window is a degraded one, so keep it short. with `table not found: leases`, because 1.3 reads expect tables the old schema
lacks. Nothing is silently promoted, so there is no deadline, but nothing works
in that window either, so run step 2 as soon as the clients are upgraded.
**If the shared server also has a Dolt remote**, step 2 is not enough. Two **If the shared server also has a Dolt remote**, step 2 is not enough. Two
hazards now apply at once — the co-resident lockout above and the cross-clone hazards now apply at once — the co-resident lockout above and the cross-clone