Release Gate Matrix

V1 supports PostgreSQL 17. PostgreSQL 15, 16, and 18 are post-V1 certification targets, and PostgreSQL 14 is legacy best-effort; none is a V1 release blocker.

PostgreSQL Status Required release gates
14 Best-effort legacy May run warning-only compatibility checks; failures do not block release.
15 First-class planned Fast Rust tests, context-pg check, pgrx SQL tests, heavy lifecycle tests.
16 First-class planned Fast Rust tests, context-pg check, pgrx SQL tests, heavy lifecycle tests.
17 Primary first-class planned Fast Rust tests, context-pg check, pgrx SQL tests, heavy lifecycle tests, local smoke gates.
18 First-class planned Fast Rust tests, context-pg check, pgrx SQL tests, heavy lifecycle tests.

Gate Tiers

Pull requests run format, clippy, fast workspace tests, docs, source hygiene, and supply-chain checks. They also check context-pg for supported PostgreSQL features when the CI runner can provide matching PostgreSQL development files.

Final supply-chain evidence is captured with:

scripts/run-supply-chain-report.sh \
  --out-dir target/supply-chain/release-candidate

The report stays incomplete for dirty trees, dry-runs, advisory failures, or license/ban/source failures from cargo deny check.

Nightly jobs run fuzz smoke checks, Miri for storage, sanitizer jobs where the platform supports them, generated SQL reproducibility checks, and optional coverage or unused-dependency checks.

Future multi-major certification jobs run the full PostgreSQL 15-18 matrix:

  • cargo test --workspace --exclude context-pg --all-features;
  • cargo check -p context-pg --no-default-features --features pgXX;
  • cargo pgrx test --release -p context-pg pgXX;
  • cargo pgrx schema -p context-pg pgXX --out target/release-sql/pgXX.sql;
  • heavy install, backup/restore, crash/restart, upgrade, low-memory, and corruption tests for each supported PostgreSQL major;
  • cargo audit, cargo deny check, source hygiene, docs, license review, and benchmark/recall reports.

Generated extension SQL must be built from a clean tree with Rust 1.96.0, pgrx 0.19.1, and the same release feature set. Release notes must state any waived benchmark, fuzz, sanitizer, Miri, platform, or PostgreSQL-version gate.

Use the local matrix runner to capture auditable fast, pgrx, and heavy gate evidence:

scripts/run-postgres-matrix-gates.sh --allow-missing

Use --mode fast, --mode schema, --mode pgrx, or --mode heavy to rerun one gate tier. Fast mode records separate rows for workspace fast tests, context-pg feature checks, and context-pg Rust tests. Schema mode records generated extension SQL paths and checksums. Heavy mode records one report row per heavy harness script, including install, upgrade, backup/restore, cross-version import, crash/restart, VACUUM, concurrency, recall, ACL/RLS, late-interaction ANN serving, low-memory, corruption, and SQLSTATE gates.

--allow-missing records unsupported local hosts as skipped when a matching pg_config is unavailable. Do not use skipped or failed rows as release approval; rerun the missing PostgreSQL majors on CI or a release host with the matching development files installed before checking off the matrix gate. Matrix reports mark approval as incomplete whenever any row is skipped, failed, missing, or dry-run. Before the first released upgrade fixture exists, the heavy:upgrade_matrix row records current-version lifecycle coverage and is marked skipped for upgrade-from-previous evidence. Do not use that skipped row to check off upgrade coverage without an explicit release waiver.

The release-gates workflow also runs the all-major report directly with scripts/run-postgres-matrix-gates.sh --mode all --out-dir target/postgres-matrix/all-postgres and uploads it as combined-postgres-matrix-report. That report is the CI artifact shaped for final release-note validation: it must contain every fast, schema, pgrx, and heavy row for PostgreSQL 15, 16, 17, and 18 with no skipped, missing, failed, or dry-run rows before the PostgreSQL matrix gate can close.

Containerized Linux Gate

Run the containerized Linux gate before publishing release artifacts:

PG_MAJOR=17 scripts/release-linux-container-gates.sh

Repeat with PG_MAJOR=15, 16, 17, and 18 for the supported matrix. The container pins Rust and pgrx versions, installs matching PostgreSQL development files, runs fast Rust gates, checks context-pg, and writes generated extension SQL under target/release-sql/. It does not replace cargo pgrx test; use the PostgreSQL matrix runner for pgrx SQL-test evidence.

Before claiming macOS and Linux build coverage, attach a combined platform build report:

scripts/run-platform-build-report.sh \
  --platform macos \
  --out-dir target/platform-builds/macos

scripts/run-platform-build-report.sh \
  --platform linux \
  --out-dir target/platform-builds/linux

scripts/run-platform-build-report.sh \
  --merge-report target/platform-builds/macos/report.md \
  --merge-report target/platform-builds/linux/report.md \
  --out-dir target/platform-builds/release-candidate

Run each per-platform report on the matching release host, then merge those reports into the release-candidate directory. The Linux container gate is diagnostic evidence only. Final platform approval requires a clean tree, macOS and Linux rows, all platform-build CI gates passing, no dry-run/skipped rows, Linux host evidence from a Linux runner, macOS host evidence from a Darwin runner, and the generated summary.tsv referenced from the merged report. The release-gates workflow uploads each per-host target/platform-builds directory and has a platform-build-summary job that downloads the Linux and macOS reports, runs the same merge command, and uploads combined-platform-build-report from target/platform-builds/release-candidate.

Release Artifact Report

The current V1 publication payload is PG17-only and unsigned. Build it twice, verify its complete checksum manifest, SBOM, provenance, and policy:

release/build-packages.sh --out-dir target/release-payload v0.1.0
scripts/verify-release-payload.py \
  --tag v0.1.0 \
  --candidate-sha "$(git rev-parse HEAD)" \
  target/release-payload

The older combined report below is retained for post-V1 multi-major and signing certification. Pass one generated SQL artifact for every first-class major and any package/install outputs. Each generated SQL artifact must have a sibling pgXX.sql.build.log from the cargo pgrx schema command that records the command, commit, artifact path, and SHA-256 hash. The report records commit SHA, clean-tree state, Rust, Cargo, cargo-pgrx, artifact sizes, SHA-256 checksums, signature verification status, and version consistency between context-pg and pgcontext.control. Reports stay incomplete for dirty trees, dry-runs, missing or empty artifacts, toolchain/version mismatches, missing PostgreSQL 15-18 generated SQL artifacts, missing or invalid generation logs, duplicate generated SQL artifacts for the same major, and unsigned or unverifiable artifacts when signatures are required. Per-major CI artifact reports are useful diagnostics, but the final release-artifact approval requires the combined all-major report. The release-gates workflow uploads each generated target/release-sql/pgXX.sql artifact and build log, downloads the four per-major artifacts into one directory, and emits a combined unsigned diagnostic report at target/release-artifacts/all-postgres. Publishing-host release approval still requires rerunning the combined report with signatures when the publishing target requires signed artifacts.