From d2ff70eac95e1941a1c158b0334db145bf5907af Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 16 Jul 2026 16:49:25 -0500
Subject: [PATCH 01/12] Add extension update test that runs the full suite
 against an upgrade
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

test/build/upgrade.sql is a fast smoke check (via pgxntool 2.1.0's
test-build feature): install 0.9.6 (oldest version we ship a full script
for) and ALTER EXTENSION UPDATE, rolled back.

That alone doesn't prove much — it never runs the actual test suite
against the upgraded state. test/deps.sql now selects between installing
fresh (current version) or via the upgrade path, based on a
count_nulls.test_load_mode GUC the Makefile sets via PGOPTIONS
(TEST_LOAD_SOURCE=fresh|upgrade). Since every test file loads deps.sql,
`make test-update` reruns the whole existing suite (extension_tests,
sanity, simple) against the upgraded install, comparing against the exact
same expected/*.out as `make test` — proving the upgrade behaves
identically to a fresh install rather than just completing without error.

Modeled on cat_tools's test/install/load.sql approach (see their
new_functions-pgxntool-2.1.0 branch), adapted to count_nulls's simpler
single-file test/deps.sql structure instead of introducing a separate
test/install fixture, since count_nulls's suite already installs the
extension per test file (into different schemas) rather than once
globally.

sql/count_nulls--0.9.6.sql isn't picked up by base.mk's DATA wildcard
(which only covers upgrade scripts and the current version file), so it's
added to DATA explicitly. Filed as a pgxntool bug:
Postgres-Extensions/pgxntool#48.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 Makefile                        | 34 +++++++++++++++++++++++++++++
 test/build/expected/upgrade.out |  1 +
 test/build/upgrade.sql          | 11 ++++++++++
 test/deps.sql                   | 38 +++++++++++++++++++++++++++++++++
 4 files changed, 84 insertions(+)
 create mode 100644 test/build/expected/upgrade.out
 create mode 100644 test/build/upgrade.sql

diff --git a/Makefile b/Makefile
index e57011a..48c4320 100644
--- a/Makefile
+++ b/Makefile
@@ -2,3 +2,37 @@ include pgxntool/base.mk
 
 # Temporary hack
 testdeps: $(wildcard test/*/*.sql) $(wildcard test/*.sql) # Be careful not to include directories in this
+
+# Install the oldest historical version's full install script so the upgrade
+# test in test/build/upgrade.sql and test/deps.sql's upgrade mode can
+# CREATE EXTENSION count_nulls VERSION '0.9.6'.
+# Not covered by base.mk's DATA wildcard, which only picks up upgrade scripts
+# (sql/*--*--*.sql) and the current version file.
+DATA += sql/count_nulls--0.9.6.sql
+
+# TEST_LOAD_SOURCE selects how test/deps.sql installs the extension for the
+# WHOLE test suite:
+#   - fresh (default): CREATE EXTENSION count_nulls (current version).
+#   - upgrade: CREATE EXTENSION at the oldest version we still ship a full
+#     install script for (0.9.6), then ALTER EXTENSION UPDATE to current.
+# Running the SAME suite with the SAME expected output against the upgraded
+# database proves it behaves identically to a fresh install.
+#
+# The mode is signalled to test/deps.sql via the count_nulls.test_load_mode
+# placeholder GUC. pg_regress does not forward make variables, but the psql
+# processes it spawns inherit the environment, so PGOPTIONS reaches deps.sql.
+# It's exported unconditionally so deps.sql can read it without missing_ok
+# and fail loudly if it didn't propagate, instead of silently defaulting to
+# fresh and running the wrong suite.
+TEST_LOAD_SOURCE ?= fresh
+ifeq ($(filter $(TEST_LOAD_SOURCE),fresh upgrade),)
+$(error TEST_LOAD_SOURCE must be 'fresh' or 'upgrade', got '$(TEST_LOAD_SOURCE)')
+endif
+export PGOPTIONS := $(PGOPTIONS) -c count_nulls.test_load_mode=$(TEST_LOAD_SOURCE)
+
+# Convenience wrapper: `make test-update` == `make test TEST_LOAD_SOURCE=upgrade`.
+# Must recurse (a fresh $(MAKE)) rather than depend on `test`, so the
+# parse-time TEST_LOAD_SOURCE conditional above re-evaluates with upgrade set.
+.PHONY: test-update
+test-update:
+	$(MAKE) test TEST_LOAD_SOURCE=upgrade
diff --git a/test/build/expected/upgrade.out b/test/build/expected/upgrade.out
new file mode 100644
index 0000000..25fdbb1
--- /dev/null
+++ b/test/build/expected/upgrade.out
@@ -0,0 +1 @@
+\set ECHO none
diff --git a/test/build/upgrade.sql b/test/build/upgrade.sql
new file mode 100644
index 0000000..c5a5946
--- /dev/null
+++ b/test/build/upgrade.sql
@@ -0,0 +1,11 @@
+\set ECHO none
+\i test/pgxntool/psql.sql
+\t
+
+-- Sanity check: install the oldest available version and upgrade to current.
+-- sql/count_nulls--0.9.6.sql is the oldest full install script we still ship
+-- (0.9.0/0.9.2/0.9.5 only exist as upgrade diffs, not standalone installs).
+BEGIN;
+CREATE EXTENSION count_nulls VERSION '0.9.6';
+ALTER EXTENSION count_nulls UPDATE;
+ROLLBACK;
diff --git a/test/deps.sql b/test/deps.sql
index 9705f9f..4dbd4c1 100644
--- a/test/deps.sql
+++ b/test/deps.sql
@@ -5,4 +5,42 @@ CREATE SCHEMA IF NOT EXISTS :schema;
 SET search_path = :schema;
 SET client_min_messages = NOTICE;
 
+/*
+ * Mode selection: 'fresh' installs the current version directly; 'upgrade'
+ * installs the oldest version we still ship a full script for (0.9.6) and
+ * runs ALTER EXTENSION UPDATE. Since every test file loads this via
+ * test/load.sql, running the suite in each mode (make test / make
+ * test-update) exercises the SAME tests against a fresh vs. an upgraded
+ * install, with the same expected output either way.
+ *
+ * The Makefile always exports this GUC, so we read it without missing_ok:
+ * if it failed to propagate we want a loud error here, not a silent
+ * fall-through to 'fresh'.
+ */
+SELECT current_setting('count_nulls.test_load_mode') AS count_nulls_test_load_mode
+\gset
+
+DO $$
+BEGIN
+  IF current_setting('count_nulls.test_load_mode') NOT IN ('fresh', 'upgrade') THEN
+    RAISE EXCEPTION
+      'count_nulls.test_load_mode must be ''fresh'' or ''upgrade'', got ''%'''
+      , current_setting('count_nulls.test_load_mode')
+    ;
+  END IF;
+END
+$$;
+
+SELECT :'count_nulls_test_load_mode' = 'upgrade' AS count_nulls_upgrade_mode
+\gset
+
+\if :count_nulls_upgrade_mode
+CREATE EXTENSION count_nulls VERSION '0.9.6';
+-- Suppress the "already installed, no update" NOTICE class of messages any
+-- upgrade script might emit.
+SET client_min_messages = WARNING;
+ALTER EXTENSION count_nulls UPDATE;
+SET client_min_messages = NOTICE;
+\else
 CREATE EXTENSION count_nulls;
+\endif

From c7286c02abbb8dc0cabadb6a16b16e35e2c61602 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 16 Jul 2026 18:25:57 -0500
Subject: [PATCH 02/12] Rename test-load mode from 'upgrade' to 'update'
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per the terminology convention: 'update' is extension-level (ALTER
EXTENSION UPDATE), 'upgrade' is cluster-level (pg_upgrade) — a separate,
not-yet-covered axis. The wrapper target was already called test-update;
the mode value and GUC name were the odd one out.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 Makefile      | 22 +++++++++++++---------
 test/deps.sql | 17 ++++++++++-------
 2 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/Makefile b/Makefile
index 48c4320..98b9c3f 100644
--- a/Makefile
+++ b/Makefile
@@ -3,8 +3,8 @@ include pgxntool/base.mk
 # Temporary hack
 testdeps: $(wildcard test/*/*.sql) $(wildcard test/*.sql) # Be careful not to include directories in this
 
-# Install the oldest historical version's full install script so the upgrade
-# test in test/build/upgrade.sql and test/deps.sql's upgrade mode can
+# Install the oldest historical version's full install script so the update
+# test in test/build/upgrade.sql and test/deps.sql's update mode can
 # CREATE EXTENSION count_nulls VERSION '0.9.6'.
 # Not covered by base.mk's DATA wildcard, which only picks up upgrade scripts
 # (sql/*--*--*.sql) and the current version file.
@@ -13,11 +13,15 @@ DATA += sql/count_nulls--0.9.6.sql
 # TEST_LOAD_SOURCE selects how test/deps.sql installs the extension for the
 # WHOLE test suite:
 #   - fresh (default): CREATE EXTENSION count_nulls (current version).
-#   - upgrade: CREATE EXTENSION at the oldest version we still ship a full
+#   - update: CREATE EXTENSION at the oldest version we still ship a full
 #     install script for (0.9.6), then ALTER EXTENSION UPDATE to current.
-# Running the SAME suite with the SAME expected output against the upgraded
+# Running the SAME suite with the SAME expected output against the updated
 # database proves it behaves identically to a fresh install.
 #
+# "update" (this) is extension-level (ALTER EXTENSION UPDATE); "upgrade" is
+# cluster-level (pg_upgrade) and is a separate, not-yet-implemented axis. Don't
+# conflate the two in variable names or comments.
+#
 # The mode is signalled to test/deps.sql via the count_nulls.test_load_mode
 # placeholder GUC. pg_regress does not forward make variables, but the psql
 # processes it spawns inherit the environment, so PGOPTIONS reaches deps.sql.
@@ -25,14 +29,14 @@ DATA += sql/count_nulls--0.9.6.sql
 # and fail loudly if it didn't propagate, instead of silently defaulting to
 # fresh and running the wrong suite.
 TEST_LOAD_SOURCE ?= fresh
-ifeq ($(filter $(TEST_LOAD_SOURCE),fresh upgrade),)
-$(error TEST_LOAD_SOURCE must be 'fresh' or 'upgrade', got '$(TEST_LOAD_SOURCE)')
+ifeq ($(filter $(TEST_LOAD_SOURCE),fresh update),)
+$(error TEST_LOAD_SOURCE must be 'fresh' or 'update', got '$(TEST_LOAD_SOURCE)')
 endif
 export PGOPTIONS := $(PGOPTIONS) -c count_nulls.test_load_mode=$(TEST_LOAD_SOURCE)
 
-# Convenience wrapper: `make test-update` == `make test TEST_LOAD_SOURCE=upgrade`.
+# Convenience wrapper: `make test-update` == `make test TEST_LOAD_SOURCE=update`.
 # Must recurse (a fresh $(MAKE)) rather than depend on `test`, so the
-# parse-time TEST_LOAD_SOURCE conditional above re-evaluates with upgrade set.
+# parse-time TEST_LOAD_SOURCE conditional above re-evaluates with update set.
 .PHONY: test-update
 test-update:
-	$(MAKE) test TEST_LOAD_SOURCE=upgrade
+	$(MAKE) test TEST_LOAD_SOURCE=update
diff --git a/test/deps.sql b/test/deps.sql
index 4dbd4c1..454be4b 100644
--- a/test/deps.sql
+++ b/test/deps.sql
@@ -6,13 +6,16 @@ SET search_path = :schema;
 SET client_min_messages = NOTICE;
 
 /*
- * Mode selection: 'fresh' installs the current version directly; 'upgrade'
+ * Mode selection: 'fresh' installs the current version directly; 'update'
  * installs the oldest version we still ship a full script for (0.9.6) and
  * runs ALTER EXTENSION UPDATE. Since every test file loads this via
  * test/load.sql, running the suite in each mode (make test / make
- * test-update) exercises the SAME tests against a fresh vs. an upgraded
+ * test-update) exercises the SAME tests against a fresh vs. an updated
  * install, with the same expected output either way.
  *
+ * "update" here is extension-level (ALTER EXTENSION UPDATE); it is not
+ * "upgrade" (cluster-level pg_upgrade), a separate axis this doesn't cover.
+ *
  * The Makefile always exports this GUC, so we read it without missing_ok:
  * if it failed to propagate we want a loud error here, not a silent
  * fall-through to 'fresh'.
@@ -22,22 +25,22 @@ SELECT current_setting('count_nulls.test_load_mode') AS count_nulls_test_load_mo
 
 DO $$
 BEGIN
-  IF current_setting('count_nulls.test_load_mode') NOT IN ('fresh', 'upgrade') THEN
+  IF current_setting('count_nulls.test_load_mode') NOT IN ('fresh', 'update') THEN
     RAISE EXCEPTION
-      'count_nulls.test_load_mode must be ''fresh'' or ''upgrade'', got ''%'''
+      'count_nulls.test_load_mode must be ''fresh'' or ''update'', got ''%'''
       , current_setting('count_nulls.test_load_mode')
     ;
   END IF;
 END
 $$;
 
-SELECT :'count_nulls_test_load_mode' = 'upgrade' AS count_nulls_upgrade_mode
+SELECT :'count_nulls_test_load_mode' = 'update' AS count_nulls_update_mode
 \gset
 
-\if :count_nulls_upgrade_mode
+\if :count_nulls_update_mode
 CREATE EXTENSION count_nulls VERSION '0.9.6';
 -- Suppress the "already installed, no update" NOTICE class of messages any
--- upgrade script might emit.
+-- update script might emit.
 SET client_min_messages = WARNING;
 ALTER EXTENSION count_nulls UPDATE;
 SET client_min_messages = NOTICE;

From 3c078c82db71b28e1724467a15a54b35f206c143 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Wed, 22 Jul 2026 17:44:24 -0500
Subject: [PATCH 03/12] Add 'existing' load mode and schema parameterization to
 the test suite

test/deps.sql gains a third TEST_LOAD_SOURCE mode ('existing'): asserts the
extension is already installed and current, without dropping/creating/
updating anything, for use against a real pg_upgrade'd or out-of-band
updated database.

Replaces the per-test-file hardcoded schema literals
(schema_to_load_count_nulls / public) - a stand-in for real
schema-qualification coverage that only ever tested two fixed, always-
lowercase names - with a single TEST_SCHEMA make var, propagated the same
way as TEST_LOAD_SOURCE via a GUC, applied uniformly for the whole test run.
This also resolves an architectural conflict between the two: a real
pg_upgrade leaves the extension in exactly one schema, which cannot
simultaneously match two different per-file hardcoded literals, so
'existing' mode needs every file installing into the same run-wide schema
to produce comparable output.

sanity.sql previously bypassed test/deps.sql entirely (a bare, unconditional
CREATE EXTENSION), which broke outright under 'existing' mode
("extension already exists"); it now respects both TEST_LOAD_SOURCE and
TEST_SCHEMA like the rest of the suite.

Locally: `make test TEST_SCHEMA=Quoted` exercises a schema requiring SQL
identifier quoting (mixed case - unquoted would fold to lowercase and
silently test 'public' again).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 Makefile                     | 36 ++++++++++++++---
 test/core/functions.sql      |  6 ++-
 test/deps.sql                | 77 +++++++++++++++++++++++++++++-------
 test/sql/extension_tests.sql | 18 +++++----
 test/sql/sanity.sql          | 22 +++++++++++
 test/sql/simple.sql          |  7 +++-
 6 files changed, 136 insertions(+), 30 deletions(-)

diff --git a/Makefile b/Makefile
index 98b9c3f..269de69 100644
--- a/Makefile
+++ b/Makefile
@@ -15,12 +15,18 @@ DATA += sql/count_nulls--0.9.6.sql
 #   - fresh (default): CREATE EXTENSION count_nulls (current version).
 #   - update: CREATE EXTENSION at the oldest version we still ship a full
 #     install script for (0.9.6), then ALTER EXTENSION UPDATE to current.
-# Running the SAME suite with the SAME expected output against the updated
-# database proves it behaves identically to a fresh install.
+#   - existing: the extension is already installed (a real `pg_upgrade` run,
+#     or an out-of-band update) - deps.sql only asserts it's present and
+#     current, it does not drop/create/update anything. Meant to be run with
+#     CONTRIB_TESTDB=<db> EXTRA_REGRESS_OPTS=--use-existing
+#     PGXNTOOL_ENABLE_TEST_BUILD=no against a real database, not via a make
+#     wrapper here (see the pg_upgrade CI job).
+# Running the SAME suite with the SAME expected output against the updated/
+# upgraded database proves it behaves identically to a fresh install.
 #
 # "update" (this) is extension-level (ALTER EXTENSION UPDATE); "upgrade" is
-# cluster-level (pg_upgrade) and is a separate, not-yet-implemented axis. Don't
-# conflate the two in variable names or comments.
+# cluster-level (pg_upgrade) - 'existing' is how that axis is exercised.
+# Don't conflate the two in variable names or comments.
 #
 # The mode is signalled to test/deps.sql via the count_nulls.test_load_mode
 # placeholder GUC. pg_regress does not forward make variables, but the psql
@@ -29,11 +35,29 @@ DATA += sql/count_nulls--0.9.6.sql
 # and fail loudly if it didn't propagate, instead of silently defaulting to
 # fresh and running the wrong suite.
 TEST_LOAD_SOURCE ?= fresh
-ifeq ($(filter $(TEST_LOAD_SOURCE),fresh update),)
-$(error TEST_LOAD_SOURCE must be 'fresh' or 'update', got '$(TEST_LOAD_SOURCE)')
+ifeq ($(filter $(TEST_LOAD_SOURCE),fresh update existing),)
+$(error TEST_LOAD_SOURCE must be 'fresh', 'update' or 'existing', got '$(TEST_LOAD_SOURCE)')
 endif
 export PGOPTIONS := $(PGOPTIONS) -c count_nulls.test_load_mode=$(TEST_LOAD_SOURCE)
 
+# TEST_SCHEMA selects which schema test/deps.sql installs count_nulls into,
+# for the WHOLE test run (every test file uses the SAME schema in a given
+# run - previously each test file hardcoded its own literal schema name as a
+# stand-in for real schema-qualification coverage, which only ever tested
+# two fixed, always-lowercase names). Combined with TEST_LOAD_SOURCE this
+# drives a schema x mode CI matrix; in particular, a schema whose name
+# requires SQL identifier quoting (mixed case - unquoted would silently fold
+# to lowercase and test the wrong, matching schema instead) needs its own
+# leg, not just 'public'. Locally: `make test TEST_SCHEMA=Quoted`.
+#
+# Propagated the same way as TEST_LOAD_SOURCE: via the count_nulls.test_schema
+# GUC, exported unconditionally through PGOPTIONS.
+TEST_SCHEMA ?= public
+ifeq ($(strip $(TEST_SCHEMA)),)
+$(error TEST_SCHEMA must not be empty)
+endif
+export PGOPTIONS := $(PGOPTIONS) -c count_nulls.test_schema=$(TEST_SCHEMA)
+
 # Convenience wrapper: `make test-update` == `make test TEST_LOAD_SOURCE=update`.
 # Must recurse (a fresh $(MAKE)) rather than depend on `test`, so the
 # parse-time TEST_LOAD_SOURCE conditional above re-evaluates with update set.
diff --git a/test/core/functions.sql b/test/core/functions.sql
index 482526c..e5120b0 100644
--- a/test/core/functions.sql
+++ b/test/core/functions.sql
@@ -219,6 +219,10 @@ BEGIN
 END
 $body$;
 
-SET SEARCH_PATH = _null_count_test, tap, :schema;
+-- Deliberately does NOT restore :"schema" (the schema count_nulls is
+-- installed into) onto search_path here - whether the caller wants it there
+-- (testing unqualified/on-search-path use) or not (testing fully-qualified/
+-- off-search-path use) differs per test file, so each caller sets its own
+-- search_path explicitly after \i'ing this file.
 
 -- vi: expandtab sw=2 ts=2
diff --git a/test/deps.sql b/test/deps.sql
index 454be4b..458674d 100644
--- a/test/deps.sql
+++ b/test/deps.sql
@@ -1,20 +1,20 @@
 -- Add any test dependency statements here
--- IF NOT EXISTS will emit NOTICEs, which is annoying
-SET client_min_messages = WARNING;
-CREATE SCHEMA IF NOT EXISTS :schema;
-SET search_path = :schema;
-SET client_min_messages = NOTICE;
 
 /*
  * Mode selection: 'fresh' installs the current version directly; 'update'
  * installs the oldest version we still ship a full script for (0.9.6) and
- * runs ALTER EXTENSION UPDATE. Since every test file loads this via
- * test/load.sql, running the suite in each mode (make test / make
- * test-update) exercises the SAME tests against a fresh vs. an updated
- * install, with the same expected output either way.
+ * runs ALTER EXTENSION UPDATE; 'existing' asserts the extension is already
+ * installed (a real `pg_upgrade` leg, or an out-of-band update) and touches
+ * nothing. Since every test file loads this via test/load.sql, running the
+ * suite in each mode (make test / make test-update / make test
+ * TEST_LOAD_SOURCE=existing) exercises the SAME tests against a fresh vs.
+ * updated vs. really-upgraded install, with the same expected output either
+ * way.
  *
  * "update" here is extension-level (ALTER EXTENSION UPDATE); it is not
- * "upgrade" (cluster-level pg_upgrade), a separate axis this doesn't cover.
+ * "upgrade" (cluster-level pg_upgrade) - 'existing' is how that axis is
+ * exercised, via a real pg_upgrade run outside this test suite (see the
+ * pg_upgrade CI job).
  *
  * The Makefile always exports this GUC, so we read it without missing_ok:
  * if it failed to propagate we want a loud error here, not a silent
@@ -25,19 +25,68 @@ SELECT current_setting('count_nulls.test_load_mode') AS count_nulls_test_load_mo
 
 DO $$
 BEGIN
-  IF current_setting('count_nulls.test_load_mode') NOT IN ('fresh', 'update') THEN
+  IF current_setting('count_nulls.test_load_mode') NOT IN ('fresh', 'update', 'existing') THEN
     RAISE EXCEPTION
-      'count_nulls.test_load_mode must be ''fresh'' or ''update'', got ''%'''
+      'count_nulls.test_load_mode must be ''fresh'', ''update'' or ''existing'', got ''%'''
       , current_setting('count_nulls.test_load_mode')
     ;
   END IF;
 END
 $$;
 
-SELECT :'count_nulls_test_load_mode' = 'update' AS count_nulls_update_mode
+SELECT :'count_nulls_test_load_mode' = 'update'   AS count_nulls_update_mode
+\gset
+SELECT :'count_nulls_test_load_mode' = 'existing' AS count_nulls_existing_mode
 \gset
 
-\if :count_nulls_update_mode
+/*
+ * TEST_SCHEMA (the count_nulls.test_schema GUC, set via the Makefile):
+ * which schema the extension is installed into, for the WHOLE test run -
+ * the SAME schema for every test file, not a different literal hardcoded
+ * per file. This is what drives the schema x mode CI matrix: at minimum
+ * 'public' (the default) and a schema whose name requires SQL identifier
+ * quoting (mixed case - unquoted would fold to lowercase and silently test
+ * a different, matching schema instead), to exercise test files' %I
+ * schema-qualification rather than just their literal test data.
+ *
+ * Read with :"schema" (quoted-identifier form) wherever used as a bare
+ * identifier below and in the test files, since the quoting-required case
+ * is exactly what this exists to exercise.
+ */
+SELECT current_setting('count_nulls.test_schema') AS schema
+\gset
+
+-- :"schema" is created/searched in every mode, including 'existing', even
+-- though 'existing' mode never installs the extension into it: test files
+-- (e.g. test__shutdown__drop_all's `DROP SCHEMA :"schema"`) expect it to
+-- exist regardless of mode, and an empty schema is harmless. IF NOT EXISTS
+-- emits NOTICEs, which is annoying.
+SET client_min_messages = WARNING;
+CREATE SCHEMA IF NOT EXISTS :"schema";
+SET search_path = :"schema";
+SET client_min_messages = NOTICE;
+
+\if :count_nulls_existing_mode
+-- Extension is already installed (real pg_upgrade, or an out-of-band
+-- update) - assert it's present and current, but do NOT drop/create/update
+-- it. The CI job driving this mode is responsible for having installed the
+-- real extension into :"schema" (matching this run's TEST_SCHEMA) before
+-- getting here, so the rest of the suite sees the same schema regardless of
+-- mode.
+DO $$
+DECLARE
+  v_installed text := (SELECT extversion FROM pg_extension WHERE extname = 'count_nulls');
+  v_default   text := (SELECT default_version FROM pg_available_extensions WHERE name = 'count_nulls');
+BEGIN
+  IF v_installed IS NULL THEN
+    RAISE EXCEPTION 'count_nulls.test_load_mode=existing but count_nulls is not installed';
+  END IF;
+  IF v_installed IS DISTINCT FROM v_default THEN
+    RAISE EXCEPTION 'count_nulls installed at % but default_version is %', v_installed, v_default;
+  END IF;
+END
+$$;
+\elif :count_nulls_update_mode
 CREATE EXTENSION count_nulls VERSION '0.9.6';
 -- Suppress the "already installed, no update" NOTICE class of messages any
 -- update script might emit.
diff --git a/test/sql/extension_tests.sql b/test/sql/extension_tests.sql
index ba88447..9786fc5 100644
--- a/test/sql/extension_tests.sql
+++ b/test/sql/extension_tests.sql
@@ -1,17 +1,22 @@
 \set ECHO none
 
-\set schema schema_to_load_count_nulls
 \i test/load.sql
 
-\set schema public
 \i test/core/functions.sql
 
---CREATE OR REPLACE FUNCTION ncs() RETURNS name LANGUAGE sql IMMUTABLE AS $$SELECT 'schema_to_load_count_nulls'::name$$;
+-- Unlike simple.sql, this file deliberately leaves search_path as
+-- functions.sql set it (_null_count_test, tap) - the schema count_nulls is
+-- installed into (TEST_SCHEMA / test/deps.sql's :"schema") stays off
+-- search_path, so every check below only passes if functions.sql's
+-- %I-qualified calls (via ncs()) are actually correct, regardless of which
+-- schema TEST_SCHEMA names.
 
 CREATE FUNCTION _null_count_test.test__check_ncs
 () RETURNS SETOF text LANGUAGE plpgsql AS $body$
 DECLARE
-    s CONSTANT name = 'schema_to_load_count_nulls';
+    -- current_setting(), not a psql :"schema" substitution: psql does not
+    -- interpolate variables inside dollar-quoted function bodies.
+    s CONSTANT name = current_setting('count_nulls.test_schema')::name;
 BEGIN
     RETURN NEXT is(
         ncs()
@@ -20,8 +25,7 @@ BEGIN
     RETURN NEXT is(
         current_schemas(true) @> array[s]
         , false
-        --, format('schema %I should not be in search path (%s)', s, current_schemas(true))
-        , format('schema %I should not be in search path', s) --, current_schemas(true))
+        , format('schema %I should not be in search path', s)
     );
 END
 $body$;
@@ -34,7 +38,7 @@ BEGIN
     );
 
     RETURN NEXT lives_ok(
-        $$DROP SCHEMA schema_to_load_count_nulls$$
+        format('DROP SCHEMA %I', current_setting('count_nulls.test_schema'))
     );
 END
 $body$;
diff --git a/test/sql/sanity.sql b/test/sql/sanity.sql
index 6c9ea2f..53d2ad0 100644
--- a/test/sql/sanity.sql
+++ b/test/sql/sanity.sql
@@ -2,7 +2,29 @@
 \set VERBOSITY verbose
 
 BEGIN;
+
+-- Unlike the other test files, this one doesn't route through
+-- test/deps.sql - it's meant to be a minimal, standalone smoke test. It
+-- still has to respect TEST_SCHEMA/TEST_LOAD_SOURCE though: under 'existing'
+-- mode the extension is already installed (CREATE EXTENSION would error),
+-- and either way the calls below are unqualified, so search_path needs to
+-- include wherever count_nulls actually lives.
+SELECT current_setting('count_nulls.test_load_mode') = 'existing' AS count_nulls_existing_mode
+\gset
+SELECT current_setting('count_nulls.test_schema') AS schema
+\gset
+
+\if :count_nulls_existing_mode
+SET search_path = :"schema";
+\else
+-- IF NOT EXISTS emits a NOTICE for the (very common) case of :"schema"
+-- being 'public', which always already exists.
+SET client_min_messages = WARNING;
+CREATE SCHEMA IF NOT EXISTS :"schema";
+SET search_path = :"schema";
+SET client_min_messages = NOTICE;
 CREATE EXTENSION count_nulls;
+\endif
 
 -- Remember that JSON only accepts 'null'
 SELECT null_count('{"a": null}'::jsonb);
diff --git a/test/sql/simple.sql b/test/sql/simple.sql
index 9406729..a429fdd 100644
--- a/test/sql/simple.sql
+++ b/test/sql/simple.sql
@@ -1,11 +1,14 @@
 \set ECHO none
 
-\set schema public
-
 \i test/load.sql
 
 \i test/core/functions.sql
 
+-- Unlike extension_tests.sql, this file tests count_nulls used unqualified
+-- (i.e. installed schema IS on search_path), regardless of which schema
+-- TEST_SCHEMA (test/deps.sql's :"schema") actually names.
+SET SEARCH_PATH = _null_count_test, tap, :"schema";
+
 --SET client_min_messages = debug;
 
 SELECT * FROM runtests( '_null_count_test'::name );

From 3f13cdc50457d1f2eb9138cc4d59784ad9b84748 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Wed, 22 Jul 2026 17:44:32 -0500
Subject: [PATCH 04/12] Add pg_upgrade dependency guard and test_existing
 helper script

test/pg_upgrade/{plant,assert,drop}_guard.sql: a view with a hard pg_depend
dependency on a stable, never-dropped/redefined extension member
(null_count(anyarray), unchanged since 0.9.0), so a non-CASCADE
DROP EXTENSION count_nulls is blocked. Proves an install/update/pg_upgrade
sequence didn't silently drop+reinstall the extension it's meant to be
testing - a stray CASCADE, a logic bug, or a bad CI step would otherwise
fall through to a silent fresh reinstall and still report green.

bin/test_existing factors the install -> plant guard -> update/upgrade ->
assert -> drop guard -> run suite sequence (needed by both the
extension-update-test and pg-upgrade-test CI jobs) into one committed,
parameterized script instead of duplicating it as inline YAML. Modeled on
Postgres-Extensions/cat_tools's script of the same name, with two
differences: count_nulls has no pg_upgrade-unsafe old version to bridge past
(it has always been pure SQL functions, no SELECT-*-over-catalog views), and
its suite has its own legitimate (harmless - always rolled back) DROP
EXTENSION test, so here the guard is dropped before run-suite instead of
surviving through it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 bin/test_existing                | 225 +++++++++++++++++++++++++++++++
 test/pg_upgrade/assert_guard.sql |  33 +++++
 test/pg_upgrade/drop_guard.sql   |   9 ++
 test/pg_upgrade/plant_guard.sql  |  14 ++
 4 files changed, 281 insertions(+)
 create mode 100755 bin/test_existing
 create mode 100644 test/pg_upgrade/assert_guard.sql
 create mode 100644 test/pg_upgrade/drop_guard.sql
 create mode 100644 test/pg_upgrade/plant_guard.sql

diff --git a/bin/test_existing b/bin/test_existing
new file mode 100755
index 0000000..f729760
--- /dev/null
+++ b/bin/test_existing
@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+#
+# Exercise the count_nulls test suite against a REAL database whose extension
+# was installed/updated/pg_upgraded OUTSIDE the suite ("existing" mode). Both
+# the pg-upgrade-test and extension-update-test jobs in
+# .github/workflows/ci.yml repeat the same sequence:
+#
+#   install -> plant dependency guard -> update/upgrade -> assert version
+#            -> drop the guard -> run the suite in existing mode
+#
+# so it lives here once instead of being duplicated as inline YAML. It is NOT
+# CI-only: a developer can run any subcommand locally against a scratch
+# database. Modeled on Postgres-Extensions/cat_tools's bin/test_existing, with
+# two differences: count_nulls has no pg_upgrade-unsafe old versions to bridge
+# past (advanced-extension-testing.md #7/#9 don't apply - it ships no
+# SELECT-*-over-catalog views), and its suite has its OWN legitimate (though
+# harmless - always rolled back) DROP EXTENSION test, so here the guard is
+# dropped before run-suite instead of surviving through it.
+#
+# USAGE: bin/test_existing <subcommand> [args]
+#
+#   plant-guard DB SCHEMA
+#       Plant + prove the dependency guard (extension must already exist).
+#
+#   update DB [TO_VERSION]
+#       ALTER EXTENSION count_nulls UPDATE [TO 'TO_VERSION'] (empty => current).
+#
+#   prepare-old DB SCHEMA INSTALL_VERSION
+#       Old-cluster prep for pg-upgrade-test: create DB + extension at
+#       INSTALL_VERSION in SCHEMA, then plant + prove the guard.
+#
+#   run-suite DB SCHEMA
+#       Assert the current version, re-prove the guard, drop it, then run the
+#       suite in existing mode (extension must be at the current version).
+#
+#   update-scenario DB SCHEMA FROM_VERSION
+#       Create DB + extension at FROM_VERSION in SCHEMA, plant the guard,
+#       update to current, then run-suite against that real updated database.
+#
+# Run `bin/test_existing` with no subcommand to print usage.
+#
+# Why the dependency guard: "existing" mode must run the suite against the
+# ACTUAL upgraded/updated objects. If anything silently dropped + reinstalled
+# the extension, the suite would test a FRESH install and hide a regression.
+# We plant an object that HARD-references a count_nulls member so a
+# non-CASCADE DROP EXTENSION fails, and actively PROVE that (see
+# test/pg_upgrade/assert_guard.sql): if the drop unexpectedly succeeds, this
+# script fails CI rather than silently passing.
+set -euo pipefail
+
+# Run from the repository root (where `make` works and test paths resolve),
+# regardless of the caller's cwd. bin/ sits directly under the repo root, so
+# its parent is the root. readlink -f resolves any path the script was
+# invoked through.
+cd "$(dirname "$(readlink -f "$0")")/.."
+
+# ---------------------------------------------------------------------------
+# psql helpers
+# ---------------------------------------------------------------------------
+
+# Capture the single-value (-tAc) output of a query against a database.
+psql_value() {
+  local db=$1 sql=$2
+  psql -d "$db" -tAc "$sql"
+}
+
+# Run SQL that must succeed, aborting the whole script on any error.
+psql_do() {
+  local db=$1
+  shift
+  psql -d "$db" -v ON_ERROR_STOP=1 "$@"
+}
+
+# ---------------------------------------------------------------------------
+# Version / guard helpers
+# ---------------------------------------------------------------------------
+
+current_version() {
+  make -s print-PGXNVERSION 2>/dev/null | sed -n 's/.*set to "\(.*\)"$/\1/p'
+}
+
+installed_version() {
+  psql_value "$1" \
+    "SELECT extversion FROM pg_extension WHERE extname = 'count_nulls'"
+}
+
+guard_present() {
+  test "$(psql_value "$1" \
+    "SELECT count(*) FROM pg_views WHERE schemaname = 'count_nulls_drop_guard' AND viewname = 'guard'")" = 1
+}
+
+# Plant the guard and PROVE it blocks a non-CASCADE drop. Call right after
+# CREATE EXTENSION (and before any update/upgrade) so it persists through them.
+plant_guard() {
+  local db=$1 schema=$2
+  psql -d "$db" -v ON_ERROR_STOP=1 -v schema="$schema" -f test/pg_upgrade/plant_guard.sql
+  assert_drop_blocked "$db"
+}
+
+# The core safeguard self-check: a non-CASCADE DROP EXTENSION MUST fail while
+# the guard exists. assert_guard.sql fails loudly (nonzero exit) if the drop
+# unexpectedly succeeds, or if the extension/guard are missing afterward.
+assert_drop_blocked() {
+  local db=$1
+  psql -d "$db" -v ON_ERROR_STOP=1 -f test/pg_upgrade/assert_guard.sql
+  echo "OK: non-CASCADE DROP EXTENSION is blocked in '$db' (dependency guard effective)"
+}
+
+drop_guard() {
+  local db=$1
+  psql -d "$db" -v ON_ERROR_STOP=1 -f test/pg_upgrade/drop_guard.sql
+}
+
+assert_version() {
+  local db=$1 expected=$2 installed
+  [ "$expected" = current ] && expected=$(current_version)
+  installed=$(installed_version "$db")
+  echo "version check '$db': installed='$installed' expected='$expected'"
+  if [ -z "$installed" ] || [ -z "$expected" ] || [ "$installed" != "$expected" ]; then
+    echo "FAIL: count_nulls in '$db' is '$installed', expected '$expected'" >&2
+    exit 1
+  fi
+}
+
+update_ext() {
+  local db=$1 to=${2:-}
+  # Prepend "TO " only when a target version is given, so a single statement
+  # covers both cases (empty $to => bare "ALTER EXTENSION ... UPDATE" to
+  # current). Use `if`, not `&&`: a false test under `set -e` would abort.
+  if [ -n "$to" ]; then to="TO '$to'"; fi
+  psql_do "$db" -c "ALTER EXTENSION count_nulls UPDATE $to"
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand implementations
+# ---------------------------------------------------------------------------
+
+# prepare-old DB SCHEMA INSTALL_VERSION
+#   Old-cluster preparation for pg-upgrade-test: create the database and the
+#   extension at INSTALL_VERSION in SCHEMA, then plant + prove the guard.
+#   No bridge step (unlike cat_tools): count_nulls ships no
+#   SELECT-*-over-catalog views, so it has no known pg_upgrade-unsafe old
+#   version to bridge past (advanced-extension-testing.md #7/#9).
+prepare_old() {
+  local db=$1 schema=$2 install=$3
+  createdb "$db"
+  psql_do "$db" -c "CREATE SCHEMA IF NOT EXISTS \"$schema\"; SET search_path = \"$schema\"; CREATE EXTENSION count_nulls VERSION '$install'"
+  plant_guard "$db" "$schema"
+}
+
+# update-scenario DB SCHEMA FROM_VERSION
+#   Full extension-update flow that runs the existing-mode suite: create the
+#   DB and extension at FROM_VERSION in SCHEMA, plant + prove the guard,
+#   update to the current version, then run the suite against that real
+#   updated database.
+update_scenario() {
+  local db=$1 schema=$2 from=$3
+  createdb "$db"
+  psql_do "$db" -c "CREATE SCHEMA IF NOT EXISTS \"$schema\"; SET search_path = \"$schema\"; CREATE EXTENSION count_nulls VERSION '$from'"
+  plant_guard "$db" "$schema"
+  update_ext "$db"
+  run_suite "$db" "$schema"
+}
+
+# Run the pgTAP suite against an already-populated database in existing mode.
+# Verifies the extension is at the current version, re-proves the guard
+# still blocks a drop (i.e. it survived the update/upgrade), drops the guard
+# (see the file header for why - count_nulls's own suite legitimately drops
+# the extension, harmlessly, inside a transaction that's always rolled
+# back), then runs the suite via --use-existing so pg_regress does NOT
+# drop/recreate the database.
+run_suite() {
+  local db=$1 schema=$2
+  assert_version "$db" current
+  assert_drop_blocked "$db"
+  drop_guard "$db"
+  # In existing mode pg_regress runs against $db via --use-existing and must
+  # NOT create/drop its own database. Two consequences drive the make args:
+  #   1. PGXNTOOL_ENABLE_TEST_BUILD=no: base.mk auto-enables the test-build
+  #      sanity check (test/build/upgrade.sql), adding it as a `test`
+  #      prerequisite. test-build spawns a recursive `installcheck` that
+  #      INHERITS this call's --use-existing (a command-line var propagates
+  #      to sub-makes) but targets a fresh `regression` DB it cannot create
+  #      under --use-existing, so it dies. test-build is a fresh-install
+  #      smoke check already run by the fresh `test` job on every PG version
+  #      - it adds nothing here.
+  #   2. `make verify-results` (not just `make test`) is the real pass/fail
+  #      gate: base.mk's `.IGNORE: installcheck` means `make test` prints
+  #      regression.diffs but exits 0 regardless
+  #      (advanced-extension-testing.md #8). verify-results depends on
+  #      `test`, so it must carry the SAME existing-mode overrides or it
+  #      would re-run FRESH (against a new throwaway DB) instead of
+  #      verifying THIS existing database.
+  local existing_args="TEST_LOAD_SOURCE=existing TEST_SCHEMA=$schema CONTRIB_TESTDB=$db EXTRA_REGRESS_OPTS=--use-existing PGXNTOOL_ENABLE_TEST_BUILD=no"
+  make test $existing_args
+  make verify-results $existing_args
+}
+
+usage() {
+  echo "usage: bin/test_existing <subcommand> [args]" >&2
+  echo "  plant-guard DB SCHEMA" >&2
+  echo "  update DB [TO_VERSION]" >&2
+  echo "  prepare-old DB SCHEMA INSTALL_VERSION" >&2
+  echo "  run-suite DB SCHEMA" >&2
+  echo "  update-scenario DB SCHEMA FROM_VERSION" >&2
+  exit 2
+}
+
+# Explicit subcommand dispatch on $1. Defined first for readability; INVOKED
+# at the very bottom, after every helper it calls is defined (bash resolves
+# calls at runtime, so main() appearing first is fine).
+main() {
+  local cmd=${1:-}
+  shift || true
+  case "$cmd" in
+    plant-guard)     plant_guard "$@" ;;
+    update)          update_ext "$@" ;;
+    prepare-old)     prepare_old "$@" ;;
+    run-suite)       run_suite "$@" ;;
+    update-scenario) update_scenario "$@" ;;
+    *)               usage ;;
+  esac
+}
+
+main "$@"
diff --git a/test/pg_upgrade/assert_guard.sql b/test/pg_upgrade/assert_guard.sql
new file mode 100644
index 0000000..a427515
--- /dev/null
+++ b/test/pg_upgrade/assert_guard.sql
@@ -0,0 +1,33 @@
+-- Proves the guard planted by plant_guard.sql actually blocks a
+-- non-CASCADE DROP EXTENSION - "prove it, don't assume it"
+-- (advanced-extension-testing.md #4). Re-run after every step (install,
+-- pg_upgrade, post-upgrade ALTER EXTENSION UPDATE): the guard disappearing
+-- at any point means a CASCADE drop happened somewhere upstream, i.e. the
+-- "existing" run downstream would actually be a silent fresh install.
+--
+-- Usage: psql -v ON_ERROR_STOP=1 -f assert_guard.sql
+\set ON_ERROR_STOP on
+
+DO $$
+BEGIN
+  DROP EXTENSION count_nulls;
+  -- Only reached if the drop above unexpectedly succeeded.
+  RAISE EXCEPTION 'GUARD FAILURE: non-CASCADE DROP EXTENSION count_nulls unexpectedly succeeded';
+EXCEPTION WHEN dependent_objects_still_exist THEN
+  RAISE NOTICE 'guard held: DROP EXTENSION count_nulls correctly blocked';
+END
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'count_nulls') THEN
+    RAISE EXCEPTION 'GUARD FAILURE: count_nulls extension missing after guard check';
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE c.relname = 'guard' AND n.nspname = 'count_nulls_drop_guard'
+  ) THEN
+    RAISE EXCEPTION 'GUARD FAILURE: count_nulls_drop_guard.guard view missing';
+  END IF;
+END
+$$;
diff --git a/test/pg_upgrade/drop_guard.sql b/test/pg_upgrade/drop_guard.sql
new file mode 100644
index 0000000..ae8dd04
--- /dev/null
+++ b/test/pg_upgrade/drop_guard.sql
@@ -0,0 +1,9 @@
+-- Removes the guard (plant_guard.sql) once its job is done - proving the
+-- install/pg_upgrade/update steps didn't corrupt the real extension - so it
+-- doesn't then block the pgTap suite's own DROP EXTENSION test
+-- (test__shutdown__drop_all, run in a transaction that's rolled back
+-- regardless, so re-dropping the real extension there is harmless).
+--
+-- Usage: psql -v ON_ERROR_STOP=1 -f drop_guard.sql
+\set ON_ERROR_STOP on
+DROP SCHEMA count_nulls_drop_guard CASCADE;
diff --git a/test/pg_upgrade/plant_guard.sql b/test/pg_upgrade/plant_guard.sql
new file mode 100644
index 0000000..a4d7b06
--- /dev/null
+++ b/test/pg_upgrade/plant_guard.sql
@@ -0,0 +1,14 @@
+-- Dependency guard (advanced-extension-testing.md #4): plants an object
+-- with a hard pg_depend dependency on a stable, never-dropped/redefined
+-- extension member (null_count(anyarray), unchanged since 0.9.0), so that a
+-- non-CASCADE DROP EXTENSION count_nulls is blocked. Used by the pg_upgrade
+-- CI job to prove a real pg_upgrade/update run didn't silently destroy the
+-- extension it's meant to be testing (a stray CASCADE drop, a logic bug, a
+-- bad CI step would otherwise fall through to a silent fresh reinstall and
+-- the job would still report green).
+--
+-- Usage: psql -v ON_ERROR_STOP=1 -v schema=<schema> -f plant_guard.sql
+\set ON_ERROR_STOP on
+CREATE SCHEMA IF NOT EXISTS count_nulls_drop_guard;
+CREATE OR REPLACE VIEW count_nulls_drop_guard.guard AS
+  SELECT :"schema".null_count(NULL::int, NULL::int) AS guarded_member;

