2. Requirements and Invariants
2. Requirements and Invariants
← 1. Introduction | Index | Next: 3. Architecture →
This section defines the constraints and invariants that shape all subsequent architectural decisions. No design presented in later sections MAY violate the principles established here.
2.1 Design Goals
2.1.1 Baseline Alignment
All containerized PostgreSQL instances MUST target major version 18.
A single major version baseline eliminates version-specific behavior differences across metadata and tenant databases and simplifies extension packaging, pooler validation, and CDC compatibility testing.
2.1.2 Extension Parity
Required extensions MUST be available and loadable for PostgreSQL 18.
The current required extension is pg_cron. Extensions previously included in the container image (Apache AGE, pgvector, pg_net) have been removed and are no longer part of the required extension surface.
2.1.3 CDC Continuity
Logical decoding MUST remain enabled and compatible with Debezium.
The tenant database depends on wal_level logical and the pgoutput plugin
for change data capture. The upgrade MUST preserve this capability
without protocol or plugin incompatibility.
2.1.4 Pooling Stability
PgBouncer transaction and session pool modes MUST remain valid for their respective workloads.
Application traffic relies on transaction pooling for high concurrency, and migration tooling relies on session pooling for transactional semantics. Both modes MUST continue to function after the upgrade.
2.1.5 Upgrade Safety
The upgrade approach MUST preserve data integrity and enable rollback.
No upgrade path MAY be adopted unless it demonstrates data equivalence before and after, and a rollback mechanism to PostgreSQL 16 remains available until the upgrade is validated.
2.2 Non-Goals
2.2.1 Application Feature Changes
This RFC MUST NOT introduce application feature changes or schema redesigns. The upgrade concerns the database engine baseline, not the schemas or application logic built on top of it.
2.2.2 Operational Runbooks
This RFC MUST NOT define step-by-step operational runbooks or commands. Implementation procedures belong in separate operational documentation.
2.2.3 Access Control Changes
This RFC MUST NOT alter service-level access control or credential models. Authentication and authorization mechanisms remain unchanged by the baseline upgrade.
2.3 Invariants
Invariant 1 — Baseline Version
All containerized PostgreSQL instances (metadata and tenant) MUST run major version 18 after the upgrade is completed.
This invariant ensures a single baseline for compatibility, debugging, and extension support.
Invariant 2 — Data Integrity Preservation
All user and system data MUST remain logically equivalent before and after the upgrade, and any upgrade path that cannot demonstrate equivalence MUST be rejected.
This invariant protects business data and prevents silent corruption or loss.
Invariant 3 — Rollback Capability
A rollback path to PostgreSQL 16 MUST remain available until PostgreSQL 18 is validated for both metadata and tenant databases.
This invariant guarantees recoverability when post-upgrade validation uncovers regressions.
Invariant 4 — Logical Decoding Continuity
wal_level MUST remain set to logical for the tenant database, and Debezium connectors MUST continue to stream changes without incompatible protocol or plugin changes.
This invariant preserves CDC behavior relied upon by downstream systems.
Invariant 5 — Extension Availability
pg_cron MUST be available for PostgreSQL 18 and compiled against the PostgreSQL 18 server ABI.
Extensions previously included in the container image — Apache AGE,
pgvector, and pg_net — have been removed from the container
configuration and are no longer required. Prisma migration files that
reference these extensions MUST be baselined to remove stale CREATE EXTENSION statements (see Section 5.6).
This invariant prevents runtime failures caused by missing or mismatched extensions for the extensions that remain in the stack.
Invariant 6 — Pooler Compatibility
PgBouncer transaction pooling for application traffic and session pooling for migration and administration MUST remain compatible with PostgreSQL 18.
This invariant preserves connectivity contracts and operational workflows.
2.4 Success Criteria
| Criterion | Metric | Target |
|---|---|---|
| Baseline version | Metadata and tenant database containers report PostgreSQL version | PostgreSQL 18 |
| CDC operational | Debezium consumes logical changes without connector errors attributable to the upgrade | Zero upgrade-related CDC errors |
| Pooler compatibility | PgBouncer supports transaction and session modes without behavioral regressions | No pooler regressions |
| Required extensions available | pg_cron is available and loadable in PostgreSQL 18 | pg_cron loads successfully |
| Prisma baseline aligned | Prisma migration history contains no CREATE EXTENSION statements for removed extensions | No stale extension references |
| Rollback readiness | Rollback path to PostgreSQL 16 is maintained until upgrade validation completes | Rollback available until sign-off |
Document Navigation
| Previous | Index | Next |
|---|---|---|
| ← 1. Introduction | Table of Contents | 3. Architecture → |
End of Section 2