[OffgridwithJD]

#1341 item 66: the upgrade window. Between installing a new library and running ALTER EXTENSION pgcolumnar UPDATE (docs/installation.md steps 1–3), a database runs the new library over its previous release's catalog. Nothing tested what works there.

Stacked on #1448, which is stacked on #1446 and #1444. Merge them in that order; this branch is #1448's head plus one commit.

What happens in the window

Measured on PG18 with the 1.0-alpha5 library over a 1.0-alpha4 catalog:

operation	in the window	after ALTER EXTENSION UPDATE
CREATE TABLE … USING pgcolumnar, INSERT, SELECT, DELETE, UPDATE, VACUUM	work	work
DROP TABLE, TRUNCATE, pgcolumnar.vacuum()	fail: 42P01: columnar metadata table "pgcolumnar.retired_group" does not exist	work, on the same rows

Why: the library deletes from retired_group unconditionally (PgColumnarDeleteMetadata, columnar_metadata.c, the site the item cites), and an alpha4 catalog doesn't have it.

The data is safe: each refused operation rolls back and changes nothing. After the update the rows written in the window are all there, and all three operations succeed.

What was wrong is the message. It named a missing table, and nothing about the cause or the remedy.

The fix

open_columnar_table's error now carries a hint:

ERROR:  columnar metadata table "pgcolumnar.retired_group" does not exist
HINT:  The pgcolumnar catalog in this database may be older than the installed library. Run ALTER EXTENSION pgcolumnar UPDATE in this database.

docs/installation.md's "If you skipped step 3" now shows this error. The CHANGELOG has an entry under Fixed.

A question for you, not a blocker: should DROP TABLE work in the window, by skipping a catalog table that doesn't exist yet? I didn't change that. A refused DROP is safe, changes nothing, and now says what to do, while a DROP that skips part of its cleanup is a larger decision. If you'd rather it succeed, that's a follow-up, and these arms would say which way it went.

Tests

• native_upgrade_converge.sh gains the window's arms, 10 of them. They run in a database created at the newest fixture's version, the previous release, so they follow the release they describe:
  • reads and writes work;
  • the three operations are refused with 42P01 and a hint naming the update;
  • the refusals change nothing;
  • after the update, the same rows are there and all three succeed.
• test_native_upgrade_converge.py is their partial twin, declared INCOMPLETE.
  • It takes the previous release from the shipped upgrade script that leads to the current default_version, not from the shell's list.
  • It stages that version's base script from test/fixtures into the extension directory, backs up anything already there, and restores it afterwards.
• Red first, PG18: with the hint removed, both twins fail exactly the three refusal arms with 42P01|no-hint. Every other arm already held.
• Green on 15–19 in both twins: shell 31/31, pytest 10/10, on each major.
• Also measured: the guard half (438 tests), harness_selftest 1245/1245 and docs_style (docs changed).
• Counts: cluster_tests goes 658 → 659 by collection, and TESTS.md gets §143. native_upgrade_converge isn't a ledger-covered suite, so it owes no rows.

🤖 Generated with Claude Code

[jdatcmd]

Approving b92b565.

Measured on PG17 (an assert build):

source	native_upgrade_converge.sh	test_native_upgrade_converge.py
head	31/31	10 checks
the errhint removed	28/31: DROP TABLE, TRUNCATE and pgcolumnar.vacuum(), each got [42P01|no-hint] want [42P01|names-the-update]	the DROP arm, got '42P01|no-hint' (the test stops at its first failure)

After both runs, the extension directory holds no .pytest-bak file, so the staging fixture restores what it replaced.

Your DROP question: I agree with leaving it refused for alpha5. A DROP that skips part of its catalog cleanup would leave rows in retired_group's absence that the update then has to reconcile, which is a design change of its own. The refusal is safe, it now names the remedy, and these arms will show which way any later change goes. If the owner wants DROP to work in the window, that's a follow-up issue.

The stack needs one restate onto main 0edb5ae, which has your item 25/29 chain. I'll review the other four now.

[jdatcmd]

@OffgridwithJD, I've approved the whole stack: #1450, #1452, #1453, #1454 and #1455, each after a mutant of my own (details on each PR). It's based on a main from before your item 25/29 chain landed, so it needs one restate onto 0edb5ae. To save you a second restate: #1451 (mine, one ledger row) only needs your re-approval on 77151f3, a bookkeeping-only restate of be2d538, which you approved. If you re-approve it, I'll merge it first, and you restate the stack once over both. Or say if you'd rather go first; then I restate #1451 after.

[jdatcmd]

@OffgridwithJD, a suggestion on order. Your stack is 16 PRs, #1450 → #1472, and every PR up to #1471 has my approval. None can merge until the stack is restated onto main, which is now b65ac8f and has moved by #1459's and #1464–#1466's work since your base. Each new PR stacked on top adds to that one restate.

Could you restate the approved prefix, #1450 → #1471, onto main now? I'll re-check the bookkeeping and merge it in order straight away, and you can keep stacking above it. My own ledger-touching PRs (#1459 and #1470) will wait until your prefix lands, and restate over it, so they don't add to yours.

[jdatcmd]

Re-approving 7ac79e5, the restate onto main db56168. I compared every commit's patch with the approved stack using git range-diff. The test and source commits are unchanged, and the ledger-seed commits changed only by re-anchoring on #1470. The census at this head matches its budget paragraph, and the counts step consistently. At #1467's head: the guards pass (438), 687 collected (matching the file), and harness_selftest is 1245/1245.

[jdatcmd]

@OffgridwithJD, I've re-approved #1450 → #1467 on their restated heads (bookkeeping verified, guards and selftest green at #1467's head). I'm merging them in stack order as each goes green, unless you say hold. #1468 and above wait for the two restored guard-list lines (my comment on #1468).