From 57b6d78f9fa72dee47c37eac6d9630d183d4de8d Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Wed, 22 Jul 2026 17:44:41 -0500
Subject: [PATCH 05/12] Wire extension-update-test and pg-upgrade-test jobs
 into CI

- test: unchanged fresh-install job, now also matrixed over TEST_SCHEMA
  (public, Quoted) via the environment (Make imports it automatically).
- extension-update-test: installs 0.9.6, plants + proves the dependency
  guard, ALTER EXTENSION UPDATEs to current, runs the suite against the
  result in existing mode - across the PG x schema matrix.
- pg-upgrade-test: installs 0.9.6 on an old cluster, plants the guard,
  binary pg_upgrades to a newer cluster, updates to current, runs the suite
  against the real migrated objects in existing mode. A small old_pg/new_pg
  matrix (10->17, 12->17) x schema, not the full PG matrix, to keep cost
  reasonable given this is the most expensive job (installs two full
  PostgreSQL majors and runs the real pg_upgrade binary per leg).
- changes: cheap docs-only gate so the three heavy jobs above can skip
  themselves on doc-only pushes without leaving the required check stuck
  Pending.
- all-checks-passed: single stable required-status-check name; asserts its
  own needs list matches the actual job set so a new job can't be silently
  omitted from the gate.

