ci: wire up extension-update-test (0.1.0 -> stable)

[jnasbyupgrade]

Stacked on #18 (link 3/3 of the update+upgrade testing effort -- completes
checklist item 7 of advanced-extension-testing.md §10: CI wiring for the
extension-update test, on top of #18's local test/install/load.sql
three-mode machinery).

What this adds

• bin/test_existing -- the committed, parameterized
  install→guard→update→assert→run-suite script (subcommands:
  plant-guard, update, run-suite, update-scenario, diff-fresh),
  modeled on Postgres-Extensions/cat_tools's bin/test_existing.
  object_reference has only one real historical PGXN release (0.1.0) and
  only one update script (a direct hop to stable, no already-tagged
  intermediate landing version), so cat_tools's prepare-old /
  update-check / update-check-version subcommands (built for testing
  multiple historical origins, and for landing on an already-tagged
  version where full parity is permanently unattainable) aren't built
  here -- see the script's own header for the reasoning.
• bin/structural_diff / bin/structural_diff.sql -- a generic
  per-extension structural comparison tool (function/view/table
  definitions, comments, ACLs, driven off pg_depend's deptype = 'e'
  membership edge), copied near-verbatim from cat_tools: the SQL file
  is already written generically with no cat_tools-specific object names,
  so it applies to object_reference as-is. Wired into update-scenario
  as assert_matches_fresh, satisfying the doc's checklist item 12
  ("structurally compare fresh vs. update before trusting it").
• A new extension-update-test CI job: installs 0.1.0 (+ its
  since-dropped count_nulls dependency), plants + proves the dependency
  guard, ALTER EXTENSION UPDATEs to the current version, structurally
  compares against a fresh stable install, then runs the full suite in
  existing mode (TEST_LOAD_SOURCE=existing CONTRIB_TESTDB=<db> EXTRA_REGRESS_OPTS=--use-existing PGXNTOOL_ENABLE_TEST_BUILD=no).
  Runs on a single PostgreSQL major (the newest supported), not the full
  matrix -- 0.1.0's install script has no identified PG-version floor, so
  crossing it against every major would multiply job count with no added
  coverage.
• all-checks-passed's needs: list updated to include the new job.
• A top-of-file "Test strategy" comment in ci.yml, per §6's guidance.

A real per-repo adaptation from the cat_tools reference

bin/test_existing's dynamic version assertion derives the current
version from make -s print-EXTENSION_object_reference_VERSION, not
print-PGXNVERSION (which cat_tools's own script uses, and which the
advanced-extension-testing doc's §6d example also shows). object_reference
has already adopted the stable pseudo-version scheme (#18):
PGXNVERSION (meta.mk) is frozen at 0.1.0, the last real numbered PGXN
release used for git tagging/dist, and no longer tracks the current
build's default_version once stable is in play. cat_tools's
PGXNVERSION and default_version still happen to be the same value, so
this divergence wasn't visible there. Confirmed directly:
make -s print-PGXNVERSION → 0.1.0, make -s print-EXTENSION_object_reference_VERSION → stable (the correct one to
assert against).

pg_upgrade legs (§6c/§6c-bis): explicitly deferred, not omitted

No binary pg_upgrade job is added in this PR. Checked directly: neither
object_reference's current nor 0.1.0 install script has a view or function
that SELECT *s over a system catalog (the doc's §7 risk -- catalog
columns added/exposed/removed between PostgreSQL majors breaking a stored
view definition across pg_upgrade). object_reference's own tables/views
are ordinary user objects, so that specific risk is low here. Given that,
and that this is already the third PR in a stack, I judged the heavier
pg-upgrade-test/pg-upgrade-stepwise legs not worth building
preemptively -- left as explicitly-noted future work (see the ci.yml
"Test strategy" comment) rather than silently skipped.

Verification

• make lint clean.
• Ran the full update-scenario flow locally against a real PostgreSQL 17
  cluster before pushing: 0.1.0 install → guard planted + proven → update
  to stable → structural diff clean → full suite green in existing
  mode (7/7 pgTAP files passing).
• EXIT-trap verification (per this container's own gotcha doc on
  RETURN vs EXIT traps under errexit): deliberately corrupted a
  comment on a real object_reference table post-update to force a genuine
  structural divergence, then ran diff-fresh directly. Confirmed (a) the
  script exited non-zero (FAIL: structural diff ..., exit code 1), and
  (b) the scratch *__fresh_ref reference database was still dropped by
  the EXIT trap despite the failure not being the trap-registering
  subshell's last command. Also confirmed via trap -p EXIT that the
  scratch database name is baked into the trap as a literal at
  registration time, not re-read from the variable when the trap fires.
• CI on this branch will be monitored to green before calling this done
  (per this repo's own CLAUDE.md).

Test plan

• make lint
• Local update-scenario dry run against a real cluster
• EXIT-trap deliberate-failure verification
• CI green on this PR (extension-update-test job actually exercised,
  not just YAML-parsed)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c5ee09a8-2e7e-4513-9532-80b1345f7058

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}