pgAgroal Enterprise · Reference
Glossary
Definitions of the terms used across the pgAgroal Enterprise documentation. The PostgreSQL-specific terms come first, since they are the unfamiliar ones if you work in Kubernetes but not Postgres; the Kubernetes terms are at the end and kept brief. Each term has its own anchor, so you can link straight to it.
Connection pooler
A connection pooler keeps a small, reusable set of backend connections open to PostgreSQL and multiplexes many client connections onto them. Clients connect to the pooler instead of to PostgreSQL directly, so the database sees a handful of steady connections rather than one per client. This caps the load that connection churn places on the database and lets far more clients share a fixed pool. pgagroal is the pooler at the centre of pgAgroal Enterprise; the pooler itself is unmodified upstream pgagroal.
Pipeline
Pipeline is pgagroal's name for a pooling mode — how it decides when a backend connection can be reused for another client. There are three: performance, session, and transaction. With performance and session, reuse is session-scoped: a backend connection stays tied to one client for the life of its session. With transaction, reuse is transaction-scoped: a backend connection is returned to the pool at the end of each transaction, so more clients can share fewer connections. See the concepts page for the trade-offs between them.
HBA (host-based authentication)
HBA is PostgreSQL's host-based authentication: a rules file, pg_hba.conf, that decides who may connect. Each rule matches on the connecting user, the database they want, and the network address they come from, and then says which authentication method they must use (for example a password, or a certificate). PostgreSQL reads the rules top to bottom and applies the first one that matches, so order matters. The pooler has its own HBA rules governing which clients may connect to it.
Frontend users
Frontend users are the users and credentials that clients present to the pooler — the pooler's own front door. They are distinct from the credentials the pooler uses to reach PostgreSQL behind it. This separation lets the pooler authenticate clients itself without handing them the database's credentials. In pgagroal these are configured in pgagroal_frontend_users.conf (managed with pgagroal-admin): a frontend user remaps a client-facing password to the real PostgreSQL password, so the application connects with one credential while pgagroal connects to PostgreSQL with another.
Split security
Split security is the pattern where the credentials clients use to authenticate to the pooler are kept separate from the credentials the pooler uses to authenticate to PostgreSQL. Because the two are different, client passwords are never the database passwords: a leaked client credential does not grant direct access to the database, and you can rotate one side without touching the other. pgagroal implements this with frontend users (the pgagroal_frontend_users.confpassword remapping described above); its manual documents the pattern under “split security”.
DSN (data source name)
A DSN, or data source name, is a single connection string that bundles everything needed to reach a database: host, port, database name, user, and connection options. Instead of passing each value separately, a component is handed one DSN string. The control plane is configured with a PostgreSQL DSN that tells it which database to use for its own state.
backendHost
backendHost is the field on the Pgagroal custom resource that names the PostgreSQL service the pooler sits in front of — the "backend". The pooler connects there on the backend port, which is 5432 (the default PostgreSQL port) unless you set another. Clients talk to the pooler; the pooler in turn talks to whatever backendHost points at.
Operator
The operator is the Kubernetes controller, part of pgAgroal Enterprise, that reconciles Pgagroal custom resources into hardened pooler deployments. You declare the pooler you want as a custom resource; the operator creates and maintains the underlying Kubernetes objects to match.
Control plane
The control plane is an optional pgAgroal Enterprise fleet service that manages poolers across clusters from one place. It is off by default and only needed when you operate poolers at fleet scale rather than in a single cluster.
CRD / custom resource
These are the standard Kubernetes terms. A CustomResourceDefinition (CRD) registers a new resource kind with the API server — here, Pgagroal. A custom resource is an instance of that kind: one Pgagroal object describes one pooler for the operator to reconcile.