Add new functions, enums

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
   test:
     strategy:
       matrix:
-        pg: [18, 17, 16, 15, 14, 13, 12, 11, 10]
+        pg: [18, 17, 16, 15, 14, 13, 12]
     name: 🐘 PostgreSQL ${{ matrix.pg }}
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
@@ -25,27 +25,48 @@ jobs:
         run: pg-start ${{ matrix.pg }}
       - name: Check out the repo
         uses: actions/checkout@v6
-      - name: Install rsync
-        run: apt-get install -y rsync
+      - name: Install rsync and server headers
+        # postgresql-server-dev-NN provides catalog/pg_class.h, which
+        # test/gen-relkinds.sh reads for the relkind drift check in
+        # test/sql/relation__.sql.
+        run: apt-get install -y rsync postgresql-server-dev-${{ matrix.pg }}
       - name: Test on PostgreSQL ${{ matrix.pg }}
-        run: make test
+        run: |
+          # Fail if the relkind drift source is empty (headers missing): the
+          # drift check must actually run on every version, not pass silently.
+          make check-relkind-source
+          make test
+          # `make test` never exits non-zero on regressions (pgxntool marks
+          # installcheck `.IGNORE`), so gate the build explicitly on the
+          # pgtap/regression.diffs check or failures would pass silently.
+          make verify-results
 
   pg-upgrade-test:
     strategy:
       matrix:
         include:
-          - old_pg: "10"
-            new_pg: "11"
+          # old_pg=10: the FULL real-world journey for a user on old PostgreSQL +
+          # old cat_tools. 0.2.0 installs on PG10; the BRIDGE update to 0.2.2
+          # (run on PG10, before pg_upgrade) recreates the views with the
+          # pg_upgrade-safe omit_column fix so the binary pg_upgrade to a newer
+          # cluster succeeds; then update to current + run the suite. This proves
+          # a 0.2.2 reached via the bridge update (not a fresh install) survives
+          # pg_upgrade and updates to latest.
           - old_pg: "10"
             new_pg: "18"
-          - old_pg: "11"
-            new_pg: "12"
-          - old_pg: "11"
-            new_pg: "18"
+            old_install: "0.2.0"
+            bridge_to: "0.2.2"
+          # old_pg>=11: 0.2.0/0.2.1 do not install on PG11+, and such users are
+          # already on 0.2.2+. Install 0.2.2 directly (no bridge), pg_upgrade,
+          # then update to current.
           - old_pg: "12"
             new_pg: "13"
+            old_install: "0.2.2"
+            bridge_to: ""
           - old_pg: "12"
             new_pg: "18"
+            old_install: "0.2.2"
+            bridge_to: ""
     name: 🔄 Binary pg_upgrade ${{ matrix.old_pg }} → ${{ matrix.new_pg }}
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
@@ -72,8 +93,17 @@ jobs:
         run: apt-get install -y rsync
       - name: Install cat_tools into old cluster
         run: make install
-      - name: Install cat_tools extension into upgrade test database
-        run: psql -c "CREATE EXTENSION cat_tools"
+      - name: Prepare the old cluster (install + bridge + dependency guard)
+        # prepare-old installs cat_tools at old_install and, when bridge_to is set
+        # (old_pg=10), ALTER EXTENSION UPDATEs to it BEFORE pg_upgrade -- the
+        # bridge that makes the views pg_upgrade-safe (see prepare-old in the
+        # script). It then plants + proves the dependency guard so the later
+        # existing-mode run cannot silently drop+reinstall and test a fresh
+        # install instead. The extension is always older than current, so the
+        # post-upgrade ALTER EXTENSION UPDATE has real work to do.
+        run: >-
+          test/ci/existing_mode.sh prepare-old cat_tools_upgrade
+          "${{ matrix.old_install }}" "${{ matrix.bridge_to }}"
       - name: Install PostgreSQL ${{ matrix.new_pg }}
         run: apt-get install -y postgresql-${{ matrix.new_pg }} postgresql-server-dev-${{ matrix.new_pg }}
       - name: Install cat_tools into new cluster
@@ -100,32 +130,37 @@ jobs:
                       /var/lib/postgresql/${{ matrix.new_pg }}/test/pg_upgrade_output.d \
                       -name '*.log' 2>/dev/null | sort | xargs -r tail -n +1; exit 1; }
           pg_ctlcluster ${{ matrix.new_pg }} test start