Locally validated end to end on this container's PG12/PG17 clusters,
including a real binary pg_upgrade (PG12 -> PG17, extension carried at
0.9.6, updated to 1.0.0, guard proven through every step) before trusting
this as CI YAML.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 253 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 252 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d4aaec9..e0eb7ed 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,13 +1,93 @@
 name: CI
 on: [push, pull_request]
 jobs:
+  # Cheap gate that lets the heavy jobs below skip themselves on commits that
+  # touch only docs. Must run on every push/pull_request (no paths-ignore on
+  # the workflow itself), otherwise the required all-checks-passed check
+  # would never report on doc-only pushes and get stuck Pending in branch
+  # protection.
+  changes:
+    name: 🔍 Detect docs-only changes
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.diff.outputs.docs_only }}
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+        with:
+          # Full history needed so BASE and HEAD below are both reachable
+          # for `git diff`.
+          fetch-depth: 0
+      - name: Compute per-push changed files
+        id: diff
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ] && \
+             [ "${{ github.event.action }}" = "synchronize" ] && \
+             [ -n "${{ github.event.before }}" ]; then
+            # A push to an already-open PR: before/after give the true
+            # per-push diff, same as for a branch push.
+            BASE="${{ github.event.before }}"
+            HEAD="${{ github.event.after }}"
+          elif [ "${{ github.event_name }}" = "pull_request" ]; then
+            # First run for this PR (opened/reopened/etc, or synchronize
+            # without a usable before): fall back to the whole base...head
+            # diff.
+            BASE="${{ github.event.pull_request.base.sha }}"
+            HEAD="${{ github.event.pull_request.head.sha }}"
+          else
+            BASE="${{ github.event.before }}"
+            HEAD="${{ github.event.after }}"
+          fi
+
+          echo "base=$BASE"
+          echo "head=$HEAD"
+
+          # Fail-safe: a missing HEAD, or an all-zeros BASE (e.g. a new
+          # branch's first push, where GitHub reports no prior commit),
+          # means we can't compute a real diff. Run the full matrix rather
+          # than risk skipping tests.
+          if [ -z "$HEAD" ] || [ -z "$BASE" ] || [[ "$BASE" =~ ^0+$ ]]; then
+            echo "docs_only=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          CHANGED=$(git diff --name-only "$BASE" "$HEAD" || echo __DIFF_FAILED__)
+
+          DOCS_ONLY=true
+          if [ "$CHANGED" = "__DIFF_FAILED__" ] || [ -z "$CHANGED" ]; then
+            DOCS_ONLY=false
+          else
+            while IFS= read -r f; do
+              if ! [[ "$f" =~ \.(md|asc)$ ]]; then
+                DOCS_ONLY=false
+                break
+              fi
+            done <<< "$CHANGED"
+          fi
+
+          echo "changed files:"
+          echo "$CHANGED"
+          echo "docs_only=$DOCS_ONLY" >> "$GITHUB_OUTPUT"
+
+  # Baseline: fresh CREATE EXTENSION, across the PG matrix AND a schema
+  # matrix (TEST_SCHEMA, picked up from the environment by test/deps.sql via
+  # the count_nulls.test_schema GUC - see the Makefile). 'public' is the
+  # common case; 'Quoted' requires SQL identifier quoting (mixed case -
+  # unquoted would fold to lowercase and silently test 'public' again),
+  # exercising the suite's %I schema-qualification rather than just its
+  # literal test data.
   test:
+    needs: [changes]
+    if: needs.changes.outputs.docs_only != 'true'
     strategy:
       matrix:
         pg: [17, 16, 15, 14, 13, 12, 11, 10]
-    name: 🐘 PostgreSQL ${{ matrix.pg }}
+        schema: [public, Quoted]
+    name: 🐘 PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema }})
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
+    env:
+      TEST_SCHEMA: ${{ matrix.schema }}
     steps:
       - name: Start PostgreSQL ${{ matrix.pg }}
         run: pg-start ${{ matrix.pg }}
@@ -15,3 +95,174 @@ jobs:
         uses: actions/checkout@v4
       - name: Test on PostgreSQL ${{ matrix.pg }}
         run: pg-build-test
+
+  # Proves the in-place extension update path: CREATE EXTENSION at the
+  # oldest version we still ship a full install script for (0.9.6), then
+  # ALTER EXTENSION UPDATE (no pg_upgrade, same PostgreSQL), then run the
+  # FULL suite against the updated database (same expected output as a
+  # fresh install of the same schema, so an updated DB must behave
+  # identically). Complements pg-upgrade-test, which covers the
+  # cross-major-version binary upgrade instead.
+  extension-update-test:
+    needs: [changes]
+    if: needs.changes.outputs.docs_only != 'true'
+    strategy:
+      matrix:
+        pg: [17, 16, 15, 14, 13, 12, 11, 10]
+        schema: [public, Quoted]
+    name: ⬆️ Extension update test on PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema }})
+    runs-on: ubuntu-latest
+    container: pgxn/pgxn-tools
+    steps:
+      - name: Start PostgreSQL ${{ matrix.pg }}
+        run: pg-start ${{ matrix.pg }}
+      - name: Check out the repo
+        uses: actions/checkout@v4
+      - name: Install count_nulls
+        run: make install
+      - name: Update 0.9.6 -> current and run the suite (existing mode)
+        # update-scenario creates a real database at 0.9.6, 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
+        # blocked a drop, before dropping it itself - see bin/test_existing).
+        run: bin/test_existing update-scenario count_nulls_update "${{ matrix.schema }}" 0.9.6
+
+  # Proves count_nulls survives a BINARY pg_upgrade (in-place catalog
+  # migration to a newer PostgreSQL major), not just an in-place extension
+  # update. Installs 0.9.6 on an old cluster, plants a dependency guard,
+  # binary-pg_upgrades to a newer cluster, updates the extension to current,
+  # then runs the suite against the REAL migrated objects in existing mode.
+  # No bridge-update step (unlike cat_tools's pg-upgrade-test, which has to
+  # dig itself out of pg_upgrade-unsafe versions it shipped before this
+  # testing pattern existed): count_nulls has always been pure SQL functions
+  # with no SELECT-*-over-catalog views, so it has no known
+  # pg_upgrade-unsafe old version to bridge past
+  # (advanced-extension-testing.md #7/#9).
+  pg-upgrade-test:
+    needs: [changes]
+    if: needs.changes.outputs.docs_only != 'true'
+    strategy:
+      matrix:
+        include:
+          - old_pg: "10"
+            new_pg: "17"
+            schema: public
+          - old_pg: "10"
+            new_pg: "17"
+            schema: Quoted
+          - old_pg: "12"
+            new_pg: "17"
+            schema: public
+          - old_pg: "12"
+            new_pg: "17"
+            schema: Quoted
+    name: 🔄 Binary pg_upgrade ${{ matrix.old_pg }} → ${{ matrix.new_pg }} (schema ${{ matrix.schema }})
+    runs-on: ubuntu-latest
+    container: pgxn/pgxn-tools
+    env:
+      # Both clusters must use the same initdb options or pg_upgrade
+      # refuses to run.
+      INITDB_OPTS: --data-checksums --auth trust
+    steps:
+      - name: Start PostgreSQL ${{ matrix.old_pg }}
+        run: pg-start ${{ matrix.old_pg }}
+      - name: Recreate old cluster with data checksums enabled
+        run: |
+          pg_ctlcluster ${{ matrix.old_pg }} test stop
+          pg_dropcluster ${{ matrix.old_pg }} test
+          # -p 5432: pg_createcluster assigns the next available port, which
+          # may not be 5432 after pg-start has claimed and released it.
+          # Force 5432 so subsequent psql/createdb calls connect without -p.
+          pg_createcluster -p 5432 ${{ matrix.old_pg }} test -- $INITDB_OPTS
+          pg_ctlcluster ${{ matrix.old_pg }} test start
+          pg_isready -t 30
+      - name: Check out the repo
+        uses: actions/checkout@v4
+      - name: Install count_nulls into old cluster
+        run: make install
+      - name: Prepare the old cluster (install + dependency guard)
+        # prepare-old installs count_nulls at 0.9.6 in the leg's schema,
+        # then plants + proves the dependency guard, so a later accidental
+        # CASCADE drop anywhere in this job cannot silently make the
+        # eventual existing-mode run test a fresh install instead.
+        run: bin/test_existing prepare-old count_nulls_upgrade "${{ matrix.schema }}" 0.9.6
+      - name: Install PostgreSQL ${{ matrix.new_pg }}
+        run: apt-get install -y postgresql-${{ matrix.new_pg }} postgresql-server-dev-${{ matrix.new_pg }}
+      - name: Install count_nulls into new cluster
+        # PG_CONFIG must be specified explicitly: at this point both old
+        # and new PostgreSQL are installed, and the default pg_config on
+        # PATH may not be the new version's.
+        run: make install PG_CONFIG=/usr/lib/postgresql/${{ matrix.new_pg }}/bin/pg_config
+      - name: Stop old cluster, binary pg_upgrade to PostgreSQL ${{ matrix.new_pg }}, start new cluster
+        run: |
+          pg_ctlcluster ${{ matrix.old_pg }} test stop
+          pg_createcluster -p 5432 ${{ matrix.new_pg }} test -- $INITDB_OPTS
+          # PG17+ writes logs to $new_datadir/pg_upgrade_output.d/; older
+          # versions write to CWD. Search both on failure.
+          mkdir -p /tmp/pg_upgrade_logs
+          chown postgres:postgres /tmp/pg_upgrade_logs
+          su -c "cd /tmp/pg_upgrade_logs && /usr/lib/postgresql/${{ matrix.new_pg }}/bin/pg_upgrade \
+            -b /usr/lib/postgresql/${{ matrix.old_pg }}/bin \
+            -B /usr/lib/postgresql/${{ matrix.new_pg }}/bin \
+            -d /var/lib/postgresql/${{ matrix.old_pg }}/test \
+            -D /var/lib/postgresql/${{ matrix.new_pg }}/test \
+            -o '-c config_file=/etc/postgresql/${{ matrix.old_pg }}/test/postgresql.conf' \
+            -O '-c config_file=/etc/postgresql/${{ matrix.new_pg }}/test/postgresql.conf'" postgres \
+            || { find /tmp/pg_upgrade_logs \
+                      /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: Update the pg_upgraded extension to the current version
+        # Exercises ALTER EXTENSION UPDATE on genuinely pg_upgraded objects
+        # (the extension binary pg_upgrade just migrated), running the
+        # 0.9.6->1.0.0 update script.
+        run: bin/test_existing update count_nulls_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),
+        # drops the guard, 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: bin/test_existing run-suite count_nulls_upgrade "${{ matrix.schema }}"
+
+  # A single stable check name for use as a required status check in branch
+  # protection rules. Matrix jobs produce check names like
+  # "🐘 PostgreSQL 14 (schema public)" which would all need to be listed
+  # individually and updated whenever the matrix changes. This job passes if
+  # all others passed or were skipped (e.g. the heavy jobs gated off by the
+  # `changes` job on a docs-only push), and fails if any failed or were
+  # cancelled.
+  all-checks-passed:
+    needs: [changes, test, extension-update-test, pg-upgrade-test]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify all jobs are listed in needs
+        # Ensures this job won't silently ignore a newly-added job that was
+        # omitted from the needs list above.
+        run: |
+          DEFINED=$(python3 -c "
+          import yaml
+          with open('.github/workflows/ci.yml') as f:
+              w = yaml.safe_load(f)
+          print('\n'.join(sorted(j for j in w['jobs'] if j != 'all-checks-passed')))
+          ")
+          NEEDED=$(echo '${{ toJson(needs) }}' | python3 -c "
+          import json, sys
+          print('\n'.join(sorted(json.load(sys.stdin))))
+          ")
+          if [ "$DEFINED" != "$NEEDED" ]; then
+            echo "Some jobs are missing from all-checks-passed needs:"
+            diff <(echo "$DEFINED") <(echo "$NEEDED")
+            exit 1
+          fi
+      - name: Check all jobs passed or were skipped
+        run: |
+          if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
+            echo "One or more jobs failed or were cancelled"
+            exit 1
+          fi
+# vi: expandtab ts=2 sw=2

From 8292c5601d3772980f5352b1a1462b9e680c8d6c Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Wed, 22 Jul 2026 18:13:45 -0500
Subject: [PATCH 06/12] Regenerate expected output for the schema-parameterized
 suite

test/expected/extension_tests.out: regenerated via `make results` against
the new default (TEST_SCHEMA=public) - the only change is the schema name
throughout (schema_to_load_count_nulls -> public), consistent with deps.sql
now installing every test file into the same run-wide schema instead of a
different literal per file. simple.out/sanity.out are byte-identical to
before (they already defaulted to 'public').

test/expected/{extension_tests,simple}_1.out: pg_regress's alternate-
expected-file convention, for the TEST_SCHEMA=Quoted CI legs (a schema name
requiring SQL identifier quoting - mixed case, so unquoted would fold to
lowercase and silently retest 'public'). Captured from a real
`make test TEST_SCHEMA=Quoted` run with zero TAP-level failures (`grep -c
'^not ok' test/results/*.out` = 0 in every file) - the only difference from
the default expected output is the schema name. sanity.out needs no
alternate: its assertions are all unqualified, so its output doesn't vary by
schema.

Verified after regenerating: `make test`, `make test-update`,
`make test TEST_SCHEMA=Quoted` and `make test-update TEST_SCHEMA=Quoted`
all report "All 3 tests passed" with zero regression.diffs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 test/expected/extension_tests.out   | 88 ++++++++++++++---------------
 test/expected/extension_tests_1.out | 87 ++++++++++++++++++++++++++++
 test/expected/simple_1.out          | 71 +++++++++++++++++++++++
 3 files changed, 202 insertions(+), 44 deletions(-)
 create mode 100644 test/expected/extension_tests_1.out
 create mode 100644 test/expected/simple_1.out

diff --git a/test/expected/extension_tests.out b/test/expected/extension_tests.out
index 3a22c24..3d213b5 100644
--- a/test/expected/extension_tests.out
+++ b/test/expected/extension_tests.out
@@ -1,80 +1,80 @@
 \set ECHO none
 # Subtest: _null_count_test.test__check_ncs()
     ok 1
-    ok 2 - schema schema_to_load_count_nulls should not be in search path
+    ok 2 - schema public should not be in search path
     1..2
 ok 1 - _null_count_test.test__check_ncs
 # Subtest: _null_count_test.test__definition()
     ok 1 - ensure null_count({anyarray}) is not in search_path
-    ok 2 - Function schema_to_load_count_nulls.null_count(anyarray) should return integer
-    ok 3 - Function schema_to_load_count_nulls.null_count(anyarray) should not be strict
-    ok 4 - Function schema_to_load_count_nulls.null_count(anyarray) should be IMMUTABLE
+    ok 2 - Function public.null_count(anyarray) should return integer
+    ok 3 - Function public.null_count(anyarray) should not be strict
+    ok 4 - Function public.null_count(anyarray) should be IMMUTABLE
     ok 5 - ensure null_count({json}) is not in search_path
-    ok 6 - Function schema_to_load_count_nulls.null_count(json) should return integer
-    ok 7 - Function schema_to_load_count_nulls.null_count(json) should not be strict
-    ok 8 - Function schema_to_load_count_nulls.null_count(json) should be IMMUTABLE
+    ok 6 - Function public.null_count(json) should return integer
+    ok 7 - Function public.null_count(json) should not be strict
+    ok 8 - Function public.null_count(json) should be IMMUTABLE
     ok 9 - ensure null_count({jsonb}) is not in search_path
-    ok 10 - Function schema_to_load_count_nulls.null_count(jsonb) should return integer
-    ok 11 - Function schema_to_load_count_nulls.null_count(jsonb) should not be strict
-    ok 12 - Function schema_to_load_count_nulls.null_count(jsonb) should be IMMUTABLE
+    ok 10 - Function public.null_count(jsonb) should return integer
+    ok 11 - Function public.null_count(jsonb) should not be strict
+    ok 12 - Function public.null_count(jsonb) should be IMMUTABLE
     ok 13 - ensure not_null_count({anyarray}) is not in search_path
-    ok 14 - Function schema_to_load_count_nulls.not_null_count(anyarray) should return integer
-    ok 15 - Function schema_to_load_count_nulls.not_null_count(anyarray) should not be strict
-    ok 16 - Function schema_to_load_count_nulls.not_null_count(anyarray) should be IMMUTABLE
+    ok 14 - Function public.not_null_count(anyarray) should return integer
+    ok 15 - Function public.not_null_count(anyarray) should not be strict
+    ok 16 - Function public.not_null_count(anyarray) should be IMMUTABLE
     ok 17 - ensure not_null_count({json}) is not in search_path
-    ok 18 - Function schema_to_load_count_nulls.not_null_count(json) should return integer
-    ok 19 - Function schema_to_load_count_nulls.not_null_count(json) should not be strict
-    ok 20 - Function schema_to_load_count_nulls.not_null_count(json) should be IMMUTABLE
+    ok 18 - Function public.not_null_count(json) should return integer
+    ok 19 - Function public.not_null_count(json) should not be strict
+    ok 20 - Function public.not_null_count(json) should be IMMUTABLE
     ok 21 - ensure not_null_count({jsonb}) is not in search_path
-    ok 22 - Function schema_to_load_count_nulls.not_null_count(jsonb) should return integer
-    ok 23 - Function schema_to_load_count_nulls.not_null_count(jsonb) should not be strict
-    ok 24 - Function schema_to_load_count_nulls.not_null_count(jsonb) should be IMMUTABLE
-    ok 25 - Function schema_to_load_count_nulls.null_count_trigger() should return trigger
-    ok 26 - Function schema_to_load_count_nulls.null_count_trigger() should not be strict
-    ok 27 - Function schema_to_load_count_nulls.null_count_trigger() should be IMMUTABLE
-    ok 28 - Function schema_to_load_count_nulls.not_null_count_trigger() should return trigger
-    ok 29 - Function schema_to_load_count_nulls.not_null_count_trigger() should not be strict
-    ok 30 - Function schema_to_load_count_nulls.not_null_count_trigger() should be IMMUTABLE
+    ok 22 - Function public.not_null_count(jsonb) should return integer
+    ok 23 - Function public.not_null_count(jsonb) should not be strict
+    ok 24 - Function public.not_null_count(jsonb) should be IMMUTABLE
+    ok 25 - Function public.null_count_trigger() should return trigger
+    ok 26 - Function public.null_count_trigger() should not be strict
+    ok 27 - Function public.null_count_trigger() should be IMMUTABLE
+    ok 28 - Function public.not_null_count_trigger() should return trigger
+    ok 29 - Function public.not_null_count_trigger() should not be strict
+    ok 30 - Function public.not_null_count_trigger() should be IMMUTABLE
     1..30
 ok 2 - _null_count_test.test__definition
 # Subtest: _null_count_test.test__functionality()
-    ok 1 - Test schema_to_load_count_nulls.null_count(a, b, c)
-    ok 2 - Test schema_to_load_count_nulls.null_count(json)
-    ok 3 - Test schema_to_load_count_nulls.null_count(jsonb)
-    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.not_null_count_trigger( NULL )
-    ok 5 - Test schema_to_load_count_nulls.not_null_count_trigger( NULL )
+    ok 1 - Test public.null_count(a, b, c)
+    ok 2 - Test public.null_count(json)
+    ok 3 - Test public.null_count(jsonb)
+    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger( NULL )
+    ok 5 - Test public.not_null_count_trigger( NULL )
     ok 6 - DROP TRIGGER "test trigger"
-    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.not_null_count_trigger(  )
-    ok 8 - Test schema_to_load_count_nulls.not_null_count_trigger(  )
+    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(  )
+    ok 8 - Test public.not_null_count_trigger(  )
     ok 9 - DROP TRIGGER "test trigger"
-    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.null_count_trigger( NULL )
-    ok 11 - Test schema_to_load_count_nulls.null_count_trigger( NULL )
+    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger( NULL )
+    ok 11 - Test public.null_count_trigger( NULL )
     ok 12 - DROP TRIGGER "test trigger"
-    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.null_count_trigger(  )
-    ok 14 - Test schema_to_load_count_nulls.null_count_trigger(  )
+    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(  )
+    ok 14 - Test public.null_count_trigger(  )
     ok 15 - DROP TRIGGER "test trigger"
-    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.null_count_trigger(1, 'error_message')
+    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, 'error_message')
     ok 17 - Test "null_BEFORE_error_message"
     ok 18 - DROP TRIGGER "null_BEFORE_error_message"
-    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.null_count_trigger(1, 'error_message')
+    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, 'error_message')
     ok 20 - Test "null_AFTER_error_message"
     ok 21 - DROP TRIGGER "null_AFTER_error_message"
