# pgpipe First-Release Support Matrix

**Stage 1 scope baseline: 2026-09-24, commit
`5924ed49f34e68a6d4447233a478ca153bd822c3`.** This records the intended release
scope and the evidence still needed. It is not a production qualification
certificate. No release candidate has been certified by this assessment.

**Stage 1 status: scope definition and three-VM inventory complete.** Essential
implementation and release qualification remain the work of Stages 2–4.

## Read this first

The first production-qualified release will focus on **one PostgreSQL source
database replicating into one PostgreSQL destination database, with one active
pgpipe process per pipeline**. The source owns the expected table contents.
Independent application writes or schema changes on replicated destination
tables are outside the initial operating profile.

We will first qualify ordinary tables with stable primary keys, compatible
pre-created destination schemas, strict ordered durable writes, persistent
state, and a restricted authenticated dashboard. Extensions, automatic schema
operations and maintenance workflows have additional requirements; they are
listed separately rather than implied by ordinary CDC support.

Use three separate questions when reading a capability:

1. **Implemented?** Does the inspected code provide this behavior?
2. **Covered?** Are there executable tests for that exact behavior and profile?
3. **Qualified?** Did those tests and the required reviews pass for the exact
   published build and environment?

An implementation or a test file is not a passing qualification result. Prior
Ubuntu experiments are useful historical evidence, but cannot certify the next
release. **Exact-candidate qualification is pending throughout this matrix.**

## Scope decisions for the first release