-      - name: Verify extension version after upgrade
-        run: |
-          VERSION=$(psql -tAc "SELECT extversion FROM pg_extension WHERE extname = 'cat_tools'")
-          echo "Extension version: ${VERSION:-<not found>}"
-          echo "$VERSION" | grep -q "0.2.2"
-      - name: Run test suite on upgraded cluster
-        run: make test
-      # TODO: also test ALTER EXTENSION cat_tools UPDATE here, once the
-      # pg_upgrade source versions (e.g. 0.2.0) can install on the new_pg
-      # version. Currently the pre-0.2.2 install scripts fail on PG11+ so
-      # we cannot pg_upgrade from a cluster that has them installed.
+      - name: Update the pg_upgraded extension to the current version
+        # Exercises ALTER EXTENSION UPDATE on genuinely pg_upgraded objects (the
+        # 0.2.2 extension binary pg_upgrade just migrated), running the
+        # version-to-version scripts up to the current version. The 0.2.2 -> 0.3.0
+        # script uses ALTER TYPE ... ADD VALUE, which is why new_pg must be >= 12.
+        run: test/ci/existing_mode.sh update cat_tools_upgrade
+      - name: Run the suite against the pg_upgraded database (existing mode)
+        # run-suite asserts the version, re-proves the dependency guard still
+        # blocks a non-CASCADE drop (i.e. it survived pg_upgrade), then runs the
+        # suite against the REAL pg_upgraded + updated database via --use-existing
+        # (so pg_regress does not drop/recreate it) -- a plain fresh `make test`
+        # would silently test a fresh install instead of the migrated objects.
+        run: test/ci/existing_mode.sh run-suite cat_tools_upgrade
 
   extension-update-test:
     strategy:
       matrix:
-        # Restricted to PG10 only because the pre-0.2.2 install scripts use
-        # unqualified SELECT * in views over pg_attribute/pg_constraint:
-        #   - PG11 added attmissingval (pseudo-type anyarray) to pg_attribute,
-        #     so cat_tools--0.2.0.sql and cat_tools--0.2.1.sql fail on PG11+
-        #     with "column attmissingval has pseudo-type anyarray".
-        #   - PG12 made the `oid` system column visible in SELECT *, causing
-        #     "column oid specified more than once" on PG12+.
-        # PG10 is the only version where both old scripts install cleanly.
-        # TODO: when a future version's install script works on PG11+, expand
-        # this matrix and add tests for the upgrade path from 0.2.2 onwards.
-        pg: [10]
+        # PG12+: exercise the WIDEST update path we support — CREATE EXTENSION at
+        # the 0.2.2 backward-compat floor, ALTER EXTENSION UPDATE to the CURRENT
+        # version, and run the full suite against the updated database. 0.2.2 is
+        # the floor because the 0.2.0/0.2.1 install scripts fail on PG11+/PG12+;
+        # PG12 is the PostgreSQL floor because the update runs
+        # `ALTER TYPE ... ADD VALUE`, which PG11 and below cannot run in an
+        # extension update script (lifted in PG12).
+        # PG10: the ONLY version where the pre-0.2.2 install scripts still load,
+        # so the only place the 0.2.0->0.2.2 and 0.2.1->0.2.2 update scripts can
+        # be exercised. They target 0.2.2 (not the current version) and use no
+        # ALTER TYPE ... ADD VALUE, so they run on PG10. The PG10 leg runs only
+        # those two checks — not the current-version suite (0.3.0 needs PG12+).
+        # See the per-step `if` guards.
+        pg: [18, 17, 16, 15, 14, 13, 12, 10]
     name: ⬆️ Extension update test on PostgreSQL ${{ matrix.pg }}
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
@@ -134,27 +169,36 @@ jobs:
         run: pg-start ${{ matrix.pg }}
       - name: Check out the repo
         uses: actions/checkout@v6
+      - name: Install rsync and server headers
+        # server-dev provides catalog/pg_class.h for the relkind drift check
+        # (see the "test" job); required so check-relkind-source below passes.
+        # PG10 runs only the legacy-script checks (no suite), so it needs no headers.
+        if: matrix.pg != '10'
+        run: apt-get install -y rsync postgresql-server-dev-${{ matrix.pg }}
       - name: Install rsync
+        if: matrix.pg == '10'
         run: apt-get install -y rsync
       - name: Install cat_tools (all versions)
         run: make install
-      - name: Test upgrade from 0.2.0 (direct 0.2.0→0.2.2 path)
-        run: |
-          psql -c "CREATE EXTENSION cat_tools VERSION '0.2.0'"
-          psql -c "ALTER EXTENSION cat_tools UPDATE"
-          VERSION=$(psql -tAc "SELECT extversion FROM pg_extension WHERE extname = 'cat_tools'")
-          echo "Version after 0.2.0 upgrade: ${VERSION:-<not found>}"
-          echo "$VERSION" | grep -q "0.2.2"
-      - name: Test upgrade from 0.2.1 (0.2.1→0.2.2 path)
+      - name: Test pre-0.2.2 update scripts (0.2.0/0.2.1 → 0.2.2, PG10 only)
+        # 0.2.0/0.2.1 install only on PG10; their update scripts target 0.2.2 (not
+        # the current version) and are otherwise never exercised. PG takes the
+        # shortest path, so 0.2.0 → 0.2.2 uses the direct 0.2.0--0.2.2 script;
+        # starting at 0.2.1 exercises the 0.2.1--0.2.2 script directly. update-check
+        # asserts each lands on 0.2.2. No suite runs (0.3.0 needs PG12+).
+        if: matrix.pg == '10'
         run: |
