1. Introduction and Motivation
1. Introduction and Motivation
← Index | Index | Next: 2. Requirements →
1.1 Background
The platform relies on a containerized PostgreSQL stack that serves both application workloads and operational tooling. The stack includes custom database images, dual PgBouncer poolers, and change data capture via Debezium. A unified baseline is required to keep database behavior stable across environments and to enable consistent extension support.
1.2 Current State
The containerized PostgreSQL stack has the following characteristics:
| Aspect | Current State |
|---|---|
| PostgreSQL version | Custom image pinned to major version 16 for both build and runtime layers |
| Extensions loaded | pg_cron installed and preloaded; version-specific development and cron packages included |
| Removed extensions | Apache AGE, pgvector, and pg_net were previously included in the container image but have been removed |
| Entrypoint | Preloads pg_cron and enables statement logging for the runtime process |
| Compose stack | Builds metadata and tenant database containers from the custom image; preloads pg_cron on both |
| Tenant config | Dedicated postgresql.conf sets wal_level to logical for Debezium and configures scram-sha-256 password encryption |
| CDC initialization | Debezium initialization script uses the PostgreSQL connector class and the pgoutput logical decoding plugin |
| Schema manager docs | References a pgvector image pinned to pg16 for local development |
1.2.1 Prisma Migration State
The Prisma migration files — particularly the initial migration — contain
CREATE EXTENSION statements for Apache AGE, pgvector, and pg_net. These
statements were authored when the container image included those extensions.
The extensions have since been removed from the container configuration,
creating a divergence between the recorded migration history and the
actual extension surface of the database.
This divergence is addressed by Prisma baselining as part of the upgrade (see Section 5.6).
1.3 Motivation
The current baseline creates an increasing mismatch between PostgreSQL features, security updates, and extension ecosystems. A major version upgrade standardizes behavior, reduces support risk, and aligns the containerized stack with the newest stable PostgreSQL capabilities while preserving CDC and pooling contracts.
The removal of Apache AGE, pgvector, and pg_net from the container image further motivates a clean baselining of the schema migration history to reflect the actual runtime extension surface.
1.4 Scope Statement
This RFC defines the architectural decision, invariants, and component-level impacts for upgrading the containerized PostgreSQL baseline from 16 to 18 for local and production environments. It does not prescribe operational runbooks or application-level schema changes.
Document Navigation
| Previous | Index | Next |
|---|---|---|
| ← 0. Index | Table of Contents | 2. Requirements → |
End of Section 1