PostgreSQL 18 Baseline Upgrade for Containerized Stack

                                                            RFC-DBOPS-0001
                                                            Category: Standards Track
                                                            Status: Draft
                                                            Database Engineering
                                                            February 2026

Status of This Memo

This document specifies a standards-track architecture for upgrading the containerized PostgreSQL baseline to major version 18. Distribution of this memo is unlimited within the organization and to authorized external reviewers.

This document is a DRAFT and is subject to change based on review feedback.

Abstract

This RFC defines the architecture decision to standardize the PostgreSQL baseline at major version 18 for the containerized stack that serves local development and production environments. The decision applies to both the metadata database and the tenant database, and it codifies a uniform baseline to reduce drift, improve operational predictability, and ensure a consistent extension surface area.

The document specifies non-negotiable invariants for data integrity, rollback safety, logical decoding continuity, extension availability, and connection pooling compatibility. It also describes the architecture-level approach, affected components, and upgrade mechanics without prescribing operational runbooks or implementation commands.

The RFC provides a shared contract for platform and application teams so that all services relying on PostgreSQL, PgBouncer, Debezium, and schema migration tooling can adopt the upgrade with explicit guarantees and known constraints.

Document Information

Scope Boundaries

Intended Audience

This document is written for:

• Platform & Infrastructure Engineers
• Application Developers consuming PostgreSQL services
• Database Reliability Engineers
• Review Board

No prior knowledge of the internal system is assumed.

Conventions and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Table of Contents

Part 1: Foundation

1. Introduction and Motivation

   • 1.1 Background
   • 1.2 Current State
   • 1.3 Motivation
   • 1.4 Scope Statement

2. Requirements and Invariants

   • 2.1 Design Goals
   • 2.2 Non-Goals
   • 2.3 Invariants
   • 2.4 Success Criteria

Part 2: Architecture

3. System Architecture

   • 3.1 System Overview
   • 3.2 Authority Domains
   • 3.3 Trust Boundaries
   • 3.4 Stable Interfaces

4. System Components

   • 4.1 PostgreSQL Image Build
   • 4.2 Metadata Database Container
   • 4.3 Tenant Database Container
   • 4.4 PgBouncer Transaction Pooler
   • 4.5 PgBouncer Session Pooler
   • 4.6 Debezium Connect
   • 4.7 Schema Migration Tooling
   • 4.8 Extension Ecosystem

Part 3: Upgrade Mechanics

5. Upgrade Mechanics
   • 5.1 Major Version Data Directory Constraints
   • 5.2 Extension ABI and Catalog Compatibility
   • 5.3 Logical Decoding and CDC
   • 5.4 Rollback Properties
   • 5.5 Operational Constraints
   • 5.6 Schema Migration Baselining

Part 4: Rationale and Evolution

6. Design Rationale

   • 6.1 Rejected Alternatives

7. Future Considerations

   • 7.1 Future Considerations

Appendices

• Appendix A: Glossary and Indexes
• Appendix B: References

Quick Navigation

Reading Paths

Platform / Infra Engineers? Start with Introduction → Requirements → Architecture → Upgrade Mechanics

Application Teams? Focus on Introduction → Requirements → Components → Glossary

Review Board? Read all sections, especially Requirements (Invariants) → Rationale → Evolution

Understanding Design Decisions? Read Requirements → Rationale → Evolution

Document Navigation

End of Section 0