-    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.not_null_count_trigger(1, 'error_message')
+    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, 'error_message')
     ok 23 - Test "not_null_BEFORE_error_message"
     ok 24 - DROP TRIGGER "not_null_BEFORE_error_message"
-    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.not_null_count_trigger(1, 'error_message')
+    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, 'error_message')
     ok 26 - Test "not_null_AFTER_error_message"
     ok 27 - DROP TRIGGER "not_null_AFTER_error_message"
-    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.null_count_trigger(1, NULL)
+    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, NULL)
     ok 29 - Test "null_BEFORE_"
     ok 30 - DROP TRIGGER "null_BEFORE_"
-    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.null_count_trigger(1, NULL)
+    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, NULL)
     ok 32 - Test "null_AFTER_"
     ok 33 - DROP TRIGGER "null_AFTER_"
-    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.not_null_count_trigger(1, NULL)
+    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, NULL)
     ok 35 - Test "not_null_BEFORE_"
     ok 36 - DROP TRIGGER "not_null_BEFORE_"
-    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE schema_to_load_count_nulls.not_null_count_trigger(1, NULL)
+    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, NULL)
     ok 38 - Test "not_null_AFTER_"
     ok 39 - DROP TRIGGER "not_null_AFTER_"
     1..39
diff --git a/test/expected/extension_tests_1.out b/test/expected/extension_tests_1.out
new file mode 100644
index 0000000..7466a35
--- /dev/null
+++ b/test/expected/extension_tests_1.out
@@ -0,0 +1,87 @@
+\set ECHO none
+# Subtest: _null_count_test.test__check_ncs()
+    ok 1
+    ok 2 - schema "Quoted" should not be in search path
+    1..2
+ok 1 - _null_count_test.test__check_ncs
+# Subtest: _null_count_test.test__definition()
+    ok 1 - ensure null_count({anyarray}) is not in search_path
+    ok 2 - Function "Quoted".null_count(anyarray) should return integer
+    ok 3 - Function "Quoted".null_count(anyarray) should not be strict
+    ok 4 - Function "Quoted".null_count(anyarray) should be IMMUTABLE
+    ok 5 - ensure null_count({json}) is not in search_path
+    ok 6 - Function "Quoted".null_count(json) should return integer
+    ok 7 - Function "Quoted".null_count(json) should not be strict
+    ok 8 - Function "Quoted".null_count(json) should be IMMUTABLE
+    ok 9 - ensure null_count({jsonb}) is not in search_path
+    ok 10 - Function "Quoted".null_count(jsonb) should return integer
+    ok 11 - Function "Quoted".null_count(jsonb) should not be strict
+    ok 12 - Function "Quoted".null_count(jsonb) should be IMMUTABLE
+    ok 13 - ensure not_null_count({anyarray}) is not in search_path
+    ok 14 - Function "Quoted".not_null_count(anyarray) should return integer
+    ok 15 - Function "Quoted".not_null_count(anyarray) should not be strict
+    ok 16 - Function "Quoted".not_null_count(anyarray) should be IMMUTABLE
+    ok 17 - ensure not_null_count({json}) is not in search_path
+    ok 18 - Function "Quoted".not_null_count(json) should return integer
+    ok 19 - Function "Quoted".not_null_count(json) should not be strict
+    ok 20 - Function "Quoted".not_null_count(json) should be IMMUTABLE
+    ok 21 - ensure not_null_count({jsonb}) is not in search_path
+    ok 22 - Function "Quoted".not_null_count(jsonb) should return integer
+    ok 23 - Function "Quoted".not_null_count(jsonb) should not be strict
+    ok 24 - Function "Quoted".not_null_count(jsonb) should be IMMUTABLE
+    ok 25 - Function "Quoted".null_count_trigger() should return trigger
+    ok 26 - Function "Quoted".null_count_trigger() should not be strict
+    ok 27 - Function "Quoted".null_count_trigger() should be IMMUTABLE
+    ok 28 - Function "Quoted".not_null_count_trigger() should return trigger
+    ok 29 - Function "Quoted".not_null_count_trigger() should not be strict
+    ok 30 - Function "Quoted".not_null_count_trigger() should be IMMUTABLE
+    1..30
+ok 2 - _null_count_test.test__definition
+# Subtest: _null_count_test.test__functionality()
+    ok 1 - Test "Quoted".null_count(a, b, c)
+    ok 2 - Test "Quoted".null_count(json)
+    ok 3 - Test "Quoted".null_count(jsonb)
+    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger( NULL )
+    ok 5 - Test "Quoted".not_null_count_trigger( NULL )
+    ok 6 - DROP TRIGGER "test trigger"
+    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(  )
+    ok 8 - Test "Quoted".not_null_count_trigger(  )
+    ok 9 - DROP TRIGGER "test trigger"
+    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger( NULL )
+    ok 11 - Test "Quoted".null_count_trigger( NULL )
+    ok 12 - DROP TRIGGER "test trigger"
+    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(  )
+    ok 14 - Test "Quoted".null_count_trigger(  )
+    ok 15 - DROP TRIGGER "test trigger"
+    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, 'error_message')
+    ok 17 - Test "null_BEFORE_error_message"
+    ok 18 - DROP TRIGGER "null_BEFORE_error_message"
+    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, 'error_message')
+    ok 20 - Test "null_AFTER_error_message"
+    ok 21 - DROP TRIGGER "null_AFTER_error_message"
+    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, 'error_message')
+    ok 23 - Test "not_null_BEFORE_error_message"
+    ok 24 - DROP TRIGGER "not_null_BEFORE_error_message"
+    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, 'error_message')
+    ok 26 - Test "not_null_AFTER_error_message"
+    ok 27 - DROP TRIGGER "not_null_AFTER_error_message"
+    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, NULL)
+    ok 29 - Test "null_BEFORE_"
+    ok 30 - DROP TRIGGER "null_BEFORE_"
+    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, NULL)
+    ok 32 - Test "null_AFTER_"
+    ok 33 - DROP TRIGGER "null_AFTER_"
+    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, NULL)
+    ok 35 - Test "not_null_BEFORE_"
+    ok 36 - DROP TRIGGER "not_null_BEFORE_"
+    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, NULL)
+    ok 38 - Test "not_null_AFTER_"
+    ok 39 - DROP TRIGGER "not_null_AFTER_"
+    1..39
+ok 3 - _null_count_test.test__functionality
+# Subtest: _null_count_test.test__shutdown__drop_all()
+    ok 1
+    ok 2
+    1..2
+ok 4 - _null_count_test.test__shutdown__drop_all
+1..4
diff --git a/test/expected/simple_1.out b/test/expected/simple_1.out
new file mode 100644
index 0000000..39b3388
--- /dev/null
+++ b/test/expected/simple_1.out
@@ -0,0 +1,71 @@
+\set ECHO none
+# Subtest: _null_count_test.test__definition()
+    ok 1 - Function "Quoted".null_count(anyarray) should return integer
+    ok 2 - Function "Quoted".null_count(anyarray) should not be strict
+    ok 3 - Function "Quoted".null_count(anyarray) should be IMMUTABLE
+    ok 4 - Function "Quoted".null_count(json) should return integer
+    ok 5 - Function "Quoted".null_count(json) should not be strict
+    ok 6 - Function "Quoted".null_count(json) should be IMMUTABLE
+    ok 7 - Function "Quoted".null_count(jsonb) should return integer
+    ok 8 - Function "Quoted".null_count(jsonb) should not be strict
+    ok 9 - Function "Quoted".null_count(jsonb) should be IMMUTABLE
+    ok 10 - Function "Quoted".not_null_count(anyarray) should return integer
+    ok 11 - Function "Quoted".not_null_count(anyarray) should not be strict
+    ok 12 - Function "Quoted".not_null_count(anyarray) should be IMMUTABLE
+    ok 13 - Function "Quoted".not_null_count(json) should return integer
+    ok 14 - Function "Quoted".not_null_count(json) should not be strict
+    ok 15 - Function "Quoted".not_null_count(json) should be IMMUTABLE
+    ok 16 - Function "Quoted".not_null_count(jsonb) should return integer
+    ok 17 - Function "Quoted".not_null_count(jsonb) should not be strict
+    ok 18 - Function "Quoted".not_null_count(jsonb) should be IMMUTABLE
+    ok 19 - Function "Quoted".null_count_trigger() should return trigger
+    ok 20 - Function "Quoted".null_count_trigger() should not be strict
+    ok 21 - Function "Quoted".null_count_trigger() should be IMMUTABLE
+    ok 22 - Function "Quoted".not_null_count_trigger() should return trigger
+    ok 23 - Function "Quoted".not_null_count_trigger() should not be strict
+    ok 24 - Function "Quoted".not_null_count_trigger() should be IMMUTABLE
+    1..24
+ok 1 - _null_count_test.test__definition
+# Subtest: _null_count_test.test__functionality()
+    ok 1 - Test "Quoted".null_count(a, b, c)
+    ok 2 - Test "Quoted".null_count(json)
+    ok 3 - Test "Quoted".null_count(jsonb)
+    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger( NULL )
+    ok 5 - Test "Quoted".not_null_count_trigger( NULL )
+    ok 6 - DROP TRIGGER "test trigger"
+    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(  )
+    ok 8 - Test "Quoted".not_null_count_trigger(  )
+    ok 9 - DROP TRIGGER "test trigger"
+    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger( NULL )
+    ok 11 - Test "Quoted".null_count_trigger( NULL )
+    ok 12 - DROP TRIGGER "test trigger"
+    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(  )
+    ok 14 - Test "Quoted".null_count_trigger(  )
+    ok 15 - DROP TRIGGER "test trigger"
+    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, 'error_message')
+    ok 17 - Test "null_BEFORE_error_message"
+    ok 18 - DROP TRIGGER "null_BEFORE_error_message"
+    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, 'error_message')
+    ok 20 - Test "null_AFTER_error_message"
+    ok 21 - DROP TRIGGER "null_AFTER_error_message"
+    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, 'error_message')
+    ok 23 - Test "not_null_BEFORE_error_message"
+    ok 24 - DROP TRIGGER "not_null_BEFORE_error_message"
+    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, 'error_message')
+    ok 26 - Test "not_null_AFTER_error_message"
+    ok 27 - DROP TRIGGER "not_null_AFTER_error_message"
+    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, NULL)
+    ok 29 - Test "null_BEFORE_"
+    ok 30 - DROP TRIGGER "null_BEFORE_"
+    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, NULL)
+    ok 32 - Test "null_AFTER_"
+    ok 33 - DROP TRIGGER "null_AFTER_"
+    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, NULL)
+    ok 35 - Test "not_null_BEFORE_"
+    ok 36 - DROP TRIGGER "not_null_BEFORE_"
+    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, NULL)
+    ok 38 - Test "not_null_AFTER_"
+    ok 39 - DROP TRIGGER "not_null_AFTER_"
+    1..39
+ok 2 - _null_count_test.test__functionality
+1..2

From 6667ae1a35364dcf2db0fc83c249251234ec9413 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Wed, 22 Jul 2026 18:46:19 -0500
Subject: [PATCH 07/12] CI: derive the supported-PostgreSQL-major list from a
 single source

Taken near-verbatim from Postgres-Extensions/cat_tools PR #48: the changes
job now derives the PG matrix list from two constants (NEWEST, FLOOR) and
emits it as a job output, consumed by both the `test` and
`extension-update-test` matrices via fromJSON. Previously both jobs
hardcoded the same [17..10] list independently - exactly the drift risk this
fixes (a new PG major meant editing two places, and forgetting one would
silently undertest it).

count_nulls needs only ONE floor, unlike cat_tools's three-constant version
(NEWEST/CURRENT_FLOOR/LEGACY_FLOOR): 0.9.6 is pure SQL over anyarray/json/
jsonb with no catalog-version sensitivity, so it installs on every supported
major - there's no PG10-only legacy leg to carve out the way cat_tools's
pre-0.2.2 scripts need.

Also documents, at pg-upgrade-test, the deliberate decision NOT to add
cat_tools's companion pg-upgrade-stepwise job (one cluster climbing every
major in sequence): that job protects against a regression at one specific
major-to-major boundary, relevant to cat_tools's catalog-touching views but
not to count_nulls's pure SQL functions.

Pure refactor - the derived list resolves to the same PG majors as before
([17,16,15,14,13,12,11,10]), confirmed by running the bash derivation
standalone.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 53 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e0eb7ed..f04ee8e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,11 +6,18 @@ jobs:
   # the workflow itself), otherwise the required all-checks-passed check
   # would never report on doc-only pushes and get stuck Pending in branch
   # protection.
+  #
+  # Also derives, from a SINGLE set of constants, the supported-PostgreSQL-
+  # major list the test / extension-update jobs consume (see the "Derive ..."
+  # step) - per Postgres-Extensions/cat_tools PR #48, taken near-verbatim:
+  # count_nulls has no legacy-floor complication (unlike cat_tools's PG10-only
+  # pre-0.2.2 scripts), so this needs only ONE list, not cat_tools's three.
   changes:
-    name: 🔍 Detect docs-only changes
+    name: 🔍 Detect docs-only changes & derive PG matrix
     runs-on: ubuntu-latest
     outputs:
       docs_only: ${{ steps.diff.outputs.docs_only }}
+      supported_pg: ${{ steps.pg.outputs.supported_pg }}
     steps:
       - name: Check out the repo
         uses: actions/checkout@v4
@@ -69,6 +76,34 @@ jobs:
           echo "$CHANGED"
           echo "docs_only=$DOCS_ONLY" >> "$GITHUB_OUTPUT"
 
+      - name: Derive the supported-PostgreSQL-major list
+        id: pg
+        run: |
+          # Spending a dozen-odd lines to replace what looks like a handful of
+          # version references is worth doing anyway: the point is
+          # CONSISTENCY - both the fresh-install `test` matrix and the
+          # `extension-update-test` matrix derive their PostgreSQL set from
+          # this ONE source, so they cannot silently drift onto different
+          # lists. Adding a new major is a one-line NEWEST bump here, not an
+          # edit in N places.
+          #
+          # count_nulls has only ONE floor (unlike cat_tools's separate
+          # current-version floor and legacy pre-0.2.2 floor): 0.9.6 is a
+          # pure-SQL-function install script with no catalog-version
+          # sensitivity, so it installs on every PostgreSQL major count_nulls
+          # supports - there is no PG10-only legacy leg to carve out.
+          NEWEST=17
+          FLOOR=10
+
+          supported=$(seq "$NEWEST" -1 "$FLOOR")
+
+          # Emit a JSON array from a list of ints, for the job matrices to
+          # consume with fromJSON (GitHub evaluates a literal dollar-brace
+          # expression even inside a run block, so none is written here).
+          json() { printf '%s\n' "$@" | paste -sd, - | sed 's/^/[/; s/$/]/'; }
+
+          echo "supported_pg=$(json $supported)" >> "$GITHUB_OUTPUT"
+
   # Baseline: fresh CREATE EXTENSION, across the PG matrix AND a schema
   # matrix (TEST_SCHEMA, picked up from the environment by test/deps.sql via
   # the count_nulls.test_schema GUC - see the Makefile). 'public' is the
@@ -81,7 +116,8 @@ jobs:
     if: needs.changes.outputs.docs_only != 'true'
     strategy:
       matrix:
-        pg: [17, 16, 15, 14, 13, 12, 11, 10]
+        # From the single source in the changes job.
+        pg: ${{ fromJSON(needs.changes.outputs.supported_pg) }}
         schema: [public, Quoted]
     name: 🐘 PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema }})
     runs-on: ubuntu-latest
