Add test preflight and parameterize PostgreSQL connection in Makefile

CONTRIBUTING.md

@@ -38,3 +38,15 @@ When introducing, removing, or changing dependencies:
    - `pg_git.control` (where applicable),
    - any other install/release documentation.
 2. **Verify dependency names and versions are consistent** in all docs and metadata files.
+
+
+## Local/Docker Test Setup (Known-Good)
+
+Use the same `make test` entrypoint in both environments so prerequisite checks stay consistent.
+
+| Environment | Required environment variables | Command |
+| --- | --- | --- |
+| Local PostgreSQL | `PGHOST`, `PGPORT`, `PGUSER`, `PGDATABASE` (defaults in `makefile` target localhost:5432/postgres) | `make test` |
+| Docker Compose | `PGHOST=db`, `PGPORT=5432`, `PGUSER=postgres`, `PGDATABASE=pg_git_dev` | `docker-compose run --rm test` |
+
+`make test` depends on `test-preflight`, which validates DB connectivity, required extensions (`pgcrypto`, `pg_trgm`, `plpython3u`), and `pg_prove` availability before running SQL tests.

README.md

@@ -111,15 +111,19 @@ CREATE EXTENSION pg_git;
 
 ## Testing
 
-The authoritative test execution order is defined in `test/sql/manifest.txt`.
-`make test` reads that manifest, runs tests in the listed order, and enforces a guard
-that every `test/sql/*_test.sql` file is present in the manifest.
+`make test` now runs a preflight (`test-preflight`) before executing SQL TAP tests. The preflight checks:
+- PostgreSQL connectivity using `PGHOST`, `PGPORT`, `PGUSER`, `PGDATABASE`
+- required extensions are enabled (`pgcrypto`, `pg_trgm`, `plpython3u`)
+- `pg_prove` is installed and on `PATH`
 
-```bash
-# Optional overrides for your local PostgreSQL connection used by pg_prove:
-# PGHOST=localhost PGPORT=5432 PGUSER=postgres PGDATABASE=postgres
-make test
-```
+### Known-good test matrix
+
+| Environment | Connection setup | Test command |
+| --- | --- | --- |
+| Local PostgreSQL | `export PGHOST=localhost PGPORT=5432 PGUSER=postgres PGDATABASE=postgres` | `make test` |
+| Docker Compose (`db` service) | `PGHOST=db PGPORT=5432 PGUSER=postgres PGDATABASE=pg_git_dev` (already set in `docker-compose.yml`) | `docker-compose run --rm test` |
+
+If preflight fails, fix the reported prerequisite and re-run `make test`.
 
 ## Development
 Using Docker:
@@ -128,10 +132,10 @@ Using Docker:
 docker-compose up -d
 
 # Access psql console
-docker-compose exec db psql -U postgres
+docker-compose exec db psql -U postgres -d pg_git_dev
 
-# Run tests
-docker-compose run test
+# Run tests (includes the same preflight checks as local runs)
+docker-compose run --rm test
 
 ```
 

makefile

@@ -6,6 +6,15 @@ EXTVERSION = 0.4.0
 PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)
 
+# PostgreSQL connection defaults for local development/testing.
+PGDATABASE ?= postgres
+PGHOST ?= localhost
+PGPORT ?= 5432
+PGUSER ?= postgres
+
+# Shared psql command for test/preflight checks.
+PSQL := psql -v ON_ERROR_STOP=1 -X -w -h $(PGHOST) -p $(PGPORT) -U $(PGUSER) -d $(PGDATABASE)
+
 # Installable SQL assets only:
 #   - extension install/upgrade entrypoints in sql/*.sql
 #   - schema/function fragments loaded by those entrypoints
@@ -26,6 +35,25 @@ REGRESS_OPTS = --inputdir=test
 
 include $(PGXS)
 
+.PHONY: test test-preflight
+
+test-preflight:
+	@command -v pg_prove >/dev/null 2>&1 || { \
+		echo "ERROR: pg_prove is not installed or not on PATH."; \
+		echo "Install it via your package manager (often in postgresql-test/perl-Test-Harness-TAP packages)."; \
+		exit 1; \
+	}
+	@$(PSQL) -c 'SELECT 1;' >/dev/null || { \
+		echo "ERROR: unable to connect to PostgreSQL using PGHOST=$(PGHOST) PGPORT=$(PGPORT) PGUSER=$(PGUSER) PGDATABASE=$(PGDATABASE)."; \
+		echo "Check credentials, host reachability, and that the database exists."; \
+		exit 1; \
+	}
+	@$(PSQL) -tA -c "SELECT string_agg(e, ', ') FROM (VALUES ('pgcrypto'),('pg_trgm'),('plpython3u')) AS req(e) WHERE NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = req.e);" | \
+		awk 'NF { printf "ERROR: missing required extensions: %s\n", $$0; print "Install with: CREATE EXTENSION <name>;"; exit 1 }'
+	@echo "Preflight checks passed for PGHOST=$(PGHOST) PGPORT=$(PGPORT) PGUSER=$(PGUSER) PGDATABASE=$(PGDATABASE)."
+
+test: test-preflight
+	pg_prove -h $(PGHOST) -p $(PGPORT) -U $(PGUSER) -d $(PGDATABASE) $(TESTS)
 
 .PHONY: test test-one test-one-verbose test-list
 test: