cat_tools 0.2.3: fix pg_class.relkind mapping and the pg_upgrade update path

.github/workflows/ci.yml

@@ -153,6 +153,14 @@ jobs:
           if [ -z "$INSTALLED" ] || [ -z "$EXPECTED" ] || [ "$INSTALLED" != "$EXPECTED" ]; then
             echo "FAIL: installed='$INSTALLED' expected='$EXPECTED'"; exit 1
           fi
+          # Verify the 0.2.2->0.2.3 view rebuild actually FIRED (not just ran). On
+          # PG10 the 0.2.0->0.2.2 path leaves _cat_tools.pg_class_v carrying
+          # relhasoids (the buggy `!= ANY` no-op never stripped it), and the
+          # conditional 0.2.2->0.2.3 repair must detect that and rebuild the view
+          # without it. This is the REAL broken path: on PG12+ relhasoids never
+          # existed, so only PG10 exercises the rebuild. ON_ERROR_STOP makes the
+          # RAISE EXCEPTION fail the step.
+          psql -v ON_ERROR_STOP=1 -c "DO \$\$ BEGIN IF EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = '_cat_tools.pg_class_v'::regclass AND attname = 'relhasoids' AND NOT attisdropped AND attnum > 0) THEN RAISE EXCEPTION 'pg_class_v still exposes relhasoids after update to current -- 0.2.2->0.2.3 rebuild did not fire'; END IF; END \$\$"
       - name: Test update 0.2.1 → 0.2.2
         run: |
           # PG takes the shortest update path, so the 0.2.0->current test above goes

CLAUDE.md

@@ -37,16 +37,38 @@ Never repeat the same comment verbatim in adjacent code — write it once and re
 
 **Always open PRs against the main repo** (`Postgres-Extensions/cat_tools`), not a fork.
 
+## Pull request descriptions
+
+The maintainer builds the squash commit message from the PR description, so the
+**opening** of the description is used directly as the basis for that commit message.
+Write it accordingly:
+
+- Make the opening stand alone as a good commit message: no leading header/title line
+  (the PR title is the subject), concise, self-contained. Multiple paragraphs are fine.
+- Lead with the substantive change and why. Keep incidental changes (minor doc tweaks,
+  dependency/action version bumps, small cleanups) OUT of the opening — put them lower
+  or omit them; the diff carries those details for anyone who wants them.
+- Do NOT add a marker delimiting the "commit message" from "the rest". Just let the
+  opening carry its own weight, with any extra context following after it.
+- Do NOT hard-wrap paragraphs: write each paragraph as a single long line (blank line
+  between paragraphs). Hard-wrapping at ~80 columns conflicts with how GitHub builds the
+  squash commit message from the description.
+
 ## SQL file conventions
 
 Rules for what to track in git:
 
 0. If a `.sql.in` file exists, track the `.sql.in` and **not** the corresponding `.sql`.
 1. If no `.sql.in` exists, track the `.sql` directly (e.g. historical pre-0.2.0 files).