@@ -108,7 +144,8 @@ jobs:
     if: needs.changes.outputs.docs_only != 'true'
     strategy:
       matrix:
-        pg: [17, 16, 15, 14, 13, 12, 11, 10]
+        # From the single source in the changes job.
+        pg: ${{ fromJSON(needs.changes.outputs.supported_pg) }}
         schema: [public, Quoted]
     name: ⬆️ Extension update test on PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema }})
     runs-on: ubuntu-latest
@@ -139,6 +176,16 @@ jobs:
   # with no SELECT-*-over-catalog views, so it has no known
   # pg_upgrade-unsafe old version to bridge past
   # (advanced-extension-testing.md #7/#9).
+  #
+  # Deliberately NOT adding cat_tools's companion `pg-upgrade-stepwise` job
+  # (one cluster climbing every major in sequence, vs. the single big jumps
+  # here): that job exists to catch a regression specific to one particular
+  # major-to-major boundary, which matters for cat_tools's views/functions
+  # that touch catalog internals (advanced-extension-testing.md #7) but not
+  # for count_nulls - pure SQL functions over anyarray/json/jsonb, nothing
+  # version-sensitive to break at a specific boundary. The two big-jump legs
+  # below (10->17, 12->17) already cover the axis that matters here. Revisit
+  # if count_nulls ever grows something catalog-touching.
   pg-upgrade-test:
     needs: [changes]
     if: needs.changes.outputs.docs_only != 'true'

From 88614587e909193ad1a20885176e2c5c2df7719e Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 23 Jul 2026 18:15:03 -0500
Subject: [PATCH 08/12] Support TEST_SCHEMA=empty (no schema targeting) as a
 first-class mode

deps.sql previously required a non-empty schema, defaulting to 'public' -
meaning the suite only ever exercised CREATE EXTENSION with an explicitly
targeted schema, never the plain, untouched default-install code path a
brand-new user actually gets. TEST_SCHEMA is now optional: empty means don't
CREATE SCHEMA/SET search_path at all, landing wherever the session's own
ambient search_path resolves; non-empty explicitly targets that schema as
before. Both legs matter and run in CI - genuinely different code paths.

Where the extension lands when nothing targets it is not always 'public' -
this suite's own pgTAP setup already puts its own schema first on
search_path before deps.sql runs, so the empty leg lands there instead.
That's not a bug to paper over (it's actually useful: it proves nothing is
hardcoded to 'public'), so assertions that need a known expected schema
(test__check_ncs, test__shutdown__drop_all) fall back to discovering the
real location dynamically (ncs()) or skip when there's no fixed expectation,
rather than assuming one.