-          createdb cat_tools_from_021
-          psql -d cat_tools_from_021 -c "CREATE EXTENSION cat_tools VERSION '0.2.1'"
-          psql -d cat_tools_from_021 -c "ALTER EXTENSION cat_tools UPDATE"
-          VERSION=$(psql -d cat_tools_from_021 -tAc "SELECT extversion FROM pg_extension WHERE extname = 'cat_tools'")
-          echo "Version after 0.2.1 upgrade: ${VERSION:-<not found>}"
-          echo "$VERSION" | grep -q "0.2.2"
-      - name: Run test suite on updated extension
-        run: make test
+          test/ci/existing_mode.sh update-check cat_tools_from_020 0.2.0 0.2.2
+          test/ci/existing_mode.sh update-check cat_tools_from_021 0.2.1 0.2.2
+      - name: Update 0.2.2 → current and run the suite (existing mode, PG12+)
+        # update-scenario creates a real database at 0.2.2, plants + proves the
+        # dependency guard, ALTER EXTENSION UPDATEs to the current version, and
+        # runs the suite against that updated database in existing mode (asserting
+        # the version and that the guard still blocks a drop). Reusing the SAME
+        # suite and expected output asserts the updated database behaves
+        # identically to a fresh install.
+        if: matrix.pg != '10'
+        run: test/ci/existing_mode.sh update-scenario cat_tools_update 0.2.2
 
   # A single stable check name for use as a required status check in branch
   # protection rules. Matrix jobs produce check names like "🐘 PostgreSQL 14"

.gitignore

@@ -19,9 +19,6 @@ control.mk
 # built targets
 # Note: Version-specific files (sql/*--*.sql) are now tracked in git and should be committed
 
-# test targets
-/test/.build/
-
 # Test artifacts
 results/
 regression.diffs

CLAUDE.md

@@ -2,45 +2,93 @@
 
 ## GitHub CI
 
-After pushing to a branch with an open PR, monitor CI using `gh pr checks --watch` in a background subagent until all jobs pass or a failure is confirmed. Investigate and fix failures immediately rather than leaving them for the user to notice.
+After **every** push, monitor GitHub CI in a background subagent until all jobs pass or a failure is confirmed. Use `gh pr checks <pr> --watch` when the branch has an open PR; otherwise (a branch with no PR yet, or a push to `master`) use `gh run watch` for the pushed commit. Investigate and fix failures immediately rather than leaving them for the user to notice.
+
+(`paths-ignore` in `.github/workflows/ci.yml` skips CI only when the *entire* change set is docs-only — e.g. a docs-only push to `master`, or a PR whose whole diff is `**.md`/`**.asc`. A docs-only commit on a PR that also touches code still triggers CI on the full PR diff. When unsure, check `gh run list` for the pushed commit and monitor whatever run appears; if none does, there is nothing to watch.)
 
 ## Bug Fixes
 
-When fixing a bug, add a comment at the fix site explaining what the bug was and why the fix works. The goal is to prevent re-introducing the bug later.
+Comment the fix where it isn't self-evident, but keep it concise — no novels. Do NOT
+recount the bug's history (what a past version got wrong) UNLESS the same mistake could
+realistically be made again; if it could, briefly state the guard fact that prevents it.
+Never repeat the same comment verbatim in adjacent code — write it once and reference it
+("same as above").
 
 ## Git
 
 **Never delete a branch without explicit user approval.** This includes `git push origin --delete`, `git branch -d`, and `git branch -D`. Always ask first.
 
 **Always open PRs against the main repo** (`Postgres-Extensions/cat_tools`), not a fork.
 
+## References to PRs and issues in committed files
+
+Any reference to a GitHub PR or issue inside a **committed file** (SQL/code comments,
+`.github/workflows/ci.yml` comments, `CLAUDE.md`, `test/install/load.sql`, docs) MUST be a
+full URL, e.g. `https://github.com/Postgres-Extensions/cat_tools/issues/28` — never a bare
+`#28` (a bare number is meaningless when the file is read outside GitHub). Referencing by
+number is fine only in GitHub-native text (PR/issue titles and descriptions, review
+comments).
+
 ## 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. Upgrade scripts (e.g. `sql/cat_tools--0.2.1--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).
 5. Version-specific files MUST NEVER be edited manually — always edit `sql/cat_tools.sql.in`
    and regenerate.
 
