4. System Components
4. System Components
← 3. Architecture | Index | Next: 5. Upgrade Mechanics →
4.1 PostgreSQL Image Build
| Aspect | Description |
|---|---|
| Responsibility | Produces the PostgreSQL runtime image used by metadata and tenant databases |
| Extensions | Packages pg_cron; AGE, pgvector, and pg_net have been removed from the container image |
| Interfaces | Exposes the PostgreSQL server binary and extension shared objects |
| Failure Modes | Extension ABI mismatch prevents server start; missing extension packages block preloads |
4.2 Metadata Database Container (db)
| Aspect | Description |
|---|---|
| Responsibility | Hosts platform metadata for ATS services |
| Baseline | Enforces PostgreSQL 18 baseline and shared extension availability |
| Interfaces | SQL protocol via PgBouncer transaction and session poolers |
| Failure Modes | Upgrade failure leaves the container on an unsupported baseline; schema migration tools fail when session pooling is unavailable |
4.3 Tenant Database Container (tenant_db)
| Aspect | Description |
|---|---|
| Responsibility | Hosts tenant data and enables logical decoding for CDC |
| Configuration | Applies configuration that must persist across the major upgrade (wal_level, password encryption) |
| Interfaces | SQL protocol via PgBouncer; logical decoding stream for Debezium |
| Failure Modes | Logical decoding incompatibility disrupts CDC; configuration drift disables wal_level or preloads |
4.4 PgBouncer Transaction Pooler
| Aspect | Description |
|---|---|
| Responsibility | Provides high-concurrency transaction pooling for application workloads |
| Interfaces | PostgreSQL protocol proxy for short-lived transactions |
| Failure Modes | Pooler compatibility issues with PostgreSQL 18 lead to connection churn; authentication misalignment blocks application access |
4.5 PgBouncer Session Pooler
| Aspect | Description |
|---|---|
| Responsibility | Provides session pooling for migration and administrative workflows |
| Interfaces | PostgreSQL protocol proxy with session persistence |
| Failure Modes | Session state regressions break migrations or tooling that relies on prepared statements |
4.6 Debezium Connect
| Aspect | Description |
|---|---|
| Responsibility | Consumes logical decoding from the tenant database and publishes change events |
| Interfaces | PostgreSQL logical decoding protocol via replication slots |
| Failure Modes | Plugin or protocol incompatibility halts CDC; replication slot resets or invalidation during upgrade cause data gaps |
4.7 Schema Migration Tooling (Prisma and Atlas)
| Aspect | Description |
|---|---|
| Responsibility | Applies and validates schema changes across metadata and tenant databases |
| Interfaces | Session pooler connections for migrations and schema validation |
| Failure Modes | Tooling incompatibility with PostgreSQL 18 prevents schema evolution; shadow database workflows fail due to extension mismatches |
4.7.1 Prisma Baselining Requirement
The Prisma migration history contains CREATE EXTENSION statements for
Apache AGE, pgvector, and pg_net in the initial migration files. These
extensions were present in the older container configuration but have
since been removed.
When Prisma is baselined against the PostgreSQL 18 container, the
baselining process reconciles the recorded migration history with the
actual database state. Because the new container does not include AGE,
pgvector, or pg_net, the baselined migration history no longer contains
CREATE EXTENSION statements for these removed extensions.
This baselining MUST be performed as part of the upgrade to ensure that the migration tooling accurately reflects the extension surface of the containerized stack. See Section 5.6 for the architectural constraints governing this process.
4.8 Extension Ecosystem
| Aspect | Description |
|---|---|
| Responsibility | Provides PostgreSQL extensions required by platform features |
| Active | pg_cron (scheduled job execution inside the database server) |
| Removed | Apache AGE, pgvector, and pg_net have been removed from the container image and are no longer part of the extension surface |
| Interfaces | Extension shared libraries loaded by PostgreSQL at startup or on demand |
| Failure Modes | Extension unavailability or incompatible builds prevent database startup or feature use |
Document Navigation
| Previous | Index | Next |
|---|---|---|
| ← 3. Architecture | Table of Contents | 5. Upgrade Mechanics → |
End of Section 4