pgAgroal Container
Practical guide to running pgagroal in Docker and Kubernetes.
Start here
If you are new to pgagroal, read these in order before deploying:
- Concepts — pipelines, what each preserves, and what breaks under transaction pooling
- Architecture — how the pool actually works between your application and PostgreSQL
- Configuration — environment variables, pool sizing, authentication
If you just want to run the container, follow the Quick start below.
Quick start
docker pull elevarq/pgagroal:1.0.0
docker run -d --name pgagroal \
-p 6432:6432 \
-e PG_BACKEND_HOST=your-postgres-host \
-e PG_BACKEND_PORT=5432 \
elevarq/pgagroal:1.0.0
psql -h localhost -p 6432 -U your_user -d your_dbReplace your-postgres-host with your PostgreSQL server and your_user / your_db with your credentials. The pooler listens on port 6432.
Verify the pool is healthy
docker exec pgagroal pgagroal-cli \
-c /etc/pgagroal/pgagroal.conf pingReturns exit code 0 if the pooler daemon is running. This is the same command used by the container's built-in health check.
Setup complete.
If psql returned a result and the ping exited with code 0, pgagroal is running and pooling connections. Your applications can now connect to port 6432 instead of 5432 — no other changes needed.
Docker Compose example
services:
postgres:
image: postgres:17.4-bookworm
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
POSTGRES_DB: appdb
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
interval: 5s
timeout: 3s
retries: 10
pgagroal:
image: elevarq/pgagroal:1.0.0
depends_on:
postgres:
condition: service_healthy
environment:
PG_BACKEND_HOST: postgres
PG_BACKEND_PORT: "5432"
MAX_CONNECTIONS: "100"
ports:
- "6432:6432"Applications connect to localhost:6432 instead of localhost:5432. Everything else stays the same.
Documentation
Read Understand first if you are new to pgagroal. Use Run it as operational reference.
Understand
Read these before writing config.
Choosing your connection path
Direct PostgreSQL vs pgagroal vs RDS Proxy. Latency, trade-offs, and when each makes sense.
Concepts
Pipelines, session vs transaction pooling, and what the choice means for application code.
Architecture
How pgagroal connects clients to backends. State, lifecycles, and pool internals.
Run it
Operational reference for deploying and running the container.
Configuration
Environment variables, connection pool sizing, timeouts, and authentication.
Performance and capacity
Pool sizing math, latency sources, and which workloads benefit from pooling.
Example: Docker Compose
Complete working stack with PostgreSQL and pgagroal. Copy, run, connect.
Example: Kubernetes
Minimal Deployment and Service manifests. Plain YAML, no Helm.
Kubernetes (Helm)
Helm chart, health probes, scaling, and production deployment patterns.
Observability
Logging, health checks, and monitoring pool behavior.
Security
Image verification, runtime hardening, and authentication modes.
Troubleshooting
Common mistakes, failure modes, and recovery patterns.