bin/test_existing's create_extension_in_schema helper and
bin/test_existing_sql/plant_guard.sql both gained the same empty/non-empty
branch (a quoted empty identifier is a real Postgres syntax error, so the
empty case can't just always emit `CREATE SCHEMA "" `).

Also moves test/pg_upgrade/*.sql to bin/test_existing_sql/ (they're helpers
for bin/test_existing, not part of the pg_regress suite, so they belong
under bin/ alongside the script that uses them), and removes
test/sql/simple.sql: it existed to exercise "the other" schema before
TEST_SCHEMA existed, dressed up as an on-search-path test, but
functions.sql's own calls are all %I-qualified via ncs() regardless of
search_path - so its search_path manipulation never actually changed
anything, and the schema coverage it stood in for is now done properly (and
more thoroughly - two legs, not one) by the TEST_SCHEMA matrix on
extension_tests.sql itself. Confirmed no coverage is lost: everything
simple.sql exercised (test__definition, test__functionality, via
functions.sql) already runs identically inside extension_tests.sql.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 Makefile                                      | 32 +++++---
 bin/test_existing                             | 50 +++++++-----
 .../test_existing_sql}/assert_guard.sql       | 18 +++--
 bin/test_existing_sql/drop_guard.sql          | 11 +++
 bin/test_existing_sql/plant_guard.sql         | 26 +++++++
 test/build/upgrade.sql                        | 20 ++++-
 test/core/functions.sql                       | 12 +--
 test/deps.sql                                 | 49 ++++++++----
 test/pg_upgrade/drop_guard.sql                |  9 ---
 test/pg_upgrade/plant_guard.sql               | 14 ----
 test/sql/extension_tests.sql                  | 78 +++++++++++++++----
 test/sql/sanity.sql                           | 23 ++++--
 test/sql/simple.sql                           | 14 ----
 13 files changed, 234 insertions(+), 122 deletions(-)
 rename {test/pg_upgrade => bin/test_existing_sql}/assert_guard.sql (63%)
 create mode 100644 bin/test_existing_sql/drop_guard.sql
 create mode 100644 bin/test_existing_sql/plant_guard.sql
 delete mode 100644 test/pg_upgrade/drop_guard.sql
 delete mode 100644 test/pg_upgrade/plant_guard.sql
 delete mode 100644 test/sql/simple.sql

diff --git a/Makefile b/Makefile
index 269de69..c8f6467 100644
--- a/Makefile
+++ b/Makefile
@@ -7,7 +7,8 @@ testdeps: $(wildcard test/*/*.sql) $(wildcard test/*.sql) # Be careful not to in
 # test in test/build/upgrade.sql and test/deps.sql's update mode can
 # CREATE EXTENSION count_nulls VERSION '0.9.6'.
 # Not covered by base.mk's DATA wildcard, which only picks up upgrade scripts
-# (sql/*--*--*.sql) and the current version file.
+# (sql/*--*--*.sql) and the current version file - a pgxntool bug, filed as
+# Postgres-Extensions/pgxntool#48.
 DATA += sql/count_nulls--0.9.6.sql
 
 # TEST_LOAD_SOURCE selects how test/deps.sql installs the extension for the
@@ -44,18 +45,29 @@ export PGOPTIONS := $(PGOPTIONS) -c count_nulls.test_load_mode=$(TEST_LOAD_SOURC
 # for the WHOLE test run (every test file uses the SAME schema in a given
 # run - previously each test file hardcoded its own literal schema name as a
 # stand-in for real schema-qualification coverage, which only ever tested
-# two fixed, always-lowercase names). Combined with TEST_LOAD_SOURCE this
-# drives a schema x mode CI matrix; in particular, a schema whose name
+# two fixed, always-lowercase names).
+#
+# Empty (the default): don't target any schema at all. The extension
+# installs wherever the session's own default search_path already resolves
+# (ordinarily 'public'), exercising the plain, untouched default-install
+# code path - the "without a schema" leg.
+#
+# Non-empty: explicitly CREATE SCHEMA/SET search_path to that name before
+# installing - the "with a schema" leg. In particular, a schema whose name
 # requires SQL identifier quoting (mixed case - unquoted would silently fold
-# to lowercase and test the wrong, matching schema instead) needs its own
-# leg, not just 'public'. Locally: `make test TEST_SCHEMA=Quoted`.
+# to lowercase) exercises the suite's %I schema-qualification, not just its
+# literal test data. Locally: `make test TEST_SCHEMA=Quoted`.
+#
+# Both legs matter and both run in CI - "without" and "with" are genuinely
+# different code paths (one never touches search_path, the other explicitly
+# targets a schema), not one being a redundant special case of the other.
 #
 # Propagated the same way as TEST_LOAD_SOURCE: via the count_nulls.test_schema
-# GUC, exported unconditionally through PGOPTIONS.
-TEST_SCHEMA ?= public
-ifeq ($(strip $(TEST_SCHEMA)),)
-$(error TEST_SCHEMA must not be empty)
-endif
+# GUC, exported unconditionally through PGOPTIONS. Empty is a valid,
+# deliberate value here (not an error) - deps.sql reads it without
+# missing_ok, so a truly unset GUC (the pipeline failing to propagate at all)
+# still fails loudly, while an explicitly empty one means "no schema".
+TEST_SCHEMA ?=
 export PGOPTIONS := $(PGOPTIONS) -c count_nulls.test_schema=$(TEST_SCHEMA)
 
 # Convenience wrapper: `make test-update` == `make test TEST_LOAD_SOURCE=update`.
diff --git a/bin/test_existing b/bin/test_existing
index f729760..e7cbad2 100755
--- a/bin/test_existing
+++ b/bin/test_existing
@@ -10,12 +10,12 @@
 #
 # so it lives here once instead of being duplicated as inline YAML. It is NOT
 # CI-only: a developer can run any subcommand locally against a scratch
-# database. Modeled on Postgres-Extensions/cat_tools's bin/test_existing, with
-# two differences: count_nulls has no pg_upgrade-unsafe old versions to bridge
-# past (advanced-extension-testing.md #7/#9 don't apply - it ships no
-# SELECT-*-over-catalog views), and its suite has its OWN legitimate (though
-# harmless - always rolled back) DROP EXTENSION test, so here the guard is
-# dropped before run-suite instead of surviving through it.
+# database. Modeled on Postgres-Extensions/cat_tools's bin/test_existing.
+# Two differences from that script: count_nulls ships no
+# SELECT-*-over-catalog views, so it has no known pg_upgrade-unsafe old
+# version to bridge past before running pg_upgrade; and its own suite has a
+# legitimate (though harmless - always rolled back) DROP EXTENSION test, so
+# here the guard is dropped before run-suite instead of surviving through it.
 #
 # USAGE: bin/test_existing <subcommand> [args]
 #
@@ -44,8 +44,8 @@
 # the extension, the suite would test a FRESH install and hide a regression.
 # We plant an object that HARD-references a count_nulls member so a
 # non-CASCADE DROP EXTENSION fails, and actively PROVE that (see
-# test/pg_upgrade/assert_guard.sql): if the drop unexpectedly succeeds, this
-# script fails CI rather than silently passing.
+# bin/test_existing_sql/assert_guard.sql): if the drop unexpectedly succeeds,
+# this script fails CI rather than silently passing.
 set -euo pipefail
 
 # Run from the repository root (where `make` works and test paths resolve),
@@ -93,7 +93,7 @@ guard_present() {
 # CREATE EXTENSION (and before any update/upgrade) so it persists through them.
 plant_guard() {
   local db=$1 schema=$2
-  psql -d "$db" -v ON_ERROR_STOP=1 -v schema="$schema" -f test/pg_upgrade/plant_guard.sql
+  psql -d "$db" -v ON_ERROR_STOP=1 -v schema="$schema" -f bin/test_existing_sql/plant_guard.sql
   assert_drop_blocked "$db"
 }
 
@@ -102,13 +102,13 @@ plant_guard() {
 # unexpectedly succeeds, or if the extension/guard are missing afterward.
 assert_drop_blocked() {
   local db=$1
-  psql -d "$db" -v ON_ERROR_STOP=1 -f test/pg_upgrade/assert_guard.sql
+  psql -d "$db" -v ON_ERROR_STOP=1 -f bin/test_existing_sql/assert_guard.sql
   echo "OK: non-CASCADE DROP EXTENSION is blocked in '$db' (dependency guard effective)"
 }
 
 drop_guard() {
   local db=$1
-  psql -d "$db" -v ON_ERROR_STOP=1 -f test/pg_upgrade/drop_guard.sql
+  psql -d "$db" -v ON_ERROR_STOP=1 -f bin/test_existing_sql/drop_guard.sql
 }
 
 assert_version() {
@@ -131,20 +131,33 @@ update_ext() {
   psql_do "$db" -c "ALTER EXTENSION count_nulls UPDATE $to"
 }
 
+# CREATE EXTENSION count_nulls at VERSION, targeting SCHEMA - unless SCHEMA
+# is empty, in which case it's created untouched, wherever the session's
+# own default search_path resolves (ordinarily 'public'). A quoted empty
+# identifier ("") is a real Postgres syntax error, so this can't just always
+# emit `CREATE SCHEMA IF NOT EXISTS "$schema"` - the empty case has to skip
+# that entirely, mirroring test/deps.sql's :count_nulls_has_schema branch.
+create_extension_in_schema() {
+  local db=$1 schema=$2 version=$3 sql=""
+  if [ -n "$schema" ]; then
+    sql="CREATE SCHEMA IF NOT EXISTS \"$schema\"; SET search_path = \"$schema\"; "
+  fi
+  psql_do "$db" -c "${sql}CREATE EXTENSION count_nulls VERSION '$version'"
+}
+
 # ---------------------------------------------------------------------------
 # Subcommand implementations
 # ---------------------------------------------------------------------------
 
 # prepare-old DB SCHEMA INSTALL_VERSION
 #   Old-cluster preparation for pg-upgrade-test: create the database and the
-#   extension at INSTALL_VERSION in SCHEMA, then plant + prove the guard.
-#   No bridge step (unlike cat_tools): count_nulls ships no
-#   SELECT-*-over-catalog views, so it has no known pg_upgrade-unsafe old
-#   version to bridge past (advanced-extension-testing.md #7/#9).
+#   extension at INSTALL_VERSION in SCHEMA, then plant + prove the guard. No
+#   bridge-update step first: count_nulls ships no SELECT-*-over-catalog
+#   views, so it has no known pg_upgrade-unsafe old version to bridge past.
 prepare_old() {
   local db=$1 schema=$2 install=$3
   createdb "$db"
-  psql_do "$db" -c "CREATE SCHEMA IF NOT EXISTS \"$schema\"; SET search_path = \"$schema\"; CREATE EXTENSION count_nulls VERSION '$install'"
+  create_extension_in_schema "$db" "$schema" "$install"
   plant_guard "$db" "$schema"
 }
 
@@ -156,7 +169,7 @@ prepare_old() {
 update_scenario() {
   local db=$1 schema=$2 from=$3
   createdb "$db"
-  psql_do "$db" -c "CREATE SCHEMA IF NOT EXISTS \"$schema\"; SET search_path = \"$schema\"; CREATE EXTENSION count_nulls VERSION '$from'"
+  create_extension_in_schema "$db" "$schema" "$from"
   plant_guard "$db" "$schema"
   update_ext "$db"
   run_suite "$db" "$schema"
@@ -186,8 +199,7 @@ run_suite() {
   #      - it adds nothing here.
   #   2. `make verify-results` (not just `make test`) is the real pass/fail
   #      gate: base.mk's `.IGNORE: installcheck` means `make test` prints
-  #      regression.diffs but exits 0 regardless
-  #      (advanced-extension-testing.md #8). verify-results depends on
+  #      regression.diffs but exits 0 regardless. verify-results depends on
   #      `test`, so it must carry the SAME existing-mode overrides or it
   #      would re-run FRESH (against a new throwaway DB) instead of
   #      verifying THIS existing database.
diff --git a/test/pg_upgrade/assert_guard.sql b/bin/test_existing_sql/assert_guard.sql
similarity index 63%
rename from test/pg_upgrade/assert_guard.sql
rename to bin/test_existing_sql/assert_guard.sql
index a427515..33946cf 100644
--- a/test/pg_upgrade/assert_guard.sql
+++ b/bin/test_existing_sql/assert_guard.sql
@@ -1,11 +1,13 @@
--- Proves the guard planted by plant_guard.sql actually blocks a
--- non-CASCADE DROP EXTENSION - "prove it, don't assume it"
--- (advanced-extension-testing.md #4). Re-run after every step (install,
--- pg_upgrade, post-upgrade ALTER EXTENSION UPDATE): the guard disappearing
--- at any point means a CASCADE drop happened somewhere upstream, i.e. the
--- "existing" run downstream would actually be a silent fresh install.
---
--- Usage: psql -v ON_ERROR_STOP=1 -f assert_guard.sql
+/*
+ * Proves the guard planted by plant_guard.sql actually blocks a
+ * non-CASCADE DROP EXTENSION - prove it, don't assume it. Re-run after
+ * every step (install, pg_upgrade, post-upgrade ALTER EXTENSION UPDATE):
+ * the guard disappearing at any point means a CASCADE drop happened
+ * somewhere upstream, i.e. the "existing" run downstream would actually be
+ * a silent fresh install.
+ *
+ * Usage: psql -v ON_ERROR_STOP=1 -f assert_guard.sql
+ */
 \set ON_ERROR_STOP on
 
 DO $$
diff --git a/bin/test_existing_sql/drop_guard.sql b/bin/test_existing_sql/drop_guard.sql
new file mode 100644
index 0000000..744c3b5
--- /dev/null
+++ b/bin/test_existing_sql/drop_guard.sql
@@ -0,0 +1,11 @@
+/*
+ * Removes the guard (plant_guard.sql) once its job is done - proving the
+ * install/pg_upgrade/update steps didn't corrupt the real extension - so it
+ * doesn't then block the pgTap suite's own DROP EXTENSION test
+ * (test__shutdown__drop_all, run in a transaction that's rolled back
+ * regardless, so re-dropping the real extension there is harmless).
+ *
+ * Usage: psql -v ON_ERROR_STOP=1 -f drop_guard.sql
+ */
+\set ON_ERROR_STOP on
+DROP SCHEMA count_nulls_drop_guard CASCADE;
diff --git a/bin/test_existing_sql/plant_guard.sql b/bin/test_existing_sql/plant_guard.sql
new file mode 100644
index 0000000..3e34269
--- /dev/null
+++ b/bin/test_existing_sql/plant_guard.sql
@@ -0,0 +1,26 @@
+/*
+ * Dependency guard: plants an object with a hard pg_depend dependency on a
+ * stable, never-dropped/redefined extension member (null_count(anyarray),
+ * unchanged since 0.9.0), so that a non-CASCADE DROP EXTENSION count_nulls
+ * is blocked. Used by the pg_upgrade CI job to prove a real pg_upgrade/
+ * update run didn't silently destroy the extension it's meant to be
+ * testing (a stray CASCADE drop, a logic bug, a bad CI step would
+ * otherwise fall through to a silent fresh reinstall and the job would
+ * still report green).
+ *
+ * Usage: psql -v ON_ERROR_STOP=1 -v schema=<schema-or-empty> -f plant_guard.sql
+ * (empty schema means "wherever null_count already resolves unqualified" -
+ * i.e. the extension was installed without targeting a schema).
+ */
+\set ON_ERROR_STOP on
+SELECT :'schema' <> '' AS count_nulls_has_schema
+\gset
+
+CREATE SCHEMA IF NOT EXISTS count_nulls_drop_guard;
+\if :count_nulls_has_schema
+CREATE OR REPLACE VIEW count_nulls_drop_guard.guard AS
+  SELECT :"schema".null_count(NULL::int, NULL::int) AS guarded_member;
+\else
+CREATE OR REPLACE VIEW count_nulls_drop_guard.guard AS
+  SELECT null_count(NULL::int, NULL::int) AS guarded_member;
+\endif
diff --git a/test/build/upgrade.sql b/test/build/upgrade.sql
index c5a5946..35d2c29 100644
--- a/test/build/upgrade.sql
+++ b/test/build/upgrade.sql
@@ -2,9 +2,23 @@
 \i test/pgxntool/psql.sql
 \t
 
--- Sanity check: install the oldest available version and upgrade to current.
--- sql/count_nulls--0.9.6.sql is the oldest full install script we still ship
--- (0.9.0/0.9.2/0.9.5 only exist as upgrade diffs, not standalone installs).
+/*
+ * Fast, cheap smoke check: install the oldest version we still ship a full
+ * script for and ALTER EXTENSION UPDATE to current, rolled back so it has
+ * no side effects. sql/count_nulls--0.9.6.sql is that oldest full install
+ * script (0.9.0/0.9.2/0.9.5 only exist as upgrade diffs, not standalone
+ * installs).
+ *
+ * pgxntool's test-build feature runs this automatically as part of every
+ * plain `make test` - i.e. on every PG major in the fresh-install CI
+ * matrix, before the pgTAP suite even starts. It only proves the update
+ * SQL runs without erroring, nothing about behavior, so it's not a
+ * substitute for test/deps.sql's 'update' load mode (which reruns the
+ * whole suite against the updated database - see the extension-update-test
+ * CI job) or the real binary-pg_upgrade coverage (pg-upgrade-test). Its
+ * value is failing fast and cheaply on a broken update script, across
+ * every supported PostgreSQL major, before those heavier jobs run at all.
+ */
 BEGIN;
 CREATE EXTENSION count_nulls VERSION '0.9.6';
 ALTER EXTENSION count_nulls UPDATE;
diff --git a/test/core/functions.sql b/test/core/functions.sql
index e5120b0..d2e5462 100644
--- a/test/core/functions.sql
+++ b/test/core/functions.sql
@@ -219,10 +219,12 @@ BEGIN
 END
 $body$;
 
--- Deliberately does NOT restore :"schema" (the schema count_nulls is
--- installed into) onto search_path here - whether the caller wants it there
--- (testing unqualified/on-search-path use) or not (testing fully-qualified/
--- off-search-path use) differs per test file, so each caller sets its own
--- search_path explicitly after \i'ing this file.
+/*
+ * Deliberately does NOT restore :"schema" (the schema count_nulls is
+ * installed into) onto search_path here - whether the caller wants it there
+ * (testing unqualified/on-search-path use) or not (testing fully-qualified/
+ * off-search-path use) differs per test file, so each caller sets its own
+ * search_path explicitly after \i'ing this file.
+ */
 
 -- vi: expandtab sw=2 ts=2
diff --git a/test/deps.sql b/test/deps.sql
index 458674d..dd640bc 100644
--- a/test/deps.sql
+++ b/test/deps.sql
@@ -43,36 +43,51 @@ SELECT :'count_nulls_test_load_mode' = 'existing' AS count_nulls_existing_mode
  * TEST_SCHEMA (the count_nulls.test_schema GUC, set via the Makefile):
  * which schema the extension is installed into, for the WHOLE test run -
  * the SAME schema for every test file, not a different literal hardcoded
- * per file. This is what drives the schema x mode CI matrix: at minimum
- * 'public' (the default) and a schema whose name requires SQL identifier
- * quoting (mixed case - unquoted would fold to lowercase and silently test
- * a different, matching schema instead), to exercise test files' %I
- * schema-qualification rather than just their literal test data.
+ * per file. Empty (the default) means "don't target any schema at all" -
+ * the extension lands wherever the session's own default search_path
+ * already resolves. Non-empty explicitly creates and targets that schema,
+ * including a schema whose name requires SQL identifier quoting (mixed
+ * case - unquoted would fold to lowercase), to exercise test files' %I
+ * schema-qualification rather than just their literal test data. Both the
+ * empty and non-empty cases are exercised in CI - genuinely different code
+ * paths, not one a redundant special case of the other.
  *
  * Read with :"schema" (quoted-identifier form) wherever used as a bare
  * identifier below and in the test files, since the quoting-required case
- * is exactly what this exists to exercise.
+ * is exactly what the non-empty case exists to exercise.
+ *
+ * Read without missing_ok, same reasoning as count_nulls.test_load_mode
+ * above: a genuinely unpropagated GUC must fail loudly, not be
+ * indistinguishable from a deliberately empty one.
  */
 SELECT current_setting('count_nulls.test_schema') AS schema
 \gset
+SELECT :'schema' <> '' AS count_nulls_has_schema
+\gset
 
--- :"schema" is created/searched in every mode, including 'existing', even
--- though 'existing' mode never installs the extension into it: test files
--- (e.g. test__shutdown__drop_all's `DROP SCHEMA :"schema"`) expect it to
--- exist regardless of mode, and an empty schema is harmless. IF NOT EXISTS
--- emits NOTICEs, which is annoying.
+\if :count_nulls_has_schema
+/*
+ * :"schema" is created/searched in every mode that has one, including
+ * 'existing' (even though 'existing' mode never installs the extension
+ * into it): test files (e.g. test__shutdown__drop_all's
+ * `DROP SCHEMA :"schema"`) expect it to exist regardless of mode, and an
+ * empty schema is harmless. IF NOT EXISTS emits NOTICEs, which is annoying.
+ */
 SET client_min_messages = WARNING;
 CREATE SCHEMA IF NOT EXISTS :"schema";
 SET search_path = :"schema";
 SET client_min_messages = NOTICE;
+\endif
 
 \if :count_nulls_existing_mode
--- Extension is already installed (real pg_upgrade, or an out-of-band
--- update) - assert it's present and current, but do NOT drop/create/update
--- it. The CI job driving this mode is responsible for having installed the
--- real extension into :"schema" (matching this run's TEST_SCHEMA) before
--- getting here, so the rest of the suite sees the same schema regardless of
--- mode.
+/*
+ * Extension is already installed (real pg_upgrade, or an out-of-band
+ * update) - assert it's present and current, but do NOT drop/create/update
+ * it. The CI job driving this mode is responsible for having installed the
+ * real extension matching this run's TEST_SCHEMA (or the default location,
+ * if empty) before getting here, so the rest of the suite sees the same
+ * schema regardless of mode.
+ */
 DO $$
 DECLARE
   v_installed text := (SELECT extversion FROM pg_extension WHERE extname = 'count_nulls');
diff --git a/test/pg_upgrade/drop_guard.sql b/test/pg_upgrade/drop_guard.sql
deleted file mode 100644
index ae8dd04..0000000
--- a/test/pg_upgrade/drop_guard.sql
+++ /dev/null
@@ -1,9 +0,0 @@
--- Removes the guard (plant_guard.sql) once its job is done - proving the
--- install/pg_upgrade/update steps didn't corrupt the real extension - so it
--- doesn't then block the pgTap suite's own DROP EXTENSION test
--- (test__shutdown__drop_all, run in a transaction that's rolled back
--- regardless, so re-dropping the real extension there is harmless).
---
--- Usage: psql -v ON_ERROR_STOP=1 -f drop_guard.sql
-\set ON_ERROR_STOP on
-DROP SCHEMA count_nulls_drop_guard CASCADE;
diff --git a/test/pg_upgrade/plant_guard.sql b/test/pg_upgrade/plant_guard.sql
deleted file mode 100644
index a4d7b06..0000000
--- a/test/pg_upgrade/plant_guard.sql
+++ /dev/null
@@ -1,14 +0,0 @@
--- Dependency guard (advanced-extension-testing.md #4): plants an object
--- with a hard pg_depend dependency on a stable, never-dropped/redefined
--- extension member (null_count(anyarray), unchanged since 0.9.0), so that a
--- non-CASCADE DROP EXTENSION count_nulls is blocked. Used by the pg_upgrade
--- CI job to prove a real pg_upgrade/update run didn't silently destroy the
--- extension it's meant to be testing (a stray CASCADE drop, a logic bug, a
--- bad CI step would otherwise fall through to a silent fresh reinstall and
--- the job would still report green).
---
--- Usage: psql -v ON_ERROR_STOP=1 -v schema=<schema> -f plant_guard.sql
-\set ON_ERROR_STOP on
-CREATE SCHEMA IF NOT EXISTS count_nulls_drop_guard;
-CREATE OR REPLACE VIEW count_nulls_drop_guard.guard AS
-  SELECT :"schema".null_count(NULL::int, NULL::int) AS guarded_member;
diff --git a/test/sql/extension_tests.sql b/test/sql/extension_tests.sql
index 9786fc5..2774a04 100644
--- a/test/sql/extension_tests.sql
+++ b/test/sql/extension_tests.sql
@@ -4,42 +4,86 @@
 
 \i test/core/functions.sql
 
--- Unlike simple.sql, this file deliberately leaves search_path as
--- functions.sql set it (_null_count_test, tap) - the schema count_nulls is
--- installed into (TEST_SCHEMA / test/deps.sql's :"schema") stays off
--- search_path, so every check below only passes if functions.sql's
--- %I-qualified calls (via ncs()) are actually correct, regardless of which
--- schema TEST_SCHEMA names.
+/*
+ * This file leaves search_path as functions.sql set it
+ * (_null_count_test, tap) - with an explicit TEST_SCHEMA, that keeps the
+ * extension's schema off search_path, so every check below only passes if
+ * functions.sql's %I-qualified calls (via ncs()) are actually correct,
+ * never relying on the extension's own schema being reachable unqualified.
+ * When TEST_SCHEMA is empty, the extension happens to land in 'tap' itself
+ * (wherever the ambient search_path - already tap, public at this point,
+ * via pgTap's own setup - resolves at CREATE EXTENSION time), which IS on
+ * search_path; test__check_ncs accounts for that below rather than
+ * asserting something that wouldn't hold.
+ */
 
 CREATE FUNCTION _null_count_test.test__check_ncs
 () RETURNS SETOF text LANGUAGE plpgsql AS $body$
 DECLARE
-    -- current_setting(), not a psql :"schema" substitution: psql does not
-    -- interpolate variables inside dollar-quoted function bodies.
-    s CONSTANT name = current_setting('count_nulls.test_schema')::name;
+    /*
+     * current_setting(), not a psql :"schema" substitution: psql does not
+     * interpolate variables inside dollar-quoted function bodies.
+     *
+     * When TEST_SCHEMA is non-empty we know exactly where the extension
+     * should be, so compare ncs() against that known value - a real
+     * assertion. When it's empty, there's no fixed expectation (it lands
+     * wherever the ambient search_path resolves at CREATE EXTENSION time,
+     * which depends on what ran before deps.sql - not something this test
+     * should hardcode), so fall back to ncs() itself: a no-op comparison
+     * that still exercises the call, without asserting a location this
+     * file has no business assuming.
+     */
+    s CONSTANT name = CASE
+        WHEN current_setting('count_nulls.test_schema') <> ''
+            THEN current_setting('count_nulls.test_schema')::name
+        ELSE ncs()
+    END;
 BEGIN
     RETURN NEXT is(
         ncs()
         , s
     );
-    RETURN NEXT is(
-        current_schemas(true) @> array[s]
-        , false
-        , format('schema %I should not be in search path', s)
-    );
+    /*
+     * "Not on search path" only means anything when s isn't one of the
+     * schemas functions.sql itself always puts there (_null_count_test,
+     * tap) - which happens exactly when TEST_SCHEMA is empty and the
+     * extension coincidentally lands in 'tap' (pgTap's own schema, always
+     * on search_path here). That's not a bug to work around, just a
+     * scenario this particular check can't say anything meaningful about.
+     */
+    IF s IN ('_null_count_test', 'tap') THEN
+        RETURN NEXT skip('extension landed in a schema functions.sql always keeps on search_path - not a meaningful check here');
+    ELSE
+        RETURN NEXT is(
+            current_schemas(true) @> array[s]
+            , false
+            , format('schema %I should not be in search path', s)
+        );
+    END IF;
 END
 $body$;
 
 CREATE FUNCTION _null_count_test.test__shutdown__drop_all
 () RETURNS SETOF text LANGUAGE plpgsql AS $body$
+DECLARE
+    v_schema CONSTANT text = current_setting('count_nulls.test_schema');
 BEGIN
     RETURN NEXT lives_ok(
         $$DROP EXTENSION count_nulls$$
     );
 
-    RETURN NEXT lives_ok(
-        format('DROP SCHEMA %I', current_setting('count_nulls.test_schema'))
-    );
+    /*
+     * Only try to drop a schema when TEST_SCHEMA actually created one -
+     * when it's empty, the extension lives wherever it landed on its own
+     * (see test/deps.sql), which this file has no business dropping.
+     */
+    IF v_schema <> '' THEN
+        RETURN NEXT lives_ok(
+            format('DROP SCHEMA %I', v_schema)
+        );
+    ELSE
+        RETURN NEXT skip('TEST_SCHEMA is empty - no dedicated schema to drop');
+    END IF;
 END
 $body$;
 
diff --git a/test/sql/sanity.sql b/test/sql/sanity.sql
index 53d2ad0..a328b35 100644
--- a/test/sql/sanity.sql
+++ b/test/sql/sanity.sql
@@ -3,26 +3,37 @@
 
 BEGIN;
 
--- Unlike the other test files, this one doesn't route through
--- test/deps.sql - it's meant to be a minimal, standalone smoke test. It
--- still has to respect TEST_SCHEMA/TEST_LOAD_SOURCE though: under 'existing'
--- mode the extension is already installed (CREATE EXTENSION would error),
--- and either way the calls below are unqualified, so search_path needs to
--- include wherever count_nulls actually lives.
+/*
+ * Unlike the other test files, this one doesn't route through
+ * test/deps.sql - it's meant to be a minimal, standalone smoke test. It
+ * still has to respect TEST_LOAD_SOURCE/TEST_SCHEMA though: under
+ * 'existing' mode the extension is already installed (CREATE EXTENSION
+ * would error), and either way the calls below are unqualified, so
+ * search_path needs to include wherever count_nulls actually lives. When
+ * TEST_SCHEMA is empty, nothing here needs to touch search_path at all:
+ * the extension lands in 'public' by Postgres's own default, and 'public'
+ * is already on the connection's default search_path.
+ */
 SELECT current_setting('count_nulls.test_load_mode') = 'existing' AS count_nulls_existing_mode
 \gset
+SELECT current_setting('count_nulls.test_schema') <> '' AS count_nulls_has_schema
+\gset
 SELECT current_setting('count_nulls.test_schema') AS schema
 \gset
 
 \if :count_nulls_existing_mode
+\if :count_nulls_has_schema
 SET search_path = :"schema";
+\endif
 \else
+\if :count_nulls_has_schema
 -- IF NOT EXISTS emits a NOTICE for the (very common) case of :"schema"
 -- being 'public', which always already exists.
 SET client_min_messages = WARNING;
 CREATE SCHEMA IF NOT EXISTS :"schema";
 SET search_path = :"schema";
 SET client_min_messages = NOTICE;
+\endif
 CREATE EXTENSION count_nulls;
 \endif
 
diff --git a/test/sql/simple.sql b/test/sql/simple.sql
deleted file mode 100644
index a429fdd..0000000
--- a/test/sql/simple.sql
+++ /dev/null
@@ -1,14 +0,0 @@
-\set ECHO none
-
-\i test/load.sql
-
-\i test/core/functions.sql
-
--- Unlike extension_tests.sql, this file tests count_nulls used unqualified
--- (i.e. installed schema IS on search_path), regardless of which schema
--- TEST_SCHEMA (test/deps.sql's :"schema") actually names.
-SET SEARCH_PATH = _null_count_test, tap, :"schema";
-
---SET client_min_messages = debug;
-
-SELECT * FROM runtests( '_null_count_test'::name );

From 1459f03a78fbfccd0ee48da5f7e5fd682bd87a93 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 23 Jul 2026 18:15:15 -0500
Subject: [PATCH 09/12] Regenerate expected output for empty-TEST_SCHEMA and
 drop simple.out

extension_tests.out: regenerated via make results for the new default
(TEST_SCHEMA empty) - the only change is the schema name throughout (now
'tap', where this suite's own pgTAP setup lands it when nothing targets a
schema, replacing the previous hardcoded 'public' default).

extension_tests_2.out: a third pg_regress alternate-expected-output variant
(existing _1.out already covers TEST_SCHEMA=Quoted), for TEST_SCHEMA=empty
runs that go through bin/test_existing's standalone psql sessions (the
extension-update-test/pg-upgrade-test CI jobs) rather than the in-suite
pg_regress session - those land in 'public' (a bare session's real ambient
default, unaffected by the pgTAP setup that only runs inside the suite),
genuinely different text from the in-suite empty-schema case. Captured from
real runs with zero TAP-level failures in both cases.

test/expected/simple.out, simple_1.out: removed along with
test/sql/simple.sql.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 test/expected/extension_tests.out             | 98 +++++++++----------
 .../{simple.out => extension_tests_2.out}     | 72 ++++++++------
 test/expected/simple_1.out                    | 71 --------------
 3 files changed, 90 insertions(+), 151 deletions(-)
 rename test/expected/{simple.out => extension_tests_2.out} (57%)
 delete mode 100644 test/expected/simple_1.out

diff --git a/test/expected/extension_tests.out b/test/expected/extension_tests.out
index 3d213b5..6860ae6 100644
--- a/test/expected/extension_tests.out
+++ b/test/expected/extension_tests.out
@@ -1,87 +1,81 @@
 \set ECHO none
 # Subtest: _null_count_test.test__check_ncs()
     ok 1
-    ok 2 - schema public should not be in search path
+    ok 2 # SKIP extension landed in a schema functions.sql always keeps on search_path - not a meaningful check here
     1..2
 ok 1 - _null_count_test.test__check_ncs
 # Subtest: _null_count_test.test__definition()
-    ok 1 - ensure null_count({anyarray}) is not in search_path
-    ok 2 - Function public.null_count(anyarray) should return integer
-    ok 3 - Function public.null_count(anyarray) should not be strict
-    ok 4 - Function public.null_count(anyarray) should be IMMUTABLE
-    ok 5 - ensure null_count({json}) is not in search_path
-    ok 6 - Function public.null_count(json) should return integer
-    ok 7 - Function public.null_count(json) should not be strict
-    ok 8 - Function public.null_count(json) should be IMMUTABLE
-    ok 9 - ensure null_count({jsonb}) is not in search_path
-    ok 10 - Function public.null_count(jsonb) should return integer
-    ok 11 - Function public.null_count(jsonb) should not be strict
-    ok 12 - Function public.null_count(jsonb) should be IMMUTABLE
-    ok 13 - ensure not_null_count({anyarray}) is not in search_path
-    ok 14 - Function public.not_null_count(anyarray) should return integer
-    ok 15 - Function public.not_null_count(anyarray) should not be strict
-    ok 16 - Function public.not_null_count(anyarray) should be IMMUTABLE
-    ok 17 - ensure not_null_count({json}) is not in search_path
-    ok 18 - Function public.not_null_count(json) should return integer
-    ok 19 - Function public.not_null_count(json) should not be strict
-    ok 20 - Function public.not_null_count(json) should be IMMUTABLE
-    ok 21 - ensure not_null_count({jsonb}) is not in search_path
-    ok 22 - Function public.not_null_count(jsonb) should return integer
-    ok 23 - Function public.not_null_count(jsonb) should not be strict
-    ok 24 - Function public.not_null_count(jsonb) should be IMMUTABLE
-    ok 25 - Function public.null_count_trigger() should return trigger
-    ok 26 - Function public.null_count_trigger() should not be strict
-    ok 27 - Function public.null_count_trigger() should be IMMUTABLE
-    ok 28 - Function public.not_null_count_trigger() should return trigger
-    ok 29 - Function public.not_null_count_trigger() should not be strict
-    ok 30 - Function public.not_null_count_trigger() should be IMMUTABLE
-    1..30
+    ok 1 - Function tap.null_count(anyarray) should return integer
+    ok 2 - Function tap.null_count(anyarray) should not be strict
+    ok 3 - Function tap.null_count(anyarray) should be IMMUTABLE
+    ok 4 - Function tap.null_count(json) should return integer
+    ok 5 - Function tap.null_count(json) should not be strict
+    ok 6 - Function tap.null_count(json) should be IMMUTABLE
+    ok 7 - Function tap.null_count(jsonb) should return integer
+    ok 8 - Function tap.null_count(jsonb) should not be strict
+    ok 9 - Function tap.null_count(jsonb) should be IMMUTABLE
+    ok 10 - Function tap.not_null_count(anyarray) should return integer
+    ok 11 - Function tap.not_null_count(anyarray) should not be strict
+    ok 12 - Function tap.not_null_count(anyarray) should be IMMUTABLE
+    ok 13 - Function tap.not_null_count(json) should return integer
+    ok 14 - Function tap.not_null_count(json) should not be strict
+    ok 15 - Function tap.not_null_count(json) should be IMMUTABLE
+    ok 16 - Function tap.not_null_count(jsonb) should return integer
+    ok 17 - Function tap.not_null_count(jsonb) should not be strict
+    ok 18 - Function tap.not_null_count(jsonb) should be IMMUTABLE
+    ok 19 - Function tap.null_count_trigger() should return trigger
+    ok 20 - Function tap.null_count_trigger() should not be strict
+    ok 21 - Function tap.null_count_trigger() should be IMMUTABLE
+    ok 22 - Function tap.not_null_count_trigger() should return trigger
+    ok 23 - Function tap.not_null_count_trigger() should not be strict
+    ok 24 - Function tap.not_null_count_trigger() should be IMMUTABLE
+    1..24
 ok 2 - _null_count_test.test__definition
 # Subtest: _null_count_test.test__functionality()
-    ok 1 - Test public.null_count(a, b, c)
-    ok 2 - Test public.null_count(json)
-    ok 3 - Test public.null_count(jsonb)
-    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger( NULL )
-    ok 5 - Test public.not_null_count_trigger( NULL )
+    ok 1 - Test tap.null_count(a, b, c)
+    ok 2 - Test tap.null_count(json)
+    ok 3 - Test tap.null_count(jsonb)
+    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.not_null_count_trigger( NULL )
+    ok 5 - Test tap.not_null_count_trigger( NULL )
     ok 6 - DROP TRIGGER "test trigger"
-    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(  )
-    ok 8 - Test public.not_null_count_trigger(  )
+    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.not_null_count_trigger(  )
+    ok 8 - Test tap.not_null_count_trigger(  )
     ok 9 - DROP TRIGGER "test trigger"
-    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger( NULL )
-    ok 11 - Test public.null_count_trigger( NULL )
+    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.null_count_trigger( NULL )
+    ok 11 - Test tap.null_count_trigger( NULL )
     ok 12 - DROP TRIGGER "test trigger"
-    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(  )
-    ok 14 - Test public.null_count_trigger(  )
+    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.null_count_trigger(  )
+    ok 14 - Test tap.null_count_trigger(  )
     ok 15 - DROP TRIGGER "test trigger"
-    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, 'error_message')
+    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.null_count_trigger(1, 'error_message')
     ok 17 - Test "null_BEFORE_error_message"
     ok 18 - DROP TRIGGER "null_BEFORE_error_message"
-    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, 'error_message')
+    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.null_count_trigger(1, 'error_message')
     ok 20 - Test "null_AFTER_error_message"
     ok 21 - DROP TRIGGER "null_AFTER_error_message"
-    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, 'error_message')
+    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.not_null_count_trigger(1, 'error_message')
     ok 23 - Test "not_null_BEFORE_error_message"
     ok 24 - DROP TRIGGER "not_null_BEFORE_error_message"
-    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, 'error_message')
+    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.not_null_count_trigger(1, 'error_message')
     ok 26 - Test "not_null_AFTER_error_message"
     ok 27 - DROP TRIGGER "not_null_AFTER_error_message"