-## CI: extension-update-test matrix
-
-The `extension-update-test` job in `.github/workflows/ci.yml` is currently restricted to
-`pg: [10]` because that is the only PostgreSQL version where the pre-0.2.2 install scripts
-install cleanly:
-- PG 11 added `attmissingval` (pseudo-type `anyarray`) to `pg_attribute`; the old `SELECT *`
-  in `0.2.0`/`0.2.1` tries to include it directly, failing with "column attmissingval has
-  pseudo-type anyarray".
-- PG 12+ exposed the `oid` system column in `SELECT *`, breaking `0.2.0`/`0.2.1` with
-  "column oid specified more than once".
-
-**When working on a new version:** review and expand this matrix. The new version's install
-script may support more PG versions, enabling testing of the upgrade path from older
-cat_tools versions on newer PostgreSQL.
+## CI: PostgreSQL version support
+
+**Policy:** Never support a fresh install on any PostgreSQL version where the extension
+update path is known to be broken — a version that cannot be updated to is not truly
+supported.
+
+Both PG10 and PG11 are dropped as of 0.3.0. The `ALTER TYPE ... ADD VALUE` statements in
+the update script cannot run inside an extension update script on PG11 or earlier
+(PROCESS_UTILITY_QUERY context); this restriction was lifted in PG12. Because a version
+that cannot be updated to is not truly supported, PG10 and PG11 support is dropped
+entirely. cat_tools 0.3.0 supports PG12+.
+
+### Test-load modes (`TEST_LOAD_SOURCE`)
+
+`test/install/load.sql` installs the suite's dependencies once, committed, before the pgTAP
+suite. The Makefile exports the mode (and update range) as placeholder GUCs via `PGOPTIONS`;
+`TEST_LOAD_SOURCE` must be `fresh`, `update`, or `existing` (anything else is a hard
+parse-time error):
+
+- **fresh** (default): `CREATE EXTENSION cat_tools` at the current version.
+- **update**: `CREATE EXTENSION` at `TEST_UPDATE_FROM` (default `0.2.2`) then
+  `ALTER EXTENSION cat_tools UPDATE` — to `TEST_UPDATE_TO` if set, else to the current
+  version. Running the SAME suite/expected output asserts an updated database behaves
+  identically to a fresh install. `make test-update` is the shorthand.
+- **existing**: the extension is ALREADY installed (by binary `pg_upgrade`, or an
+  `ALTER EXTENSION UPDATE` performed outside the suite). load.sql does not touch it; it only
+  asserts presence + current version and creates the test roles. Pair with
+  `CONTRIB_TESTDB=<db> EXTRA_REGRESS_OPTS=--use-existing` so `pg_regress` runs against that
+  database instead of dropping/recreating a throwaway one.
+
+### CI jobs
+
+- `extension-update-test` exercises the widest update path we support — `0.2.2` → current
+  in `update` mode — on `pg: [12..18]`, plus a PG10-only leg that exercises the pre-0.2.2
+  update scripts (`0.2.0`→`0.2.2` and `0.2.1`→`0.2.2`, which install only on PG10 and target
+  `0.2.2`, not the current version). `0.2.2` is the update-from floor only for backward-compat:
+  the 0.2.0/0.2.1 install scripts fail on PG11+/PG12+. PG12 is the PostgreSQL floor — PG11 and
+  earlier cannot run `ALTER TYPE ... ADD VALUE` in extension update scripts (lifted in PG12).
+- `pg-upgrade-test` binary-`pg_upgrade`s a real database and then runs the suite against it
+  in `existing` mode (`0.2.2` is the oldest version that survives pg_upgrade — pre-0.2.2
+  views reference catalog columns removed in newer PostgreSQL). Two shapes:
+  - `old_pg>=11`: install `0.2.2` directly → plant guard → pg_upgrade → update to current.
+  - `old_pg=10`: the FULL real-world journey — install `0.2.0`, **bridge-update to `0.2.2` on
+    the old cluster** (the `0.2.0`→`0.2.2` script recreates the views with the pg_upgrade-safe
+    omit_column fix) → plant guard → pg_upgrade → update to current. This proves a `0.2.2`
+    reached via the bridge update (not a fresh install) survives pg_upgrade.
+  Both flows plant the dependency guard and run through `test/ci/existing_mode.sh`.
 
 ## Code Style
 
@@ -55,3 +103,8 @@ Always use block comment format for multi-line comments in SQL files:
 ```
 
 Never use `--` line comments for multi-line explanations.
+
+### Terminology
+"upgrade" refers to a PostgreSQL cluster (`pg_upgrade`); "update" refers to an extension
+(`ALTER EXTENSION ... UPDATE`). cat_tools' version-to-version scripts are "update scripts" —
+never "upgrade scripts."