-2. Version-specific install scripts (e.g. `sql/cat_tools--0.2.2.sql.in`) MUST be tracked.
-3. Update scripts (e.g. `sql/cat_tools--0.2.1--0.2.2.sql.in`) MUST be tracked.
-4. The current version'''s install script (e.g. `sql/cat_tools--0.2.2.sql.in`) is generated
-   by `make` from `sql/cat_tools.sql.in`, but MUST still be tracked (rule 2 applies).
+2. Version-specific install scripts (e.g. `sql/cat_tools--0.2.2.sql.in`) are tracked BY
+   DEFAULT. They enable update testing (install an old version, `ALTER EXTENSION UPDATE`,
+   verify) and, because a new MAJOR PostgreSQL version can unpredictably break installing
+   an OLDER extension version, keeping old versions committed lets CI catch when a version
+   stops installing on a newer PG.
+   See https://github.com/Postgres-Extensions/pgxntool/issues/51.
+3. Update scripts (e.g. `sql/cat_tools--0.2.1--0.2.2.sql.in`) MUST be tracked — they are
+   essential to the update path and have no substitute.
+4. EXCEPTION to rule 2: a version that changes little AND ships no nontrivial update-path machinery MAY omit its generated install script (little test-coverage value; it is regenerated from `sql/cat_tools.sql.in` at build time). Track it whenever the version carries meaningful changes or a nontrivial update script — a complex update warrants the committed install script for update-test coverage and provenance.
 5. Version-specific files MUST NEVER be edited manually — always edit `sql/cat_tools.sql.in`
    and regenerate.
 

HISTORY.asc

@@ -1,3 +1,15 @@
+0.2.3
+-----
+Fix the backwards `pg_class.relkind` mapping (c/f/m) in `relation__kind()` and
+`relation__relkind()`. Also fix binary `pg_upgrade` for databases updated from
+0.2.0/0.2.1, whose catalog views kept columns removed in PostgreSQL 12+
+(`relhasoids`/`relhaspkey`): to `pg_upgrade` such a cluster to PG12+, first
+update the extension to 0.2.3, which rebuilds those views. The rebuild drops and
+recreates public views (`pg_class_v`, `column`, `pg_class()`), so drop any of
+your own dependent objects first. See the README "Updating the extension"
+section and https://github.com/Postgres-Extensions/cat_tools/pull/42.
+
+
 0.2.2
 -----
 Compatibility release: fixes broken installs on PostgreSQL 11 and 12+, and

META.in.json

@@ -14,7 +14,7 @@
     "name": "cat_tools",
 
     "X_comment": "REQUIRED. Version of the distribution. http://pgxn.org/spec/#version",
-    "version": "0.2.2",
+    "version": "0.2.3",
 
     "X_comment": "REQUIRED. Short description of distribution.",
     "abstract": "Tools for interfacing with the Postgres catalog",
@@ -37,7 +37,7 @@
             "file": "sql/cat_tools.sql",
 
             "X_comment": "REQUIRED. Version the extension is at.",
-            "version": "0.2.2",
+            "version": "0.2.3",
 
             "X_comment": "Optional: \"abstract\": Description of the extension.",
             "abstract": "Tools for interfacing with the catalog",

META.json

@@ -14,7 +14,7 @@
     "name": "cat_tools",
 
     "X_comment": "REQUIRED. Version of the distribution. http://pgxn.org/spec/#version",
-    "version": "0.2.2",
+    "version": "0.2.3",
 
     "X_comment": "REQUIRED. Short description of distribution.",
     "abstract": "Tools for interfacing with the Postgres catalog",
@@ -37,7 +37,7 @@
             "file": "sql/cat_tools.sql",
 
             "X_comment": "REQUIRED. Version the extension is at.",
-            "version": "0.2.2",
+            "version": "0.2.3",
 
             "X_comment": "Optional: \"abstract\": Description of the extension.",
             "abstract": "Tools for interfacing with the catalog",

README.asc

@@ -25,6 +25,30 @@ This is very much a work in progress. If it doesn't do something you need, pleas
 
 Works on Postgres 9.3 and above.
 
+== Updating the extension
+
+Usually just run `ALTER EXTENSION cat_tools UPDATE`. Two special cases apply to a
+database that reached 0.2.2 via the *0.2.0/0.2.1 update scripts*, whose catalog
+views are broken (they still reference `pg_class`/`pg_attribute` columns —
+`relhasoids`, `relhaspkey` — that a fresh 0.2.2 install correctly omits). A fresh
+0.2.2 install has correct views and is unaffected by either case.
+
+=== Binary `pg_upgrade` to PostgreSQL 12+ from such a database
+
+Update the extension to 0.2.3 (or newer) on the *old* cluster first, then run
+binary `pg_upgrade`. The broken views reference catalog columns removed in PG12+,
+so `pg_upgrade` fails otherwise; the 0.2.2→0.2.3 update repairs them first. See
+the 0.2.3 entry in HISTORY.asc for details.
+
+=== Updating such a database to 0.2.3 rebuilds some public views
+
+*Only* when the views are broken, the 0.2.2→0.2.3 update `DROP`+`CREATE`s (without
+`CASCADE`) these public objects: `cat_tools.pg_class_v`, `cat_tools.column`, and
+the `cat_tools.pg_class(regclass)` function. If you created your own objects
+depending on any of these, drop them before updating and recreate them afterward;
+the update aborts otherwise. A fresh 0.2.2 install's views are left untouched, so
+its dependents are unaffected. See the 0.2.3 entry in HISTORY.asc for details.
+
 == Data Types
 
 * `object_type` - Descriptive names for every type of Postgres object (table, operator, rule, etc)

RELEASE.md

@@ -0,0 +1,97 @@
+# Releasing cat_tools
+
+cat_tools builds on pgxntool (https://github.com/Postgres-Extensions/pgxntool);
+the release machinery (`make tag`, `make dist`) lives in `pgxntool/base.mk`. These
+steps cut a new release.
+
+## 1. Pre-release checks
+- [ ] Open issues/PRs for this release reviewed, merged or deferred.
+- [ ] CI green on all supported PostgreSQL versions (the `all-checks-passed` job on master).
+- [ ] Locally: `make verify-results` passes. It depends on `test` (so it runs the suite
+      first, then gates on the results). `make test` alone is non-gating — pgxntool marks
+      `installcheck` `.IGNORE`, so it never returns non-zero on a regression; only
+      `verify-results` (which inspects `test/regression.diffs`) is a real gate.
+
+## 2. Decide the version and what to track
+- [ ] Pick the new version (semantic versioning).
+- [ ] **Minor change? Consider NOT committing the generated versioned install script.**
+      If this release makes only fairly minor changes (unlikely to cross a PostgreSQL
+      supported-version boundary), decide whether to omit the generated
+      `sql/cat_tools--<version>.sql.in` — it has little update-test-coverage value and
+      omitting it keeps the repo smaller (it is regenerated from `sql/cat_tools.sql.in`
+      at build time). The update script (`sql/cat_tools--<prev>--<version>.sql.in`) is
+      ALWAYS committed. See CLAUDE.md "SQL file conventions".
+
+## 3. Update version + changelog
+
+> **⚠️ CRITICAL — you are temporarily leaving the `stable` pseudo-version.** Master's
+> `default_version` normally sits at the `stable` pseudo-version so that source edits
+> regenerate `cat_tools--stable.sql` and never a frozen released file. Stamping a real
+> version here points the generated current-version file at `cat_tools--<version>`. The
+> moment this release is merged you **MUST** flip `default_version` back to `stable` on
+> master (step 6). If you forget, the next source edit on master will regenerate — and
+> corrupt — the just-released version's install file.
+
+- [ ] Bump `default_version` in `cat_tools.control` (bumped by hand).
+- [ ] Bump the version in `META.in.json` — the source of truth is
+      `provides.cat_tools.version` (also update the top-level `version`); `META.json`,
+      `control.mk`, and `meta.mk` (which feeds `PGXNVERSION`) regenerate via `make`.
+- [ ] Advance `release_status` in `META.in.json` as appropriate (unstable → testing →
+      stable).
+- [ ] Add/finish the update script `sql/cat_tools--<prev>--<version>.sql.in`; confirm
+      `ALTER EXTENSION cat_tools UPDATE` from the previous version reaches the new one,
+      on multiple PG majors.
+- [ ] Stamp `HISTORY.asc`: the top `STABLE` section accumulates user-facing changes as
+      PRs land; at release, rename that header to the new version number.
+
+## 4. Verify
+- [ ] `make verify-results` green (it runs `test` first, then gates on the results).
+- [ ] From a clean checkout (or `git archive` of the tag): `make && make install`
+      regenerates and installs cleanly and `CREATE EXTENSION cat_tools;` reports the new
+      version — confirms a PGXN consumer can build from the tracked sources alone. (This
+      mirrors what `make dist` ships, since it archives the tag: committed files only, so
+      any omitted generated install script is regenerated on the consumer's side.)
+
+## 5. Tag and distribute
+- [ ] Commit the release changes; working tree must be clean — `make tag` aborts with
+      "Untracked changes!" on a dirty tree.
+- [ ] `make tag` — creates a git tag named exactly the version, UNPREFIXED (e.g. `0.2.3`,
+      matching the existing `0.2.2` tag; no `v` prefix), taken from `PGXNVERSION`, and
+      pushes it to `origin`. It is idempotent when the tag already points at HEAD, and
+      errors if the tag exists on a different commit. To move an existing tag use
+      `make forcetag` (= `make rmtag` then `make tag`); `make rmtag` deletes the tag
+      locally and on `origin`.
+- [ ] `make dist` — depends on `tag` (and builds the HTML docs), then
+      `git archive`s the tag into `../cat_tools-<version>.zip` (parent directory).
+      Because it archives the tag, only committed files are included. If a `.gitattributes`
+      exists it must be committed, or `dist` aborts (git archive only honors
+      `export-ignore` for committed files). `make forcedist` = `forcetag` + `dist`.
+- [ ] Upload the `../cat_tools-<version>.zip` to PGXN (manual).
+
+## 6. Return master to `stable` (CRITICAL — do not skip)
+- [ ] As soon as the release is merged, flip `default_version` back to the `stable`
+      pseudo-version on master (`cat_tools.control` + `META.in.json`), open a new top
+      `STABLE` section in `HISTORY.asc`, and re-seed a fresh
+      `sql/cat_tools--<this-release>--stable.sql.in` update script for the next cycle.
+      Leaving master stamped at the real version means the next source edit regenerates
+      and corrupts the released version's install file.
+- [ ] `rm` any stale generated `sql/cat_tools--<released-version>.sql.in` /
+      `cat_tools--<released-version>.sql` left in the tree — once `default_version` is
+      `stable`, `make` no longer regenerates them, so they are one-time cleanup.
+
+> The persistent `stable` pseudo-version (a permanent version literally named `stable`,
+> with a live `sql/cat_tools--<last-release>--stable.sql.in` update script that every
+> source fix targets) decouples fixes from version bumps. The machinery is built into
+> `sql.mk`; it lands immediately after the 0.2.3 release, so 0.2.3 itself is the last
+> release cut before the scheme exists — steps 3/6 above describe the flow from the
+> next release onward.
+
+## Notes and caveats
+
+- **0.2.3 catalog-view repair / `pg_upgrade` caveat.** Databases updated from
+  0.2.0/0.2.1 hold broken catalog views that fail binary `pg_upgrade` to PostgreSQL
+  12+ until the extension is updated to 0.2.3 (the update rebuilds them, dropping and
+  recreating the public `pg_class_v`/`column`/`pg_class()` objects without `CASCADE`).
+  Surface this in the release notes when people may cross the PG 11 → 12+ boundary. See
+  README.asc "Updating the extension" and
+  https://github.com/Postgres-Extensions/cat_tools/pull/42.

cat_tools.control

@@ -1,4 +1,4 @@
 comment = 'Tools for intorfacing with the catalog'
-default_version = '0.2.2'
+default_version = '0.2.3'
 relocatable = false
 schema = 'cat_tools'

control.mk

@@ -1,6 +1,6 @@
 EXTENSIONS += cat_tools
 EXTENSION_SQL_FILES += sql/cat_tools.sql
-EXTENSION_cat_tools_VERSION := 0.2.2
+EXTENSION_cat_tools_VERSION := 0.2.3
 EXTENSION_cat_tools_VERSION_FILE	= sql/cat_tools--$(EXTENSION_cat_tools_VERSION).sql
 EXTENSION_VERSION_FILES		+= $(EXTENSION_cat_tools_VERSION_FILE)
 $(EXTENSION_cat_tools_VERSION_FILE): sql/cat_tools.sql cat_tools.control