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

CLAUDE.md

@@ -37,16 +37,35 @@ 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.
+
 ## 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,23 @@
+0.2.3
+-----
+Fix backwards pg_class.relkind mapping (c/f/m) in relation__kind() and
+relation__relkind(). Per pg_class.h the correct mapping is 'c' = composite
+type, 'f' = foreign table, 'm' = materialized view; releases through 0.2.2 had
+these three arms reversed.
+
+The 0.2.3 update also rebuilds the catalog views (`_cat_tools.pg_class_v` and its
+dependents) so they survive a binary `pg_upgrade`. To binary-`pg_upgrade` a
+cluster running a cat_tools older than 0.2.3 on PostgreSQL < 12, first
+`ALTER EXTENSION cat_tools UPDATE` to 0.2.3 (or newer): the pre-0.2.3 views still
+carry catalog columns (`relhasoids`/`relhaspkey`) that PG 12+ removed, so an
+upgrade without updating first fails.
+
+That rebuild uses `DROP`+`CREATE` without `CASCADE`, so if you have your own
+object depending on `cat_tools.pg_class_v` (or the objects rebuilt with it —
+`cat_tools.column`, `cat_tools.pg_class()`, the `_cat_tools.*` views) the update
+fails with a dependency error until you drop it first; recreate it afterward.
+
+
 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,26 @@ 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 when
+updating to 0.2.3.
+
+=== Binary `pg_upgrade` to PostgreSQL 12+ from cat_tools older than 0.2.3
+
+Update the extension to 0.2.3 (or newer) on the *old* cluster first, then run
+binary `pg_upgrade`. Pre-0.2.3 catalog views reference `pg_class`/`pg_attribute`
+columns removed in PG12+, so `pg_upgrade` fails otherwise. See the 0.2.3 entry in
+HISTORY.asc for details.
+
+=== Updating to 0.2.3 drops and recreates some public views
+
+The 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 have your own objects depending on any of these, the update
+fails until you drop yours first; recreate them afterward. 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,104 @@
+# 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
+
+- **pg_upgrade across cat_tools < 0.2.3 on PostgreSQL < 12.** To binary-`pg_upgrade`
+  a cluster running a cat_tools older than 0.2.3, first
+  `ALTER EXTENSION cat_tools UPDATE` to 0.2.3 (or newer). The 0.2.3 update rebuilds
+  the catalog views (`_cat_tools.pg_class_v` and its dependents) so they survive the
+  upgrade; pre-0.2.3 views still carry catalog columns (`relhasoids`/`relhaspkey`)
+  that PG 12+ removed, so upgrading without updating first fails. Mention this in the
+  release notes for any release that people may be running when they cross the PG 11 →
+  12+ boundary.
+- **The 0.2.3 view rebuild is `DROP`+`CREATE` without `CASCADE`.** Updating to 0.2.3
+  fails with a dependency error if a user object depends on `cat_tools.pg_class_v` (or
+  the objects rebuilt with it — `cat_tools.column`, `cat_tools.pg_class()`, the
+  `_cat_tools.*` views); the user must drop and recreate their object around the update.
+  No-`CASCADE` is intentional — surface a clear error rather than silently drop user
+  objects. See README.asc "Updating the extension".

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