RFC-DBOPS-0001                                                    Section 5
Category: Standards Track                              Upgrade Mechanics

PostgreSQL major versions are not binary compatible at the data-directory level. The architecture MUST treat PostgreSQL 18 as a new major baseline, and any upgrade plan MUST account for data directory incompatibility as a first-class constraint.

5.2 Extension ABI and Catalog Compatibility

Extensions that compile against PostgreSQL server headers are tied to a specific major version. The PostgreSQL 18 upgrade MUST rebuild or repackage extension binaries against the PostgreSQL 18 ABI and ensure extension catalogs are valid after upgrade.

This requirement applies to pg_cron, the only extension that remains in the container image. Extensions previously included (Apache AGE, pgvector, pg_net) have been removed and do not require ABI recompilation.

5.3 Logical Decoding and CDC

Logical decoding depends on wal_level logical and stable replication slot semantics. The upgrade MUST preserve logical decoding capability for the tenant database and maintain compatibility with Debezium's PostgreSQL connector and pgoutput plugin.

5.4 Rollback Properties

The upgrade architecture MUST provide a reversible path that preserves the pre-upgrade PostgreSQL 16 state until PostgreSQL 18 is validated. Rollback capability MUST be preserved across both metadata and tenant databases.

5.5 Operational Constraints

The upgrade introduces an unavoidable transition boundary where PostgreSQL 16 and PostgreSQL 18 coexist or are swapped. The architecture MUST treat this boundary as a controlled change with explicit validation gates, and it MUST avoid partial or drifting baselines across the two databases.

5.6 Schema Migration Baselining

5.6.1 Context

The older container configuration included PostgreSQL extensions Apache AGE, pgvector, and pg_net. These extensions have been removed from the current container image. However, the Prisma migration history — specifically the initial migration files — contains CREATE EXTENSION statements for these extensions because the migrations were authored when the extensions were part of the container.

This creates a divergence: the recorded migration state references extensions that no longer exist in the runtime environment.

5.6.2 Baselining Requirement

Prisma baselining MUST be performed as part of the PostgreSQL 18 upgrade to reconcile the migration history with the actual database state. The baselining process marks the current database schema as the new migration baseline, effectively replacing the historical migration chain with a snapshot of the current state.

Because the PostgreSQL 18 container does not include AGE, pgvector, or pg_net, the baselined migration state does not contain CREATE EXTENSION statements for these removed extensions. This aligns the migration tooling with the actual extension surface of the containerized stack.

5.6.3 Architectural Constraints

Constraint	Description
Timing	Baselining MUST occur after the PostgreSQL 18 container is operational and before new migrations are applied
Extension surface alignment	The baselined state MUST reflect only extensions present in the PostgreSQL 18 container (pg_cron)
Migration history continuity	New migrations authored after baselining MUST apply cleanly on top of the baselined state
Rollback consideration	If rollback to PostgreSQL 16 is required before baselining is committed, the original migration history remains available

5.6.4 Impact

Aspect	Before Baselining	After Baselining
Initial migration	Contains `CREATE EXTENSION` for AGE, pgvector, pg_net	Baselined; stale extension statements removed
Extension surface	Migration history references extensions not present in container	Migration history matches container extension surface
New migrations	Risk of conflict with stale extension references	Clean baseline for future schema changes

Previous	Index	Next
← 4. Components	Table of Contents	6. Rationale →

End of Section 5

5. Upgrade Mechanics