Skip to content

Operations

This page covers running the pooler day to day: how it is secured, the admin console, service management, logs, backups, updates and support.

Security model

  • Loopback by default. PgBouncer listens on 127.0.0.1:6432 until you change it.
  • TLS required. Clients must use TLS (client_tls_sslmode = require). Connections to your database also use TLS.
  • SCRAM-SHA-256. Clients authenticate with SCRAM-SHA-256 against the user list.
  • Per-instance secrets. The CA, server certificate, passwords, user list and configuration are created on first boot. The image contains none of them.
  • File permissions. /var/lib/pgbouncer and its tls and credentials directories are closed to the ubuntu user. Clients use the public CA copy in /usr/local/share/sushi/pgbouncer/ca.pem.
  • Service sandbox. The pgbouncer service runs as the pgbouncer user and can write only to /run/pgbouncer and /var/lib/pgbouncer.

A single instance is not highly available. If you need that for the pooler itself, plan for it in your own architecture.

Admin console

PgBouncer's admin console is the special pgbouncer database. Connect as the pgbouncer user with the admin password:

sudo bash -euo pipefail <<'PGBOUNCER_ADMIN'
PGPASSWORD=$(tr -d '\n' < /var/lib/pgbouncer/credentials/admin.password)
export PGPASSWORD
psql "host=127.0.0.1 port=6432 dbname=pgbouncer user=pgbouncer sslmode=verify-full sslrootcert=/usr/local/share/sushi/pgbouncer/ca.pem" \
  -c 'SHOW POOLS'
unset PGPASSWORD
PGBOUNCER_ADMIN

SHOW POOLS lists client and server connections per pool. See the PgBouncer usage guide for the other SHOW commands.

Manage the service

sudo systemctl status pgbouncer
sudo systemctl reload pgbouncer
sudo systemctl restart pgbouncer

The first-boot service, sushi-pgbouncer-firstboot, runs before pgbouncer on every boot and creates anything that is missing. It does not overwrite existing files.

Logs

PgBouncer logs connections and disconnections to the systemd journal and to syslog with the identity pgbouncer:

sudo journalctl -u pgbouncer -n 100 --no-pager

Backups

Back up /etc/pgbouncer/ and /var/lib/pgbouncer/ together. They hold the configuration, user list, passwords and TLS identity. Your data lives in your database; back that up there.

To move to a replacement instance, launch it, copy both directories with their ownership and permissions, then point clients at the new host. Practise the restore once before you depend on it.

Updates

  • Ubuntu packages, including OpenSSL and libevent, receive unattended security updates.
  • PgBouncer itself stays on 1.26.0. A new PgBouncer release comes as a new version of the image. Running instances are not migrated: launch the new version, copy your configuration as above and switch clients over.

Support

Software Sushi supports the packaging, first-boot setup and this documentation. Email info@softwaresushi.com with your PgBouncer version (pgbouncer --version), what you ran and the error. Never include passwords or private keys. Support coverage beyond installation questions requires a separate agreement. The PgBouncer project does not provide support for this image.