From 054ae7ac856255d7d85f222e3685f7bc39cddaf9 Mon Sep 17 00:00:00 2001 From: Chris Sells Date: Mon, 5 Oct 2026 21:54:45 -0700 Subject: [PATCH] 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 --- docs/getting-started/upgrading.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index 634c1ac99..649383129 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -443,8 +443,8 @@ configured, though the two cases consent differently Upgrade one server's clients like this: ```bash -# 1. Upgrade bd on every client of the server. Reads keep working throughout — -# an upgraded client reads the old schema, it just cannot write to it. +# 1. Upgrade bd on every client of the server. Until step 2, an upgraded +# client refuses writes and most reads fail (see below). bd version # on each client, confirm the new version # 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 ``` -Between steps 1 and 2, an upgraded client reads normally and its writes are -refused with the gate's guidance. Nothing is silently promoted, so there is no -deadline — but the window is a degraded one, so keep it short. +Between steps 1 and 2, an upgraded client refuses writes with the gate's +guidance, and most reads fail too: `bd list`, `bd show` and `bd ready` stop +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 hazards now apply at once — the co-resident lockout above and the cross-clone