pgAgroal Enterprise · Explanation

Architecture

pgAgroal Enterprise is a control and management plane built on top of standard, unmodified pgagroal. This page explains the core architectural decision behind it — attach alongside, not in front — why that decision was made, and what it means for how instances are managed and where the trust boundary sits.

Attach alongside, not in front

The central architectural decision (ADR-0001) is how the enterprise layer attaches to pgagroal. Three models were considered:

Alongside — the enterprise components run as separate processes that manage, observe, and orchestrate standard pgagroal instances through their existing config and management interfaces.
In front — an Elevarq component sits in the connection path ahead of pgagroal, handling routing, audit, and coordination itself.
Inside— modify pgagroal's C source to add behaviour.

Enterprise attaches alongside. Standard pgagroal is treated as a pinned, unmodified black-box dependency, and the enterprise value is built in the control and management plane around and above it.

Alongside means the data path is unchanged: client connections still terminate at standard pgagroal. The enterprise layer never sits between a client and the pooler.

Why alongside

The choice is not merely stylistic — it makes the product's foundational commitments true by construction rather than by discipline:

It structurally enforces the commitments.You cannot diverge what you do not modify, so "no fork of core" and "never block or delay upstream" hold because the base is never touched, not because someone remembered to honour them.
It matches where the value is. Most enterprise capabilities — the operator, fleet config, policy, drift detection, managed upgrades, HA orchestration, coordinated limits, observability — live above a single pooler, not inside it.
It decouples our velocity from upstream's cadence. Pinning a released base means upstream's release pace affects which version is pinned, not the enterprise feature velocity.
It keeps traceability clean. A known upstream tag is pinned, BSD-3 attribution is retained, and an SBOM is emitted — auditable in a way a private patch set is not.

Why the data path stays the open pooler

Operator + control plane

Enterprise · manages & configures

Client apps

your services

pgAgroal pooler

unmodified upstream pgagroal

PostgreSQL

your database

The control plane configures and manages poolers from the side — it is not in the request path. Pools keep serving even if the control plane is down.

Putting an Elevarq component in front of pgagroal was rejected for two concrete reasons. First, an extra hop in the connection path undercuts pgagroal's low-latency value — a paid product slower than the free pooler is the wrong trade. Second, sitting in front means parsing the PostgreSQL wire protocol, which re-introduces exactly the pre-auth memory-safety surface the project works to keep out of the data path.

There is a more important operational consequence. Because the control plane is not in the connection path, a control-plane failure does not interrupt traffic. If the control plane is down, being upgraded, or unreachable, existing and new client connections continue to flow through standard pgagroal unaffected. Management and observation pause; serving does not. This data-plane independence is an architectural invariant of the alongside model, not a feature that has to be added.

Features that genuinely must live in the data path are the rare exception, evaluated explicitly against these costs. The default is always to do the work alongside, consume pgagroal's existing outputs, or contribute a generic extension point upstream.

The operator and the optional control plane

The enterprise layer is composed of separate processes that sit above the poolers:

Operator — manages the lifecycle of pgagroal instances and reconciles them against declared configuration.
Control plane— manages many standard pgagroal instances as one fleet: inventory, health, drift detection, and audited config-apply, over pgagroal's existing public interfaces only. It is an optional layer; the poolers run with or without it.

Neither component contains data-path code and neither forks pgagroal. The control-plane reference catalogues its subsystems in detail.

How instances are discovered and managed

Instances are discovered through a static registry or via Kubernetes discovery, then managed entirely through pgagroal's existing public interfaces:

Observe — the control plane probes instances for metrics, aggregates fleet health, and marks unreachable instances stale.
Detect drift — a read-only comparison of declared configuration against the actual running configuration.
Apply config — the write path applies configuration via pgagroal-cli remote management, with dry-run, authorization, and partial-failure handling.

Credentials are resolved from a cloud secret manager and materialized into pgagroal's users file — again without any pgagroal source change. CDC-dependent capabilities consume logical decoding from PostgreSQL directly rather than through pgagroal, so they too fit the alongside model.

The trust boundary

The boundary between the closed enterprise layer and the open base is the spine of the architecture. Standard upstream pgagroal — the open, shared pooler that handles every client connection — sits on one side. The proprietary operator and control plane sit on the other and only ever reach pgagroal through its public, documented interfaces: its config files, management API, metrics, and logs. There is no private patch, no shared memory, and no in-path interposition crossing that line.

Operator actions cross the boundary under authentication and authorization, and every mutating action is recorded to a hash-chained, tamper-evident audit log before it is performed. That keeps the boundary auditable and supports our compliance-readiness goals, aligned with the controls Elevarq is building toward.

The open base stays standard and the enterprise layer stays proprietary; functionality flows closed to open over time, never the reverse. See Open core for the boundary as a product commitment.