| Area | Initial qualification scope | Boundary |
| --- | --- | --- |
| Replication | PostgreSQL to PostgreSQL; INSERT, UPDATE, DELETE, NULL and transaction ordering | No additional source engines, analytics destinations, fan-out, or bidirectional/conflict-resolution claim. |
| Database versions | **14 same-version or forward-version candidate pairs**: 14 → 15/16/17/18; 15 → 15/16/17/18; 16 → 16/17/18; 17 → 17/18; 18 → 18 | Every pair in the [candidate pair matrix](docs/support/platforms.md#candidate-pair-matrix) remains pending qualification. Destinations older than their source major and PostgreSQL 14 destinations are outside this candidate matrix. |
| Required broader version checks | Keep PostgreSQL 14 source checks, PostgreSQL 14 destination rejection, PostgreSQL 15–18 destination-safety checks and existing extension lanes | The candidate pair matrix does not remove any existing release gate; a focused pair test does not establish full release qualification. |
| Deployment | Linux native packages and Linux containers; retain required raw-binary checks | Qualify Ubuntu 26.04 DEB, the existing Fedora 44 RPM/systemd lane, and linux/amd64 plus linux/arm64 runtime evidence separately. A cross-compiled artifact is not a tested runtime. |
| State | BoltDB on persistent local storage is the reference installation; SQLite and PostgreSQL state have implemented alternatives | All required backend conformance/recovery gates remain. PostgreSQL state-server support is assessed separately from destination-server support. |
| Tables | Ordinary persistent tables with a stable simple or composite primary key and a matching destination unique arbiter | No general promise for keyless, generated-column, partitioned/inherited, RLS or arbitrary trigger/rule shapes. Consult the detailed table matrix. |
| Data values | Built-in types covered by the datatype harness, with exact declared destination shapes and encoding compatibility | Snapshot, live CDC, verification and repair have different evidence. XML, custom types, OID references and extension types require the specific conditions below. |
| Write policy | Strict ordering, durable destination commit, direct upsert; one effective streaming writer; row DLQ disabled in this baseline | This is an explicit recommended profile, not a statement that all shipped defaults already select it. No unconditional exactly-once, zero-loss or zero-latency promise. |
| Schema changes | Reviewed shape-specific manual column changes for the baseline; opt-in structured DDL only for its documented allowlist | Manual table rename does not establish continuity: source rename needs matching capture proof, and recreation needs its documented recovery procedure. No arbitrary SQL DDL replay or automatic custom-type migration. Required DDL regression tests still run. |
| Access | One administrator, verified database connections, private/loopback dashboard or properly configured HTTPS | RBAC/SSO is later work. Credential storage and source structured TLS protections are implemented in development; qualify their exact release paths. |
| Operations | Supported same-lineage restart, monitored lag/WAL/resources, reviewed table operations and a rehearsed backup/recovery procedure | No automatic HA, independent copied-state takeover, historical checkpoint replay or resumable mid-table snapshot promise. |
| Repair | Existing development capability remains default-off, with explicit review/approval and all eligibility checks | Implementation is not GA approval. All locked clean-major Phase 7 gates remain required even when repair is off. |

This is the bounded qualification target, not a claim that other accepted
configurations were removed from the product. The code accepts a broader range
in several places. Public release notes must name the combinations actually
qualified and distinguish conditional compatibility from full support.

The first four baseline pair runs completed on isolated native Ubuntu ARM64
instances with a PostgreSQL 14.24 source and PostgreSQL 15.19/16.15/17.11/18.6
destinations. **All four baselines failed.** PG14 → PG15/16/17 encountered a
false collation refusal for composite types; PG14 → PG18 was blocked at startup
by NOT NULL catalog drift. See the [measured results](docs/support/pg14-cross-version-20260924.md),
[case results CSV](docs/support/pg14-compatibility-matrix.csv) and
[job results CSV](docs/support/pg14-compatibility-jobs.csv); diagnostic profiles
are recorded separately from the baselines. The other ten pairs were untested
in that historical run. The [later Stage 3 run](docs/support/stage3-20260925.md)
completed the baseline at all fourteen pairs; its conditional profiles and
operational findings are separate. Release qualification remains pending for
all 14 pairs. The
[dedicated lab endpoints](docs/support/stage1-lab-20260924.md#follow-on-candidate-matrix-setup)
leave the existing PostgreSQL 18 clusters and GUI untouched.

The [subsequent PG14 collation fix](docs/support/pg14-collation-fix-20260924.md)
passed focused custom-type catalog tests on PG14–18 and live snapshot/CDC checks
against PG15/16/17 in both write modes. The subsequent
[PG18 NOT NULL fix](docs/support/pg18-notnull-fix-20260924.md) passed 80 focused
snapshot/CDC case attempts across PG14 → PG15/16/17/18, including both write
modes. The subsequent
[source-reconnection fix](docs/support/source-reconnect-fix-20260924.md) passed
focused automatic source-restart recovery checks. The subsequent
[target-reconnection fix](docs/support/target-reconnect-fix-20260925.md) passed
all 72 focused recovery phases across PG14 → PG15/16/17/18, including eight
automatic target and sixteen automatic source recoveries. These focused passes
do not replace the failed baseline or complete pair qualification.

## Detailed matrices

| Document | Questions it answers |
| --- | --- |
| [Platforms and database versions](docs/support/platforms.md) | Which source/destination versions, OS/architecture combinations, state stores and upgrade paths exist? Which tests cover them, and where is runtime evidence missing? |
| [Data types, tables and DDL](docs/support/data-types.md) | What is implemented for each requested type family? Does it cover snapshot, CDC, verification and repair? What must be prepared manually? |
| [Operating and recovery contract](docs/support/operating-contract.md) | Which durability settings define the initial profile? What resource bounds exist? What can an operator safely recover, and what still needs implementation? |
| [Stage 1 lab assessment](docs/support/stage1-lab-20260924.md) | What was observed on the three VMs, which build is running, and what needs attention before qualification? |

Examples of important distinctions:

- A `numeric` column passing CDC tests does not prove every possible numeric
  precision, workload size or use of that type as a primary key.
- Raw XML may retain its meaning while its declaration changes. Exact stored
  text requires the prepared `xml_text` companion workflow.
- A pgvector column requires matching reviewed extension versions, dimensions
  and permissions. Merely installing the extension is insufficient.
- An enum can replicate with a matching type already prepared on both databases;
  that does not imply pgpipe automatically creates or migrates enum definitions.
- A successful PostgreSQL 18 safety check does not prove PostgreSQL 14 → 18 CDC,
  a different provider build, or every possible PostgreSQL 18 table shape.

## Known limitations and work carried forward

| Finding | Classification | Next action |
| --- | --- | --- |
| Whole-pipeline pause/resume is implemented in development | Exact-release recovery qualification pending | Follow the [pause/resume operating contract](docs/pause-resume.md) and rerun transaction, restart and retained-WAL checks against the release candidate. |
| Source structured CA/client-certificate/key fields reach SQL and replication connections | Exact-release TLS qualification pending | Follow the [credential/TLS operating contract](docs/credential-tls-protection.md); rerun certificate rejection, mutual TLS and reconnect checks against the release candidate. |
| Managed password hashes, protected secret-file inputs/generated files and source TLS wiring are implemented in development | Exact-release security qualification pending | Retain the [credential/TLS operating contract](docs/credential-tls-protection.md), rerun its security and platform checks against the published candidate, and repeat the [verification/recovery procedures](VERIFICATION_RECOVERY.md) on the candidate. |
| Broad type fixtures do not cover every verification/repair/key/auto-DDL combination | Evidence gap | Build a per-operation matrix for the intended release lanes; retain conditional or excluded status where evidence is absent. |
| Source version acceptance and published binary targets are broader than full runtime coverage | Evidence gap | Test all 14 named candidate pairs and required platform/version gates; do not turn successful builds into compatibility claims. |
| No current universal throughput, maximum row size, total RSS or recovery-time promise | Measurement gap | Establish workload-specific limits and headroom in Stage 3. Existing configured limits are component bounds, not service-level guarantees. |
| Backups, destination authority and checkpoints must agree | Recovery constraint | Rehearse a compatible recovery cohort and retain the global roles/ACLs required by the destination safety contract. Managed backup/restore tooling can follow the supported manual procedure. |
| Final comparison during independent writes can be inconclusive | Consistency constraint | Quiet selected source application writes, stop independent destination writes/DDL, catch up, and compare while both sides remain stable. |
| Source recreation, absent WAL, unsafe table shapes and unknown catalog builds can fail closed | Deliberate safety restriction | Document the refusal and supported recovery path. Do not reset state or bypass guards to turn a refusal into a passing test. |

Historical DATE-infinity, JSONPath, XML, pgvector and stale-COPY bug reports must
not be repeated as current failures merely because they appear in old reports.
Their fixes and focused regression cases exist. The next release must rerun the
relevant tests; this assessment did not rerun the complete CDC suite.

## Stage 1 completion and handoff

The scope definition is complete when the following are recorded:

- Exact code baseline and status vocabulary.
- Named initial qualification lanes and the required wider release gates.
- Type/table/DDL conditions, explicit exclusions and evidence references.
- Deployment, access, durability, resource and recovery boundaries.
- Lab inventory findings, with unavailable observations marked unavailable.
- Essential implementation gaps and the evidence required before publication.

Stage 1 is documentation and assessment. It does not install a new build,
change VM configuration, restart replication, create test tables, run destructive
tests, or certify production readiness. Any unavailable lab observation remains
an explicit follow-up rather than an assumed pass.

Stage 2 now has development pause/resume and credential/TLS implementations,
plus the [verification/recovery runbook](VERIFICATION_RECOVERY.md). Its focused
drills and documented unsupported recovery cases do not complete Stage 3.
Stage 3 exercises the supported implementation and recovery scope. Its
[development evidence](docs/support/stage3-20260925.md) records the corrected
version matrix and separate load, installation and browser outcomes. The later
[installation and GUI close-out](docs/support/stage3-closeout-20260927.md)
completes the requested development campaign, with its platform and host-intervention
limitations recorded. Results across development builds do not qualify a release.
Stage 4 binds all required passing tests, installation/security/
soak/recovery/performance evidence, named reviews and artifacts to one unchanged
candidate. See [the production plan](PRODUCTION_READINESS_PLAN.md),
[CI](CI.md#phase-7-release-certification), and
[the release contract](DESTINATION_SAFETY_CONTRACT.md#15-phase-7-documentation-and-release-certification).