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.1.0 — pgagroal 2.1.0 on debian:bookworm-slim, built for amd64 and arm64, and signed with Cosign. Open source.

Upgrading from 1.0.x? Read the 1.1.0 migration guide — pgagroal 2.1.0 changes the vault encryption format and management protocol, so operators must regenerate the master key and upgrade clients in lockstep.

Quick start

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

docker pull elevarq/pgagroal:1.1.0

docker run -d --name pgagroal \
  -p 6432:6432 \
  -e PG_BACKEND_HOST=your-postgres-host \
  -e PG_BACKEND_PORT=5432 \
  elevarq/pgagroal:1.1.0

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.