-    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, NULL)
+    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.null_count_trigger(1, NULL)
     ok 29 - Test "null_BEFORE_"
     ok 30 - DROP TRIGGER "null_BEFORE_"
-    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.null_count_trigger(1, NULL)
+    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.null_count_trigger(1, NULL)
     ok 32 - Test "null_AFTER_"
     ok 33 - DROP TRIGGER "null_AFTER_"
-    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, NULL)
+    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.not_null_count_trigger(1, NULL)
     ok 35 - Test "not_null_BEFORE_"
     ok 36 - DROP TRIGGER "not_null_BEFORE_"
-    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE public.not_null_count_trigger(1, NULL)
+    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE tap.not_null_count_trigger(1, NULL)
     ok 38 - Test "not_null_AFTER_"
     ok 39 - DROP TRIGGER "not_null_AFTER_"
     1..39
 ok 3 - _null_count_test.test__functionality
 # Subtest: _null_count_test.test__shutdown__drop_all()
     ok 1
-    ok 2
+    ok 2 # SKIP TEST_SCHEMA is empty - no dedicated schema to drop
     1..2
 ok 4 - _null_count_test.test__shutdown__drop_all
 1..4
diff --git a/test/expected/simple.out b/test/expected/extension_tests_2.out
similarity index 57%
rename from test/expected/simple.out
rename to test/expected/extension_tests_2.out
index ea8bad2..744cda8 100644
--- a/test/expected/simple.out
+++ b/test/expected/extension_tests_2.out
@@ -1,31 +1,42 @@
 \set ECHO none
+# Subtest: _null_count_test.test__check_ncs()
+    ok 1
+    ok 2 - schema public should not be in search path
+    1..2
+ok 1 - _null_count_test.test__check_ncs
 # Subtest: _null_count_test.test__definition()
-    ok 1 - Function public.null_count(anyarray) should return integer
-    ok 2 - Function public.null_count(anyarray) should not be strict
-    ok 3 - Function public.null_count(anyarray) should be IMMUTABLE
-    ok 4 - Function public.null_count(json) should return integer
-    ok 5 - Function public.null_count(json) should not be strict
-    ok 6 - Function public.null_count(json) should be IMMUTABLE
-    ok 7 - Function public.null_count(jsonb) should return integer
-    ok 8 - Function public.null_count(jsonb) should not be strict
-    ok 9 - Function public.null_count(jsonb) should be IMMUTABLE
-    ok 10 - Function public.not_null_count(anyarray) should return integer
-    ok 11 - Function public.not_null_count(anyarray) should not be strict
-    ok 12 - Function public.not_null_count(anyarray) should be IMMUTABLE
-    ok 13 - Function public.not_null_count(json) should return integer
-    ok 14 - Function public.not_null_count(json) should not be strict
-    ok 15 - Function public.not_null_count(json) should be IMMUTABLE
-    ok 16 - Function public.not_null_count(jsonb) should return integer
-    ok 17 - Function public.not_null_count(jsonb) should not be strict
-    ok 18 - Function public.not_null_count(jsonb) should be IMMUTABLE
-    ok 19 - Function public.null_count_trigger() should return trigger
-    ok 20 - Function public.null_count_trigger() should not be strict
-    ok 21 - Function public.null_count_trigger() should be IMMUTABLE
-    ok 22 - Function public.not_null_count_trigger() should return trigger
-    ok 23 - Function public.not_null_count_trigger() should not be strict
-    ok 24 - Function public.not_null_count_trigger() should be IMMUTABLE
-    1..24
-ok 1 - _null_count_test.test__definition
+    ok 1 - ensure null_count({anyarray}) is not in search_path
+    ok 2 - Function public.null_count(anyarray) should return integer
+    ok 3 - Function public.null_count(anyarray) should not be strict
+    ok 4 - Function public.null_count(anyarray) should be IMMUTABLE
+    ok 5 - ensure null_count({json}) is not in search_path
+    ok 6 - Function public.null_count(json) should return integer
+    ok 7 - Function public.null_count(json) should not be strict
+    ok 8 - Function public.null_count(json) should be IMMUTABLE
+    ok 9 - ensure null_count({jsonb}) is not in search_path
+    ok 10 - Function public.null_count(jsonb) should return integer
+    ok 11 - Function public.null_count(jsonb) should not be strict
+    ok 12 - Function public.null_count(jsonb) should be IMMUTABLE
+    ok 13 - ensure not_null_count({anyarray}) is not in search_path
+    ok 14 - Function public.not_null_count(anyarray) should return integer
+    ok 15 - Function public.not_null_count(anyarray) should not be strict
+    ok 16 - Function public.not_null_count(anyarray) should be IMMUTABLE
+    ok 17 - ensure not_null_count({json}) is not in search_path
+    ok 18 - Function public.not_null_count(json) should return integer
+    ok 19 - Function public.not_null_count(json) should not be strict
+    ok 20 - Function public.not_null_count(json) should be IMMUTABLE
+    ok 21 - ensure not_null_count({jsonb}) is not in search_path
+    ok 22 - Function public.not_null_count(jsonb) should return integer
+    ok 23 - Function public.not_null_count(jsonb) should not be strict
+    ok 24 - Function public.not_null_count(jsonb) should be IMMUTABLE
+    ok 25 - Function public.null_count_trigger() should return trigger
+    ok 26 - Function public.null_count_trigger() should not be strict
+    ok 27 - Function public.null_count_trigger() should be IMMUTABLE
+    ok 28 - Function public.not_null_count_trigger() should return trigger
+    ok 29 - Function public.not_null_count_trigger() should not be strict
+    ok 30 - Function public.not_null_count_trigger() should be IMMUTABLE
+    1..30
+ok 2 - _null_count_test.test__definition
 # Subtest: _null_count_test.test__functionality()
     ok 1 - Test public.null_count(a, b, c)
     ok 2 - Test public.null_count(json)
@@ -67,5 +78,10 @@ ok 1 - _null_count_test.test__definition
     ok 38 - Test "not_null_AFTER_"
     ok 39 - DROP TRIGGER "not_null_AFTER_"
     1..39
-ok 2 - _null_count_test.test__functionality
-1..2
+ok 3 - _null_count_test.test__functionality
+# Subtest: _null_count_test.test__shutdown__drop_all()
+    ok 1
+    ok 2 # SKIP TEST_SCHEMA is empty - no dedicated schema to drop
+    1..2
+ok 4 - _null_count_test.test__shutdown__drop_all
+1..4
diff --git a/test/expected/simple_1.out b/test/expected/simple_1.out
deleted file mode 100644
index 39b3388..0000000
--- a/test/expected/simple_1.out
+++ /dev/null
@@ -1,71 +0,0 @@
-\set ECHO none
-# Subtest: _null_count_test.test__definition()
-    ok 1 - Function "Quoted".null_count(anyarray) should return integer
-    ok 2 - Function "Quoted".null_count(anyarray) should not be strict
-    ok 3 - Function "Quoted".null_count(anyarray) should be IMMUTABLE
-    ok 4 - Function "Quoted".null_count(json) should return integer
-    ok 5 - Function "Quoted".null_count(json) should not be strict
-    ok 6 - Function "Quoted".null_count(json) should be IMMUTABLE
-    ok 7 - Function "Quoted".null_count(jsonb) should return integer
-    ok 8 - Function "Quoted".null_count(jsonb) should not be strict
-    ok 9 - Function "Quoted".null_count(jsonb) should be IMMUTABLE
-    ok 10 - Function "Quoted".not_null_count(anyarray) should return integer
-    ok 11 - Function "Quoted".not_null_count(anyarray) should not be strict
-    ok 12 - Function "Quoted".not_null_count(anyarray) should be IMMUTABLE
-    ok 13 - Function "Quoted".not_null_count(json) should return integer
-    ok 14 - Function "Quoted".not_null_count(json) should not be strict
-    ok 15 - Function "Quoted".not_null_count(json) should be IMMUTABLE
-    ok 16 - Function "Quoted".not_null_count(jsonb) should return integer
-    ok 17 - Function "Quoted".not_null_count(jsonb) should not be strict
-    ok 18 - Function "Quoted".not_null_count(jsonb) should be IMMUTABLE
-    ok 19 - Function "Quoted".null_count_trigger() should return trigger
-    ok 20 - Function "Quoted".null_count_trigger() should not be strict
-    ok 21 - Function "Quoted".null_count_trigger() should be IMMUTABLE
-    ok 22 - Function "Quoted".not_null_count_trigger() should return trigger
-    ok 23 - Function "Quoted".not_null_count_trigger() should not be strict
-    ok 24 - Function "Quoted".not_null_count_trigger() should be IMMUTABLE
-    1..24
-ok 1 - _null_count_test.test__definition
-# Subtest: _null_count_test.test__functionality()
-    ok 1 - Test "Quoted".null_count(a, b, c)
-    ok 2 - Test "Quoted".null_count(json)
-    ok 3 - Test "Quoted".null_count(jsonb)
-    ok 4 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger( NULL )
-    ok 5 - Test "Quoted".not_null_count_trigger( NULL )
-    ok 6 - DROP TRIGGER "test trigger"
-    ok 7 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(  )
-    ok 8 - Test "Quoted".not_null_count_trigger(  )
-    ok 9 - DROP TRIGGER "test trigger"
-    ok 10 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger( NULL )
-    ok 11 - Test "Quoted".null_count_trigger( NULL )
-    ok 12 - DROP TRIGGER "test trigger"
-    ok 13 - CREATE TRIGGER "test trigger" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(  )
-    ok 14 - Test "Quoted".null_count_trigger(  )
-    ok 15 - DROP TRIGGER "test trigger"
-    ok 16 - CREATE TRIGGER "null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, 'error_message')
-    ok 17 - Test "null_BEFORE_error_message"
-    ok 18 - DROP TRIGGER "null_BEFORE_error_message"
-    ok 19 - CREATE TRIGGER "null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, 'error_message')
-    ok 20 - Test "null_AFTER_error_message"
-    ok 21 - DROP TRIGGER "null_AFTER_error_message"
-    ok 22 - CREATE TRIGGER "not_null_BEFORE_error_message" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, 'error_message')
-    ok 23 - Test "not_null_BEFORE_error_message"
-    ok 24 - DROP TRIGGER "not_null_BEFORE_error_message"
-    ok 25 - CREATE TRIGGER "not_null_AFTER_error_message" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, 'error_message')
-    ok 26 - Test "not_null_AFTER_error_message"
-    ok 27 - DROP TRIGGER "not_null_AFTER_error_message"
-    ok 28 - CREATE TRIGGER "null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, NULL)
-    ok 29 - Test "null_BEFORE_"
-    ok 30 - DROP TRIGGER "null_BEFORE_"
-    ok 31 - CREATE TRIGGER "null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".null_count_trigger(1, NULL)
-    ok 32 - Test "null_AFTER_"
-    ok 33 - DROP TRIGGER "null_AFTER_"
-    ok 34 - CREATE TRIGGER "not_null_BEFORE_" BEFORE INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, NULL)
-    ok 35 - Test "not_null_BEFORE_"
-    ok 36 - DROP TRIGGER "not_null_BEFORE_"
-    ok 37 - CREATE TRIGGER "not_null_AFTER_" AFTER INSERT ON test_data FOR EACH ROW EXECUTE PROCEDURE "Quoted".not_null_count_trigger(1, NULL)
-    ok 38 - Test "not_null_AFTER_"
-    ok 39 - DROP TRIGGER "not_null_AFTER_"
-    1..39
-ok 2 - _null_count_test.test__functionality
-1..2

From 170928afd4d15149f755ef368234acb533122b39 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 23 Jul 2026 18:15:36 -0500
Subject: [PATCH 10/12] CI: schema matrix without/with, NEWEST=18, drop
 cat_tools-only comment context

test/extension-update-test/pg-upgrade-test matrices: schema axis is now
["", Quoted] (without/with an explicit schema) instead of [public, Quoted],
matching TEST_SCHEMA's new empty-mode support. pg-upgrade-test's new_pg
targets bumped 17->18 to match the derived PG list's new ceiling (confirmed
working: a real cat_tools CI run on PostgreSQL 18 is green).

NEWEST bumped 17->18 in the single-source PG-major derivation.

Removed comments that leaned on cat_tools context to justify a design
choice in this repo's own CI (e.g. "unlike cat_tools's pg-upgrade-test,
which has to dig itself out of...") - every comment here should stand on
its own reasoning; a reader of this repo has no reason to know cat_tools's
history. Reworded the "worth doing anyway" phrasing into something that
actually reads coherently. Also hardened the docs-only-changes step: it now
writes docs_only=false as its literal first action, so any early exit or
error further down leaves the fail-safe default in place instead of relying
on every branch remembering to set it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 112 +++++++++++++++++++++------------------
 1 file changed, 59 insertions(+), 53 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f04ee8e..c3b773b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,10 +8,11 @@ jobs:
   # protection.
   #
   # Also derives, from a SINGLE set of constants, the supported-PostgreSQL-
-  # major list the test / extension-update jobs consume (see the "Derive ..."
-  # step) - per Postgres-Extensions/cat_tools PR #48, taken near-verbatim:
-  # count_nulls has no legacy-floor complication (unlike cat_tools's PG10-only
-  # pre-0.2.2 scripts), so this needs only ONE list, not cat_tools's three.
+  # major list the test / extension-update-test jobs consume (see the
+  # "Derive ..." step): every job that cares which majors are supported reads
+  # the SAME list, so they can't silently drift onto different sets, and
+  # adding a new major is a one-line change here instead of an edit in
+  # several jobs.
   changes:
     name: 🔍 Detect docs-only changes & derive PG matrix
     runs-on: ubuntu-latest
@@ -28,6 +29,14 @@ jobs:
       - name: Compute per-push changed files
         id: diff
         run: |
+          # Fail safe to running the full matrix: default docs_only to false
+          # immediately, before anything below has a chance to compute or
+          # fail. Writing the same GITHUB_OUTPUT key twice is fine (the last
+          # write wins), so the only way this step ends with docs_only=true
+          # is by genuinely proving it further down - never by skipping past
+          # an edge case with a default.
+          echo "docs_only=false" >> "$GITHUB_OUTPUT"
+
           if [ "${{ github.event_name }}" = "pull_request" ] && \
              [ "${{ github.event.action }}" = "synchronize" ] && \
              [ -n "${{ github.event.before }}" ]; then
@@ -49,12 +58,11 @@ jobs:
           echo "base=$BASE"
           echo "head=$HEAD"
 
-          # Fail-safe: a missing HEAD, or an all-zeros BASE (e.g. a new
-          # branch's first push, where GitHub reports no prior commit),
-          # means we can't compute a real diff. Run the full matrix rather
-          # than risk skipping tests.
+          # A missing HEAD, or an all-zeros BASE (e.g. a new branch's first
+          # push, where GitHub reports no prior commit), means we can't
+          # compute a real diff. docs_only is already false from above;
+          # just stop here rather than risk skipping tests.
           if [ -z "$HEAD" ] || [ -z "$BASE" ] || [[ "$BASE" =~ ^0+$ ]]; then
-            echo "docs_only=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
 
@@ -79,20 +87,19 @@ jobs:
       - name: Derive the supported-PostgreSQL-major list
         id: pg
         run: |
-          # Spending a dozen-odd lines to replace what looks like a handful of
-          # version references is worth doing anyway: the point is
-          # CONSISTENCY - both the fresh-install `test` matrix and the
-          # `extension-update-test` matrix derive their PostgreSQL set from
-          # this ONE source, so they cannot silently drift onto different
-          # lists. Adding a new major is a one-line NEWEST bump here, not an
-          # edit in N places.
+          # A dozen-odd lines to replace what looks like a handful of version
+          # references, but it buys CONSISTENCY: both the fresh-install
+          # `test` matrix and the `extension-update-test` matrix derive their
+          # PostgreSQL set from this ONE source, so they cannot silently
+          # drift onto different lists. Adding a new major is a one-line
+          # NEWEST bump here, not an edit in N places.
           #
-          # count_nulls has only ONE floor (unlike cat_tools's separate
-          # current-version floor and legacy pre-0.2.2 floor): 0.9.6 is a
-          # pure-SQL-function install script with no catalog-version
-          # sensitivity, so it installs on every PostgreSQL major count_nulls
-          # supports - there is no PG10-only legacy leg to carve out.
-          NEWEST=17
+          # Only one floor is needed here: 0.9.6 (the oldest version
+          # count_nulls still ships a full install script for) is pure SQL
+          # over anyarray/json/jsonb with no catalog-version sensitivity, so
+          # it installs on every PostgreSQL major count_nulls supports -
+          # there's no separate legacy-only floor to carve out.
+          NEWEST=18
           FLOOR=10
 
           supported=$(seq "$NEWEST" -1 "$FLOOR")
@@ -106,11 +113,14 @@ jobs:
 
   # Baseline: fresh CREATE EXTENSION, across the PG matrix AND a schema
   # matrix (TEST_SCHEMA, picked up from the environment by test/deps.sql via
-  # the count_nulls.test_schema GUC - see the Makefile). 'public' is the
-  # common case; 'Quoted' requires SQL identifier quoting (mixed case -
-  # unquoted would fold to lowercase and silently test 'public' again),
+  # the count_nulls.test_schema GUC - see the Makefile). Empty ('') runs
+  # WITHOUT specifying a schema at all - CREATE EXTENSION with no targeting,
+  # landing wherever the session's own default search_path resolves.
+  # 'Quoted' runs WITH one explicitly specified, using a name that requires
+  # SQL identifier quoting (mixed case - unquoted would fold to lowercase),
   # exercising the suite's %I schema-qualification rather than just its
-  # literal test data.
+  # literal test data. Both legs matter; neither is redundant with the
+  # other (see the Makefile's TEST_SCHEMA comment).
   test:
     needs: [changes]
     if: needs.changes.outputs.docs_only != 'true'
@@ -118,8 +128,8 @@ jobs:
       matrix:
         # From the single source in the changes job.
         pg: ${{ fromJSON(needs.changes.outputs.supported_pg) }}
-        schema: [public, Quoted]
-    name: 🐘 PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema }})
+        schema: ["", Quoted]
+    name: 🐘 PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema == '' && 'none' || matrix.schema }})
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
     env:
@@ -146,8 +156,8 @@ jobs:
       matrix:
         # From the single source in the changes job.
         pg: ${{ fromJSON(needs.changes.outputs.supported_pg) }}
-        schema: [public, Quoted]
-    name: ⬆️ Extension update test on PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema }})
+        schema: ["", Quoted]
+    name: ⬆️ Extension update test on PostgreSQL ${{ matrix.pg }} (schema ${{ matrix.schema == '' && 'none' || matrix.schema }})
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
     steps:
@@ -170,22 +180,18 @@ jobs:
   # update. Installs 0.9.6 on an old cluster, plants a dependency guard,
   # binary-pg_upgrades to a newer cluster, updates the extension to current,
   # then runs the suite against the REAL migrated objects in existing mode.
-  # No bridge-update step (unlike cat_tools's pg-upgrade-test, which has to
-  # dig itself out of pg_upgrade-unsafe versions it shipped before this
-  # testing pattern existed): count_nulls has always been pure SQL functions
-  # with no SELECT-*-over-catalog views, so it has no known
-  # pg_upgrade-unsafe old version to bridge past
-  # (advanced-extension-testing.md #7/#9).
+  # No bridge-update step first: count_nulls has always been pure SQL
+  # functions with no SELECT-*-over-catalog views, so it has no known
+  # pg_upgrade-unsafe old version to bridge past.
   #
-  # Deliberately NOT adding cat_tools's companion `pg-upgrade-stepwise` job
-  # (one cluster climbing every major in sequence, vs. the single big jumps
-  # here): that job exists to catch a regression specific to one particular
-  # major-to-major boundary, which matters for cat_tools's views/functions
-  # that touch catalog internals (advanced-extension-testing.md #7) but not
-  # for count_nulls - pure SQL functions over anyarray/json/jsonb, nothing
-  # version-sensitive to break at a specific boundary. The two big-jump legs
-  # below (10->17, 12->17) already cover the axis that matters here. Revisit
-  # if count_nulls ever grows something catalog-touching.
+  # Deliberately not doing a stepwise every-major-in-sequence climb (one
+  # cluster walking 10->11->12->...->newest, vs. the single big jumps here):
+  # that would catch a regression specific to one particular major-to-major
+  # boundary, which would matter if count_nulls had views/functions touching
+  # catalog internals, but it doesn't - pure SQL functions over anyarray/
+  # json/jsonb, nothing version-sensitive to break at a specific boundary.
+  # The two big-jump legs below already cover the axis that matters here.
+  # Revisit if count_nulls ever grows something catalog-touching.
   pg-upgrade-test:
     needs: [changes]
     if: needs.changes.outputs.docs_only != 'true'
