Add new functions, enums

CLAUDE.md

@@ -37,6 +37,15 @@ 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.
 
+## 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).
+
 ## Pull request descriptions
 
 The maintainer builds the squash commit message from the PR description, so the
@@ -72,18 +81,61 @@ Rules for what to track in git:
 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
+## 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. Two shapes:
+  - `old_pg>=11`: install `0.2.2` directly → plant guard → pg_upgrade → update to current.
+    A *fresh* `0.2.2` install builds the views with the pg_upgrade-safe `omit_column` (`!= ALL`),
+    so it survives pg_upgrade as-is.
+  - `old_pg=10`: the FULL real-world journey — install `0.2.0`, **bridge-update to `0.2.3` on
+    the old cluster** → plant guard → pg_upgrade → update to current. The bridge must reach
+    `0.2.3`, not `0.2.2`: the shipped `0.2.0`→`0.2.2` / `0.2.1`→`0.2.2` scripts do NOT fix the
+    views (their `omit_column` used the no-op `!= ANY`, leaving `relhasoids`/`relhaspkey` in
+    `_cat_tools.pg_class_v`); the pg_class_v DROP+CREATE rebuild that strips those columns lives
+    in the `0.2.2`→`0.2.3` update. `0.2.3` is also the furthest a PG10 cluster can reach
+    (`0.2.3`→`0.3.0` uses `ALTER TYPE ... ADD VALUE`, unrunnable in an update script before
+    PG12); the post-upgrade step then updates `0.2.3`→current on the new cluster. This proves a
+    `0.2.3` reached via the bridge update (not a fresh install) survives pg_upgrade.
+  Both flows plant the dependency guard and run through `bin/test_existing`.
+
+**When working on a new version:** review and expand these matrices. A new version's install
 script may support more PG versions, enabling testing of the update path from older
 cat_tools versions on newer PostgreSQL.
 
@@ -101,6 +153,16 @@ Always use block comment format for multi-line comments in SQL files:
 
 Never use `--` line comments for multi-line explanations.
 
+### Closing non-indentable blocks
+When closing a code block that cannot be indented to show its nesting (e.g. SQL
+`\endif`, `DO $$...$$`, shell heredocs, column-0 `fi`/`esac`) AND that block
+contains nested blocks, label the closer with a comment naming which block it
+closes — e.g. shell `esac  # basename dispatch`, or a named dollar-quote
+`DO $DO$ ... $DO$` for a DO block. Where the language rejects a trailing comment
+on the closer (psql `\endif` warns "extra argument ignored"), put the label on
+the immediately following line instead (e.g. `\endif` then
+`-- end \if :cat_tools_mode_existing`).
+
 ### 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" —

HISTORY.asc

