Example deployment: Docker Compose
A complete working stack you can copy and run in under a minute.
This example runs PostgreSQL and pgagroal together as a local service. It is the fastest way to evaluate pgagroal with a real database, and the same structure works in staging and small production environments.
Docker network: backend
Client
:6432
pgagroal:5432
postgrespgdata volume
docker-compose.yml
services:
postgres:
image: postgres:17.4-bookworm
restart: unless-stopped
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: changeme
POSTGRES_DB: appdb
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
interval: 5s
timeout: 3s
retries: 10
networks:
- backend
pgagroal:
image: elevarq/pgagroal:1.0.0
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
environment:
PG_BACKEND_HOST: postgres
PG_BACKEND_PORT: "5432"
MAX_CONNECTIONS: "50"
PGAGROAL_LOG_LEVEL: warn
ports:
- "6432:6432"
networks:
- backend
volumes:
pgdata:
networks:
backend:Start
docker compose up -dPostgreSQL starts first. pgagroal waits for the health check to pass before starting. This typically takes 5-10 seconds.
Verify
# Connect through pgagroal
PGPASSWORD=changeme psql -h localhost -p 6432 -U app -d appdb -c 'SELECT 1'
# Check pool health
docker exec pgagroal-pgagroal-1 pgagroal-cli \
-c /etc/pgagroal/pgagroal.conf pingIf the query returns 1 and the ping exits with code 0, the stack is working. Applications connect to localhost:6432 instead of localhost:5432.
What this gives you
- --PostgreSQL 17.4 with persistent storage (survives restarts)
- --pgagroal connection pooler with 50 backend connections
- --Health check on PostgreSQL — pgagroal only starts when the database is ready
- --Automatic restart on failure for both services
- --Isolated network — PostgreSQL is not exposed to the host, only pgagroal is
Common adjustments
| Change | How |
|---|---|
| Database password | Change POSTGRES_PASSWORD and update your connection string |
| Database name | Change POSTGRES_DB |
| Pool size | Change MAX_CONNECTIONS (default 50 in this example) |
| Expose PostgreSQL directly | Add ports: ["5432:5432"] to the postgres service |
| Change pgagroal port | Change the host port in ports (e.g. "6433:6432") |
| Use an external database | Remove the postgres service and set PG_BACKEND_HOST to your database hostname |
Stop and clean up
# Stop services (data persists)
docker compose down
# Stop and remove all data
docker compose down -vSee also: Configuration for all environment variables, or Kubernetes for Helm-based deployment.