Skip to content

Upgrade notes: migration 0011 locks component while it backfills, 0007's rename fails 2.1 instances - #910

Merged
schmitch merged 1 commit into
mainfrom
claude/issue-764-migration-upgrade-notes
Nov 17, 2026
Merged

schmitch merged 1 commit into
mainfrom
claude/issue-764-migration-upgrade-notes

Conversation

@schmitch

Copy link
Copy Markdown
Member

Fixes #764

docs/deployment.md (Upgrades) promises that a release that needs something other than a rolling restart says so. Two 2.2.0 migrations reach the 2.1 instances still serving during the rollout, and the notes did not say it.

What changes

  • docs/changes/2.2.0/764.upgrade.md (new fragment, per docs/changes/README.md: the ref is the issue the change fixes, so the existing 185.upgrade.md and 642.upgrade.md stay as they are). It says:
    • Migration 0011 takes the ACCESS EXCLUSIVE lock on component and backfills unlisted_at on every unlisted version before it commits, so every query on component waits, from every instance including the 2.1 ones. Advice: upgrade in a quiet window; SELECT count(*) FROM component WHERE NOT listed counts the rows it writes.
    • Migration 0007's rename takes nexus_import away from the 2.1 instances: until the last one is replaced, its import worker logs relation "nexus_import" does not exist and its import API fails. Advice: let running imports finish or cancel them before the upgrade, and start none until every instance runs 2.2.0.
  • docs/deployment.md, Upgrades: one bullet saying that the first new instance migrates while old instances still serve, and that the upgrade notes say when a migration makes them wait or fail.

How the claims were checked

By reading the code, not by running a rolling upgrade:

  • migrations/0011_retention_unlisted_at.sql: ALTER TABLE component ADD COLUMN and the UPDATE … WHERE NOT listed are in one migration, without sqlx's -- no-transaction marker, so MIGRATOR.run (crates/db/src/pool.rs) runs them in one transaction.
  • v2.1.2 ships migrations 0001–0004 only, and its crates/db/src/import_dao.rs queries nexus_import / nexus_import_item by name, for the worker (claim_next every 5 s, lease renewal, finish) and the admin API.
  • One difference from the issue's wording: the issue says the rename "fails an import started on an old instance". In 2.1.2 the run on the old instance does end with a database error, but recording failed is itself a query on nexus_import, so the row stays running; its lease (120 s) is no longer renewed, and 2.2's claim_next takes a running import whose lease expired. The note therefore says the import stops on the old instance and is continued by a 2.2.0 instance, as a resumed one is (642.upgrade.md: its scan starts again).

Not done here

The issue's optional part, splitting 0011 into an add-column migration and a batched backfill so that component is locked only for the metadata change, is a code change and is left out of this pull request.

No admin API changes, so no web UI screen.


Generated by Claude Code

… 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012e6DJb3r3wrWZ3mXUjH79T
@schmitch
schmitch added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit e8dbd90 Nov 17, 2026
18 checks passed
@schmitch
schmitch deleted the claude/issue-764-migration-upgrade-notes branch November 17, 2026 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Upgrade notes: migration 0011 locks component while it backfills, and 0007's rename fails 2.1 instances during a rolling restart

2 participants