@@ -1,3 +1,35 @@
+0.3.0
+-----
+New functions and types for working with routines and partitioned relations.
+
+### PostgreSQL Version Support
+
+**PostgreSQL 10 and 11 are no longer supported** as of this release. The 0.2.3→0.3.0
+update script adds values to existing enum types (`ALTER TYPE ... ADD VALUE`), which
+cannot run inside an extension update script on PG11 or earlier (a restriction 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 **PostgreSQL 12 through 18+**.
+
+### Changes
+
+* Added routine/function/procedure introspection support: new enum types
+  `routine_type`, `routine_argument_mode`, `routine_volatility`, and
+  `routine_parallel_safety`, plus the composite type `routine_argument`.
+* Added routine functions for parsing and retrieving argument information
+  (`routine__parse_arg_types`, `routine__parse_arg_names`, `routine__arg_types`,
+  `routine__arg_names`, and their `_text` variants), along with the mapping
+  functions `routine__type`, `routine__argument_mode`, `routine__volatility`,
+  and `routine__parallel_safety`.
+* `function__arg_types()` and `function__arg_types_text()` are now deprecated in
+  favor of `routine__parse_arg_types()` and `routine__parse_arg_types_text()`.
+* Corrected the `relation__kind()` / `relation__relkind()` mapping for `relkind`
+  values `c`, `f`, and `m` (composite type, foreign table, and materialized
+  view respectively), which were previously mapped incorrectly.
+* `_cat_tools` helper functions now `REVOKE EXECUTE ... FROM PUBLIC` so they are
+  no longer callable by roles without `cat_tools__usage`.
+
 0.2.3
 -----
 Fix the backwards `pg_class.relkind` mapping (c/f/m) in `relation__kind()` and
@@ -13,7 +45,7 @@ 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
-provides an upgrade path from 0.2.0 and 0.2.1.
+provides an update path from 0.2.0 and 0.2.1.
 
 
 ### PostgreSQL Version Support
@@ -27,24 +59,24 @@ It fails on newer versions due to catalog schema changes:
 * **PG 12**: System catalog `oid` columns became visible as regular columns. Views
   using `SELECT c.*` alongside an explicit `c.oid` alias produce duplicate column names.
 
-cat_tools 0.2.2 installs and upgrades correctly on **PostgreSQL 9.2 through 18+**
+cat_tools 0.2.2 installs and updates correctly on **PostgreSQL 9.2 through 18+**
 (all currently supported versions).
 
-### Upgrade Path
+### Update Path
 
-**You must upgrade cat_tools to 0.2.2 before upgrading PostgreSQL to version 11 or
-later.** Upgrade via `ALTER EXTENSION cat_tools UPDATE`.
+**You must update cat_tools to 0.2.2 before upgrading PostgreSQL to version 11 or
+later.** Update via `ALTER EXTENSION cat_tools UPDATE`.
 
-### Upgrade Warning: Objects Depending on `cat_tools.column`
+### Update Warning: Objects Depending on `cat_tools.column`
 
 `cat_tools.column` in 0.2.0 and 0.2.1 had extra columns: an unqualified `SELECT *`
 across a `LEFT JOIN pg_constraint` accidentally pulled in all `pg_constraint` columns
-(`conname`, `contype`, etc.). The 0.2.2 upgrade fixes the column list by dropping and
+(`conname`, `contype`, etc.). The 0.2.2 update fixes the column list by dropping and
 recreating `cat_tools.column` (and its underlying `_cat_tools.column`).
 
 **If you have created any views, functions, or other objects that depend on
-`cat_tools.column`, you must drop them before upgrading and recreate them
-afterward.** The upgrade will fail with an error if any such dependent objects
+`cat_tools.column`, you must drop them before updating and recreate them
+afterward.** The update will fail with an error if any such dependent objects
 exist — this is intentional, to avoid silently breaking user-defined objects.
 After dropping your dependent objects, run `ALTER EXTENSION cat_tools UPDATE` again.
 
@@ -68,25 +100,25 @@ to PostgreSQL 12 or later.**
 
 ### Changes
 
-* `sql/cat_tools--0.1.4--0.1.5.sql` was empty; added `-- empty upgrade` placeholder so
-  PostgreSQL accepts it as a valid (no-op) upgrade script.
+* `sql/cat_tools--0.1.4--0.1.5.sql` was empty; added `-- empty update` placeholder so
+  PostgreSQL accepts it as a valid (no-op) update script.
 * `cat_tools.column` now exposes `attmissingval` as `text[]` (cast from `anyarray` on
   PG 11+, or `NULL::text[]` on older versions). Any `SELECT *` on `cat_tools.column`
   will now include this column.
 * Views rebuilt using `omit_column()` to enumerate columns explicitly, avoiding both the
   `anyarray` and duplicate-`oid` problems.
-* A direct `0.2.0 → 0.2.2` upgrade path is provided (`cat_tools--0.2.0--0.2.2.sql`),
+* A direct `0.2.0 → 0.2.2` update path is provided (`cat_tools--0.2.0--0.2.2.sql`),
   which also applies all 0.2.1 function additions in a single step.
 * `GRANT SELECT ON cat_tools.pg_extension_v TO cat_tools__usage` is now applied on the
-  upgrade path from 0.2.0 (it was absent in 0.2.0 and only added via the 0.2.1 upgrade).
+  update path from 0.2.0 (it was absent in 0.2.0 and only added via the 0.2.1 update).
 * (Re-release) `_cat_tools.pg_class_v` now explicitly omits `relhasoids` (removed in PG12)
   and `relhaspkey` (removed in PG17) to prevent `pg_upgrade` failures.
 * (Re-release) `_cat_tools.pg_attribute_v` now explicitly omits `attcacheoff` (removed in
   PG17) to prevent `pg_upgrade` failures.
 
 0.2.1
 -----
-Fix significant problems with a previous upgrade script.
+Fix significant problems with a previous update script.
 
 Add pg_extension_v and related functions.
 
@@ -126,7 +158,7 @@ objects would cascede to the extension itself.
 
 0.1.2
 -----
-=## BUGFIX: Install upgrade script
+=## BUGFIX: Install update script
 
 0.1.1
 -----

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.3",
+    "version": "0.3.0",
 
     "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.3",
+            "version": "0.3.0",
 
             "X_comment": "Optional: \"abstract\": Description of the extension.",
             "abstract": "Tools for interfacing with the catalog",
@@ -72,7 +72,7 @@
 
         "build": {
             "requires": {
-                "PostgreSQL": "9.2.0"
+                "PostgreSQL": "12.0"
             }
         },
         "runtime": {

META.json

@@ -14,7 +14,7 @@
     "name": "cat_tools",
 
     "X_comment": "REQUIRED. Version of the distribution. http://pgxn.org/spec/#version",
-    "version": "0.2.3",
+    "version": "0.3.0",
 
     "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.3",
+            "version": "0.3.0",
 
             "X_comment": "Optional: \"abstract\": Description of the extension.",
             "abstract": "Tools for interfacing with the catalog",
@@ -72,7 +72,7 @@
 
         "build": {
             "requires": {
-                "PostgreSQL": "9.2.0"
+                "PostgreSQL": "12.0"
             }
         },
         "runtime": {

Makefile

@@ -38,9 +38,14 @@ PGXNTOOL_ENABLE_TEST_INSTALL = yes
 # is a hard error at parse time (so e.g. `make test TEST_LOAD_SOURCE=typo` fails
 # fast rather than defaulting).
 #
-# The install runs COMMITTED (in test/install, not in deps.sql's per-test
-# transaction) so it happens once, before the suite, and persists into every
-# rolled-back test. See test/install/load.sql.
+# An update must be committed (which is why it lives in test/install, not in
+# deps.sql's per-test transaction): the update to the current version runs
+# ALTER TYPE ... ADD VALUE, and a newly added enum value cannot be USED in the
+# transaction that added it (55P04). See test/install/load.sql.
+#
+# update mode requires PG12+ when it targets the current version (ALTER TYPE
+# ... ADD VALUE cannot run in a transaction at all before PG12); CI restricts it
+# accordingly.
 TEST_LOAD_SOURCE ?= fresh
 ifeq ($(filter $(TEST_LOAD_SOURCE),fresh update existing),)
 $(error TEST_LOAD_SOURCE must be 'fresh', 'update' or 'existing', got '$(TEST_LOAD_SOURCE)')
@@ -60,10 +65,11 @@ export PGOPTIONS := $(PGOPTIONS) -c cat_tools.test_load_mode=$(TEST_LOAD_SOURCE)
 test-update:
 	$(MAKE) test TEST_LOAD_SOURCE=update
 
-# Versioned SQL is generated from .sql.in at build time. That generation and the
-# DATA list that installs it live in sql.mk, which also owns
-# `include pgxntool/base.mk` (base.mk has no include guard, so it must be
-# included exactly once; sql.mk includes it at its top). sql.mk documents the
+# Versioned SQL is generated from .sql.in at build time. That generation, the
+# DATA list that installs it, and the relkind drift source all live in sql.mk,
+# which also owns `include pgxntool/base.mk` (base.mk has no include guard, so it
+# must be included exactly once; sql.mk includes it at its top). This Makefile
+# therefore does NOT include base.mk itself -- only sql.mk. sql.mk documents the
 # GNU Make two-phase (parse vs. recipe) hazards involved (e.g.
 # https://github.com/Postgres-Extensions/cat_tools/issues/28) and relies on
 # base.mk/control.mk/PGXS vars (EXTENSION_VERSION_FILES, PG_CONFIG, MAJORVER,