Documentation

pgAgroal Container

A signed container image for pgagroal, the high-performance PostgreSQL connection pooler. Drop it in front of your database, point your applications at port 6432 instead of 5432, and pool connections with no application changes.

Image: elevarq/pgagroal:1.4.3 — pgagroal 2.1.0 on debian:bookworm-slim, built for amd64 and arm64, and signed with Cosign. Open source.

Upgrading from 1.3.x or earlier? Read the 1.4.0 migration guide — the 1.4 line keeps pgagroal 2.1.0 but changes authentication, HBA, network-policy, published-port, and Helm credential defaults.

Quick start

Pull the image, run it against your PostgreSQL host, and connect through the pool:

docker pull elevarq/pgagroal:1.4.3

docker run -d --name pgagroal \
  -p 127.0.0.1:6432:6432 \
  -e PG_BACKEND_HOST=your-postgres-host \
  -e PG_BACKEND_PORT=5432 \
  -e PG_USERNAME=your_user \
  -e PG_PASSWORD=your_password \
  elevarq/pgagroal:1.4.3

psql -h localhost -p 6432 -U your_user -d your_db

Replace your-postgres-host with your PostgreSQL server and your_user / your_db with your credentials. The pooler listens on port 6432. Confirm it's healthy with the same command its built-in health check uses (exit code 0 = pooler running):

docker exec pgagroal pgagroal-cli \
  -c /etc/pgagroal/pgagroal.conf ping

For the full Compose stack with PostgreSQL, see the Docker Compose tutorial.

The manual

This documentation is organised the way you actually use docs — pick the box that matches what you need right now.

Tutorial

Learn by doing

Guided deployments — from a running pool to a production Kubernetes setup.

How-to guides

Solve a specific task

Operational recipes for running, observing, and hardening the container.

Reference

Look up the facts

Every environment variable, plus the pool-sizing and capacity math.

Explanation

Understand the design

Why a pooler, what pooling preserves, and how pgagroal works inside.

New to connection pooling? Start with Choosing a connection path and Pooling concepts before you deploy.