@@ -193,18 +199,18 @@ jobs:
       matrix:
         include:
           - old_pg: "10"
-            new_pg: "17"
-            schema: public
+            new_pg: "18"
+            schema: ""
           - old_pg: "10"
-            new_pg: "17"
+            new_pg: "18"
             schema: Quoted
           - old_pg: "12"
-            new_pg: "17"
-            schema: public
+            new_pg: "18"
+            schema: ""
           - old_pg: "12"
-            new_pg: "17"
+            new_pg: "18"
             schema: Quoted
-    name: 🔄 Binary pg_upgrade ${{ matrix.old_pg }} → ${{ matrix.new_pg }} (schema ${{ matrix.schema }})
+    name: 🔄 Binary pg_upgrade ${{ matrix.old_pg }} → ${{ matrix.new_pg }} (schema ${{ matrix.schema == '' && 'none' || matrix.schema }})
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
     env:
@@ -276,7 +282,7 @@ jobs:
 
   # A single stable check name for use as a required status check in branch
   # protection rules. Matrix jobs produce check names like
-  # "🐘 PostgreSQL 14 (schema public)" which would all need to be listed
+  # "🐘 PostgreSQL 14 (schema none)" which would all need to be listed
   # individually and updated whenever the matrix changes. This job passes if
   # all others passed or were skipped (e.g. the heavy jobs gated off by the
   # `changes` job on a docs-only push), and fails if any failed or were

From 7d2e6ebfa6b1c0158bd2373d53a5140d1f25ebb8 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 23 Jul 2026 18:20:31 -0500
Subject: [PATCH 11/12] Rename bin/test_existing_sql/ to bin/test_existing.sql/

Same reasoning as the earlier move out of test/pg_upgrade/ - these files
are helpers for bin/test_existing specifically, so the directory name
reads as "test_existing's sql" alongside the script itself.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 bin/test_existing                                         | 8 ++++----
 .../assert_guard.sql                                      | 0
 .../drop_guard.sql                                        | 0
 .../plant_guard.sql                                       | 0
 4 files changed, 4 insertions(+), 4 deletions(-)
 rename bin/{test_existing_sql => test_existing.sql}/assert_guard.sql (100%)
 rename bin/{test_existing_sql => test_existing.sql}/drop_guard.sql (100%)
 rename bin/{test_existing_sql => test_existing.sql}/plant_guard.sql (100%)

diff --git a/bin/test_existing b/bin/test_existing
index e7cbad2..8955336 100755
--- a/bin/test_existing
+++ b/bin/test_existing
@@ -44,7 +44,7 @@
 # the extension, the suite would test a FRESH install and hide a regression.
 # We plant an object that HARD-references a count_nulls member so a
 # non-CASCADE DROP EXTENSION fails, and actively PROVE that (see
-# bin/test_existing_sql/assert_guard.sql): if the drop unexpectedly succeeds,
+# bin/test_existing.sql/assert_guard.sql): if the drop unexpectedly succeeds,
 # this script fails CI rather than silently passing.
 set -euo pipefail
 
@@ -93,7 +93,7 @@ guard_present() {
 # CREATE EXTENSION (and before any update/upgrade) so it persists through them.
 plant_guard() {
   local db=$1 schema=$2
-  psql -d "$db" -v ON_ERROR_STOP=1 -v schema="$schema" -f bin/test_existing_sql/plant_guard.sql
+  psql -d "$db" -v ON_ERROR_STOP=1 -v schema="$schema" -f bin/test_existing.sql/plant_guard.sql
   assert_drop_blocked "$db"
 }
 
@@ -102,13 +102,13 @@ plant_guard() {
 # unexpectedly succeeds, or if the extension/guard are missing afterward.
 assert_drop_blocked() {
   local db=$1
-  psql -d "$db" -v ON_ERROR_STOP=1 -f bin/test_existing_sql/assert_guard.sql
+  psql -d "$db" -v ON_ERROR_STOP=1 -f bin/test_existing.sql/assert_guard.sql
   echo "OK: non-CASCADE DROP EXTENSION is blocked in '$db' (dependency guard effective)"
 }
 
 drop_guard() {
   local db=$1
-  psql -d "$db" -v ON_ERROR_STOP=1 -f bin/test_existing_sql/drop_guard.sql
+  psql -d "$db" -v ON_ERROR_STOP=1 -f bin/test_existing.sql/drop_guard.sql
 }
 
 assert_version() {
diff --git a/bin/test_existing_sql/assert_guard.sql b/bin/test_existing.sql/assert_guard.sql
similarity index 100%
rename from bin/test_existing_sql/assert_guard.sql
rename to bin/test_existing.sql/assert_guard.sql
diff --git a/bin/test_existing_sql/drop_guard.sql b/bin/test_existing.sql/drop_guard.sql
similarity index 100%
rename from bin/test_existing_sql/drop_guard.sql
rename to bin/test_existing.sql/drop_guard.sql
diff --git a/bin/test_existing_sql/plant_guard.sql b/bin/test_existing.sql/plant_guard.sql
similarity index 100%
rename from bin/test_existing_sql/plant_guard.sql
rename to bin/test_existing.sql/plant_guard.sql

From 3b9eabf17d62591282f11fce64535b3cb7891674 Mon Sep 17 00:00:00 2001
From: jnasbyupgrade <jnasby@upgrade.com>
Date: Thu, 23 Jul 2026 18:55:29 -0500
Subject: [PATCH 12/12] Simplify schema-qualification with a prefix var;
 document the test suite

bin/test_existing.sql/plant_guard.sql: replaced the \if/\else branch with a
single schema_prefix variable (empty, or the quoted schema name plus a
literal '.'), computed once via quote_ident() and spliced in as plain text -
one CREATE VIEW statement instead of two branches of one.

test/sql/extension_tests.sql: test__check_ncs and test__shutdown__drop_all
now take the schema as a function parameter (schema_hint name DEFAULT
NULLIF(:'schema', '')::name) instead of calling current_setting() inside the
plpgsql body. psql doesn't interpolate variables inside dollar-quoted
bodies, which is why the previous version needed a runtime GUC read at all -
a parameter default is plain top-level SQL, so the psql substitution just
works there directly, and runtests() calling every test__* function with no
arguments always gets the default.

Added a top-of-file "Test strategy" comment to .github/workflows/ci.yml
summarizing what each job covers before the per-job comments get into
specifics, and test/README.md documenting the two independent mode switches
(TEST_LOAD_SOURCE, TEST_SCHEMA) and - concretely, with a scenario table -
exactly what drives the need for multiple expected/extension_tests*.out
variants, not just that they exist.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml              | 37 +++++++++++
 bin/test_existing.sql/plant_guard.sql | 18 +++--
 test/README.md                        | 94 +++++++++++++++++++++++++++
 test/sql/extension_tests.sql          | 47 +++++++-------
 4 files changed, 167 insertions(+), 29 deletions(-)
 create mode 100644 test/README.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c3b773b..2e175f3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,3 +1,40 @@
+# ===========================================================================
+# Test strategy
+#
+# count_nulls can be arrived at several ways, each of which can break
+# differently, so each is exercised by its own job below:
+#
+#   test                   -- FRESH install: CREATE EXTENSION at the current
+#                              version, across every supported PostgreSQL
+#                              major x schema leg (empty/none and Quoted -
+#                              see TEST_SCHEMA in the Makefile).
+#   extension-update-test   -- IN-PLACE update: CREATE EXTENSION at 0.9.6
+#                              (the oldest version we still ship a full
+#                              install script for) then ALTER EXTENSION
+#                              UPDATE (same PostgreSQL, no pg_upgrade), same
+#                              PG x schema matrix as test.
+#   pg-upgrade-test         -- BINARY pg_upgrade: install 0.9.6 on an OLD
+#                              PostgreSQL major, binary-upgrade the cluster
+#                              to a NEWER major, then update the extension to
+#                              current - proves objects created on an old
+#                              server still work when read on a new one. A
+#                              smaller old_pg/new_pg x schema matrix (not the
+#                              full PG matrix - this job is by far the most
+#                              expensive, installing two full PostgreSQL
+#                              majors and running the real pg_upgrade binary
+#                              per leg).
+#
+# All three matrices cross PostgreSQL major with the TEST_SCHEMA axis:
+# without a schema specified at all (empty - CREATE EXTENSION lands wherever
+# the session's own default search_path resolves) and with one explicitly
+# targeted, using a name that requires SQL identifier quoting. Neither leg is
+# redundant with the other - see the Makefile's TEST_SCHEMA comment.
+#
+# `changes` is a cheap gate that lets all three heavy jobs above skip
+# themselves on doc-only pushes, and also derives the shared PostgreSQL-major
+# list those jobs consume from a single set of constants. `all-checks-passed`
+# is the single stable required-status-check name.
+# ===========================================================================
 name: CI
 on: [push, pull_request]
 jobs:
diff --git a/bin/test_existing.sql/plant_guard.sql b/bin/test_existing.sql/plant_guard.sql
index 3e34269..5b3dd92 100644
--- a/bin/test_existing.sql/plant_guard.sql
+++ b/bin/test_existing.sql/plant_guard.sql
@@ -13,14 +13,18 @@
  * i.e. the extension was installed without targeting a schema).
  */
 \set ON_ERROR_STOP on
-SELECT :'schema' <> '' AS count_nulls_has_schema
+
+/*
+ * schema_prefix: either empty, or the quoted schema name followed by a
+ * literal '.' - so the view definition below is a single statement with a
+ * plain (unquoted) substitution, rather than branching the whole CREATE
+ * VIEW on whether a schema was given. quote_ident(), not :"schema" -
+ * :schema_prefix is pasted as-is (unquoted substitution), so it must
+ * already be valid, properly-quoted SQL text by the time it lands there.
+ */
+SELECT CASE WHEN :'schema' <> '' THEN quote_ident(:'schema') || '.' ELSE '' END AS schema_prefix
 \gset
 
 CREATE SCHEMA IF NOT EXISTS count_nulls_drop_guard;
-\if :count_nulls_has_schema
-CREATE OR REPLACE VIEW count_nulls_drop_guard.guard AS
-  SELECT :"schema".null_count(NULL::int, NULL::int) AS guarded_member;
-\else
 CREATE OR REPLACE VIEW count_nulls_drop_guard.guard AS
-  SELECT null_count(NULL::int, NULL::int) AS guarded_member;
-\endif
+  SELECT :schema_prefix null_count(NULL::int, NULL::int) AS guarded_member;
diff --git a/test/README.md b/test/README.md
new file mode 100644
index 0000000..e1cf61b
--- /dev/null
+++ b/test/README.md
@@ -0,0 +1,94 @@
+# count_nulls test suite
+
+## Layout
+
+- `deps.sql` — loaded by every test file (via `load.sql` ->
+  `pgxntool/setup.sql` -> `deps.sql`). Installs the extension according to
+  two independent GUC-driven switches (below), or asserts it's already
+  installed.
+- `core/functions.sql` — a shared helper, `\i`'d by `sql/extension_tests.sql`.
+  Defines `ncs()` (discovers, live, which schema the extension is actually
+  installed in - never trusts a hardcoded/passed-in value) plus a battery of
+  `test__*` functions (pgTAP's `runtests()` naming convention) covering
+  function definitions, immutability/strictness, and behavior across
+  `anyarray`/`json`/`jsonb` and both trigger functions.
+- `sql/extension_tests.sql` — `\i`'s `core/functions.sql`, adds two more
+  `test__*` functions of its own (`test__check_ncs`, asserting the extension
+  landed where expected; `test__shutdown__drop_all`, asserting it can be
+  cleanly dropped), then runs everything via `runtests()`.
+- `sql/sanity.sql` — deliberately does NOT go through `deps.sql`/
+  `core/functions.sql`. A minimal, independent smoke test: `CREATE EXTENSION`
+  (or assert-only, in `existing` mode) plus two direct `null_count()` calls,
+  left in an open transaction. Exists specifically so a failure here is
+  trivially localized (nothing shared to go wrong) - if this fails, the
+  extension itself is broken, not the shared test harness.
+- `build/upgrade.sql` — pgxntool's `test-build` feature: a fast, cheap smoke
+  check (install 0.9.6, `ALTER EXTENSION UPDATE`, rolled back) that runs
+  automatically before the main suite on every `make test`. Catches a broken
+  update script immediately, before the heavier CI jobs even start.
+- `expected/*.out` — pg_regress's expected output per test file. See
+  "Why multiple expected-output files per test" below before touching these.
+
+## The two independent mode switches
+
+Both are make vars, propagated the same way: `make var` -> `PGOPTIONS -c
+<guc>=<value>` -> `current_setting()` in `deps.sql` (`pg_regress` doesn't
+forward make vars, but the `psql` it spawns inherits the environment).
+
+**`TEST_LOAD_SOURCE`** (`count_nulls.test_load_mode`) — *how* the extension
+got there:
+- `fresh` (default): `CREATE EXTENSION count_nulls` at current.
+- `update`: installs `0.9.6`, then `ALTER EXTENSION UPDATE`. `make
+  test-update` wraps this.
+- `existing`: extension already installed (a real `pg_upgrade`, or an
+  out-of-band update via `bin/test_existing`) - asserts present/current,
+  touches nothing.
+
+**`TEST_SCHEMA`** (`count_nulls.test_schema`) — *where* it lands:
+- empty (default): no `CREATE SCHEMA`/`SET search_path` at all - lands
+  wherever the session's own ambient search_path resolves.
+- non-empty: explicitly targets that schema. `TEST_SCHEMA=Quoted` locally
+  exercises a name requiring SQL identifier quoting.
+
+These are independent axes; the CI matrix (`.github/workflows/ci.yml`, see
+its top-of-file summary comment) crosses both with the PostgreSQL version.
+
+## Why multiple expected-output files per test
+
+`extension_tests.sql`'s assertions build SQL text through `%I`-qualified
+`format()` calls using `ncs()`'s result (`core/functions.sql`) - e.g. a
+`CREATE TRIGGER ... EXECUTE PROCEDURE tap.null_count_trigger(...)` line's
+exact text depends on which schema `ncs()` found. `pg_regress` requires an
+EXACT text match against `expected/<test>.out`, so a run that lands the
+extension somewhere else produces a *correct but textually different*
+result - not a failure to paper over, a second valid baseline to capture.
+`pg_regress` natively supports this: it tries `expected/<test>.out`, then
+`expected/<test>_1.out`, `_2.out`, ... in turn, and passes if ANY one
+matches (see `PGXNTOOL_ENABLE_TEST_BUILD`/pg_regress docs for the general
+mechanism - this isn't pgxntool-specific).
+
+Concretely, three real scenarios currently produce different (each
+individually correct) text for `extension_tests`, so there are three files:
+
+| File | Scenario | Where the extension lands, and why |
+|---|---|---|
+| `extension_tests.out` (default) | `TEST_SCHEMA` empty, run in-suite (`make test`) | `tap` - this suite's own pgTAP setup (`pgxntool/test/pgxntool/tap_setup.sql`) already puts its own schema first on `search_path` *before* `deps.sql` runs, so an untargeted `CREATE EXTENSION` lands there. |
+| `extension_tests_1.out` | `TEST_SCHEMA=Quoted` (any entry point) | `Quoted` - explicitly targeted, so it's wherever it was told to go, regardless of entry point. |
+| `extension_tests_2.out` | `TEST_SCHEMA` empty, run via `bin/test_existing` (the `extension-update-test`/`pg-upgrade-test` CI jobs) | `public` - `bin/test_existing` connects with a bare, standalone `psql` session that never runs `tap_setup.sql`, so an untargeted `CREATE EXTENSION` lands in Postgres's own real default instead. |
+
+If you add a new scenario that changes this text again (a new TEST_SCHEMA
+value, a new entry point), capture its actual `test/results/<test>.out` (a
+real run, zero raw `^not ok` lines) as the next `_N.out`, don't hand-author
+one. `sanity.out` doesn't vary by scenario (its calls are all unqualified,
+no schema name ever appears in its output), so it has no alternates.
+
+## Regenerating expected output
+
+Never hand-edit files under `expected/`. Regenerate via `make results`
+(guarded by `make verify-results`, which refuses to copy while
+`regression.diffs` shows real failures - use `PGXNTOOL_ENABLE_VERIFY_RESULTS=no`
+to bypass that guard for a run you've already reviewed and know is a
+legitimate, intentional change, not a way to skip reviewing the diff).
+`make results` only ever writes the unsuffixed default; alternates
+(`_1.out`, `_2.out`, ...) have to be copied by hand from a real
+`test/results/<test>.out` for that scenario.
diff --git a/test/sql/extension_tests.sql b/test/sql/extension_tests.sql
index 2774a04..fab9342 100644
--- a/test/sql/extension_tests.sql
+++ b/test/sql/extension_tests.sql
@@ -17,27 +17,30 @@
  * asserting something that wouldn't hold.
  */
 
+/*
+ * schema_hint DEFAULT NULLIF(:'schema', '')::name, not current_setting()
+ * inside the function body: psql does not interpolate variables inside
+ * dollar-quoted bodies, but a parameter DEFAULT is plain top-level SQL, so
+ * :'schema' (test/deps.sql's psql variable, still set from this session's
+ * \gset) substitutes there normally. NULLIF turns the empty-TEST_SCHEMA
+ * case into NULL, and runtests() calls every test__* function with no
+ * arguments, so it always gets this default.
+ */
 CREATE FUNCTION _null_count_test.test__check_ncs
-() RETURNS SETOF text LANGUAGE plpgsql AS $body$
+(schema_hint name DEFAULT NULLIF(:'schema', '')::name)
+RETURNS SETOF text LANGUAGE plpgsql AS $body$
 DECLARE
     /*
-     * current_setting(), not a psql :"schema" substitution: psql does not
-     * interpolate variables inside dollar-quoted function bodies.
-     *
      * When TEST_SCHEMA is non-empty we know exactly where the extension
      * should be, so compare ncs() against that known value - a real
-     * assertion. When it's empty, there's no fixed expectation (it lands
-     * wherever the ambient search_path resolves at CREATE EXTENSION time,
-     * which depends on what ran before deps.sql - not something this test
-     * should hardcode), so fall back to ncs() itself: a no-op comparison
-     * that still exercises the call, without asserting a location this
-     * file has no business assuming.
+     * assertion. When it's empty (schema_hint is NULL), there's no fixed
+     * expectation (it lands wherever the ambient search_path resolves at
+     * CREATE EXTENSION time, which depends on what ran before deps.sql -
+     * not something this test should hardcode), so fall back to ncs()
+     * itself: a no-op comparison that still exercises the call, without
+     * asserting a location this file has no business assuming.
      */
-    s CONSTANT name = CASE
-        WHEN current_setting('count_nulls.test_schema') <> ''
-            THEN current_setting('count_nulls.test_schema')::name
-        ELSE ncs()
-    END;
+    s CONSTANT name = COALESCE(schema_hint, ncs());
 BEGIN
     RETURN NEXT is(
         ncs()
@@ -64,9 +67,8 @@ END
 $body$;
 
 CREATE FUNCTION _null_count_test.test__shutdown__drop_all
-() RETURNS SETOF text LANGUAGE plpgsql AS $body$
-DECLARE
-    v_schema CONSTANT text = current_setting('count_nulls.test_schema');
+(schema_hint name DEFAULT NULLIF(:'schema', '')::name)
+RETURNS SETOF text LANGUAGE plpgsql AS $body$
 BEGIN
     RETURN NEXT lives_ok(
         $$DROP EXTENSION count_nulls$$
@@ -74,12 +76,13 @@ BEGIN
 
     /*
      * Only try to drop a schema when TEST_SCHEMA actually created one -
-     * when it's empty, the extension lives wherever it landed on its own
-     * (see test/deps.sql), which this file has no business dropping.
+     * when it's empty (schema_hint is NULL), the extension lives wherever
+     * it landed on its own (see test/deps.sql), which this file has no
+     * business dropping.
      */
-    IF v_schema <> '' THEN
+    IF schema_hint IS NOT NULL THEN
         RETURN NEXT lives_ok(
-            format('DROP SCHEMA %I', v_schema)
+            format('DROP SCHEMA %I', schema_hint)
         );
     ELSE
         RETURN NEXT skip('TEST_SCHEMA is empty - no dedicated schema to drop');