Minimal PgBouncer image that is easy to configure
This is a minimal PgBouncer image, based on Alpine Linux.
Features:
psql,
pg_isready
/etc/pgbouncer/pgbouncer.iniand
/etc/pbbouncer/userlist.txtare auto-created if they don't exist.
PostgreSQL connections take up a lot of memory (about 10MB per connection). There is also a significant startup cost to establish a connection with TLS, hence web applications gain performance by using persistent connections.
By placing PgBouncer in between the web application and the actual PostgreSQL database, the memory and start-up costs are reduced. The web application can keep persistent connections to PgBouncer, while PgBouncer only keeps a few connections to the actual PostgreSQL server. It can reuse the same connection for multiple clients.
Base images:
latest(Dockerfile) - Default and latest version.
1.15.0(Dockerfile) - Latest version.
1.14.0(Dockerfile) - Latest version.
1.12.0(Dockerfile) - Latest version.
Images are automatically rebuild on Alpine Linux updates.
docker run --rm \ -e DATABASE_URL="postgres://user:[email protected]/database" \ -p 5432:5432 \ edoburu/pgbouncer
Or using separate variables:
docker run --rm \ -e DB_USER=user \ -e DB_PASSWORD=pass \ -e DB_HOST=postgres-host \ -e DB_NAME=database \ -p 5432:5432 \ edoburu/pgbouncer
Connecting should work as expected:
psql 'postgresql://user:[email protected]/dbname'
Almost all settings found in the pgbouncer.ini can be defined as environment variables, except a few that make little sense in a Docker environment (like port numbers, syslog and pid settings). See the entrypoint script for details. For example:
docker run --rm \ -e DATABASE_URL="postgres://user:[email protected]/database" \ -e POOL_MODE=session \ -e SERVER_RESET_QUERY="DISCARD ALL" \ -e MAX_CLIENT_CONN=100 \ -p 5432:5432 edoburu/pgbouncer
For example in Kubernetes, see the examples/kubernetes folder.
For example in Docker Compose, see the examples/docker-compose folder.
Make sure PostgreSQL at least accepts connections from the machine where PgBouncer runs! Update
listen_addressesin
postgresql.confand accept incoming connections from your IP range (e.g.
10.0.0.0/8) in
pg_hba.conf:
# TYPE DATABASE USER ADDRESS METHOD host all all 10.0.0.0/8 md5
When the default
pgbouncer.iniis not sufficient, or you'd like to let multiple users connect through a single PgBouncer instance, mount an updated configuration:
docker run --rm \ -e DB_USER=user \ -e DB_PASSWORD=pass \ -e DB_HOST=postgres-host \ -e DB_NAME=database \ -v pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro -p 5432:5432 edoburu/pgbouncer
Or extend the
Dockerfile:
FROM edoburu/pgbouncer:1.11.0 COPY pgbouncer.ini userlist.txt /etc/pgbouncer/
When the
pgbouncer.inifile exists, the startup script will not override it. An extra entry will be written to
userlist.txtwhen
DATABASE_URLcontains credentials, or
DB_USERand
DB_PASSWORDare defined.
The
userlist.txtfile uses the following format:
"username" "plaintext-password"
or:
"username" "md5"
Use examples/generate-userlist to generate this file:
examples/generate-userlist >> userlist.txt
You can also connect with a single user to PgBouncer, and from there retrieve the actual database password by setting
AUTH_USER. See the example from: https://www.cybertec-postgresql.com/en/pgbouncer-authentication-made-easy/
When an admin user is defined, and it has a password in the
userlist.txt, it can connect to the special
pgbouncerdatabase:
psql postgres://[email protected]/pgbouncer # outside container psql postgres://127.0.0.1/pgbouncer # inside container
Hence this requires a custom configuration, or a mount of a custom
userlist.txtin the docker file. Various admin console commands can be executed, for example:
SHOW STATS; SHOW SERVERS; SHOW CLIENTS; SHOW POOLS;
And it allows temporary disconnecting the backend database (e.g. for restarts) while the web applications keep a connection to PgBouncer:
PAUSE; RESUME;