From 73f8cff307de3af86c4abc62dc6300c98ea0fa54 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 16:06:28 +0000 Subject: [PATCH] Upgrade notes: 0011 locks component while it backfills, 0007's rename fails 2.1 instances (#764) The 2.2.0 upgrade notes say what the two migrations do to the 2.1 instances still serving during a rolling restart, and what to do about it. The Upgrades section of docs/deployment.md points to such notes. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_012e6DJb3r3wrWZ3mXUjH79T --- docs/changes/2.2.0/764.upgrade.md | 16 ++++++++++++++++ docs/deployment.md | 4 ++++ 2 files changed, 20 insertions(+) create mode 100644 docs/changes/2.2.0/764.upgrade.md diff --git a/docs/changes/2.2.0/764.upgrade.md b/docs/changes/2.2.0/764.upgrade.md new file mode 100644 index 00000000..d0abeaff --- /dev/null +++ b/docs/changes/2.2.0/764.upgrade.md @@ -0,0 +1,16 @@ +Two of the upgrade's migrations reach the 2.1 instances that still serve +during a rolling restart; upgrade in a quiet window. The migration that +adds `component.unlisted_at` locks `component` (`ACCESS EXCLUSIVE`) and, +before it commits, writes the column on every unlisted version: until then +every query on `component` waits, from every instance, the 2.1 ones +included. It is brief on most installs and takes longest where many +versions are unlisted, as on a NuGet repository, where a client's delete +unlists (`SELECT count(*) FROM component WHERE NOT listed` counts the rows +it writes). The rename of `nexus_import` to `repository_import` takes the +table away from the 2.1 instances: until the last one is replaced, its +import worker logs `relation "nexus_import" does not exist` every few +seconds and its import API fails with the same error, and an import running +on it stops there. Let running imports finish, or cancel them, before the +upgrade, and start none until every instance runs 2.2.0. An import caught +by the upgrade stays `running` and is continued by a 2.2.0 instance once +its lease has run out (two minutes), as a resumed one is. diff --git a/docs/deployment.md b/docs/deployment.md index 9a103659..a3548acb 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1998,6 +1998,10 @@ Then sign in as a local administrator and fix or disable the broken realm. release first. - Read the [changelog](../CHANGELOG.md) for each version you skip over. A release that needs something other than a rolling restart says so there. +- In a rolling restart, the first instance of the new version migrates the + database while the instances of the old version still serve. When a + migration makes them wait or fail until they are replaced, the release's + upgrade notes say so, and what to do about it. - Migrations run automatically on the first start of a new version and only move forward. Rolling back to an older binary after a newer one has migrated the database requires restoring the backup taken before the upgrade.