Configure pgBouncer connection pooling for Postgres

Every Postgres connection consumes a server process and shared memory. At high connection counts — common in microservice architectures and serverless workloads — this overhead degrades query throughput and can exhaust server resources entirely. pgBouncer sits in front of PostgreSQL and multiplexes application connections onto a much smaller pool of real server connections, dramatically reducing overhead without changing your application’s connection string. PGO integrates pgBouncer natively. Add a single proxy.pgBouncer section to your PostgresCluster spec and the operator manages the Deployment, Service, TLS certificates, and user authentication automatically.

Enable pgBouncer

The minimal configuration is an empty pgBouncer object. This starts one pgBouncer pod in transaction pooling mode using PGO defaults.

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 16
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 10Gi
  backups:
    pgbackrest:
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 10Gi
  proxy:
    pgBouncer: {}

Once the cluster reconciles, verify the pgBouncer pod is running:

kubectl get pods -l postgres-operator.crunchydata.com/role=pgbouncer \
  -l postgres-operator.crunchydata.com/cluster=hippo

Configure pool size and mode

Use spec.proxy.pgBouncer.config.global to set any pgBouncer configuration parameter. Key settings include pool_mode, max_client_conn, and default_pool_size.

spec:
  proxy:
    pgBouncer:
      config:
        global:
          pool_mode: "transaction"
          max_client_conn: "1000"
          default_pool_size: "20"
          min_pool_size: "5"
          reserve_pool_size: "5"
          reserve_pool_timeout: "3"
          log_connections: "1"
          log_disconnections: "1"

Changes to config.global are reloaded automatically without restarting pgBouncer. However, invalid configuration values can put pgBouncer into an unusable state, so validate your settings before applying.

Scale pgBouncer replicas

For high-traffic clusters, run multiple pgBouncer pods behind the Kubernetes Service. Each pod maintains its own connection pools independently.

spec:
  proxy:
    pgBouncer:
      replicas: 3
      resources:
        requests:
          cpu: "100m"
          memory: "64Mi"
        limits:
          cpu: "500m"
          memory: "256Mi"

Database routing

By default, pgBouncer routes all connections through a wildcard (*) entry that targets the primary PostgreSQL instance. Use config.databases to define explicit routing rules with libpq-style connection strings.

spec:
  proxy:
    pgBouncer:
      config:
        databases:
          # Route the 'myapp' database to primary
          myapp: "host=hippo-primary port=5432 dbname=myapp"
          # Route 'myapp-ro' database to the replica service
          myapp-ro: "host=hippo-replicas port=5432 dbname=myapp"

Per-user settings

config.users lets you apply pgBouncer settings for specific database users, such as overriding the pool size or pool mode.

spec:
  proxy:
    pgBouncer:
      config:
        users:
          app: "pool_mode=transaction max_user_connections=50"
          admin: "pool_mode=session"

Expose pgBouncer externally

By default the pgBouncer Service is ClusterIP. Change spec.proxy.pgBouncer.service.type to expose it via a LoadBalancer or NodePort.

spec:
  proxy:
    pgBouncer:
      service:
        type: LoadBalancer

Retrieve the connection endpoint

Find the pgBouncer Service

kubectl get service -l postgres-operator.crunchydata.com/role=pgbouncer \
  -l postgres-operator.crunchydata.com/cluster=hippo

Get the pgBouncer connection secret

PGO writes pgBouncer connection details into the per-user secret alongside the direct Postgres connection string. The key pgbouncer-uri contains a connection URI pointing at the pgBouncer Service.

kubectl get secret hippo-pguser-hippo \
  -o jsonpath='{.data.pgbouncer-uri}' | base64 -d

Connect through pgBouncer

Use the pgbouncer-uri in your application. The URI points to the pgBouncer Service on port 5432 (the default), using the same credentials as the direct connection.

psql "$(kubectl get secret hippo-pguser-hippo \
  -o jsonpath='{.data.pgbouncer-uri}' | base64 -d)"

Direct Postgres vs. pgBouncer

Use the right endpoint for each workload type:

Workload	Recommended endpoint	Why
Short-lived application connections	pgBouncer (`pgbouncer-uri`)	Pools connections; reduces server process overhead
Long-running sessions, `LISTEN/NOTIFY`, advisory locks	Direct Postgres (`uri`)	Session-level features require a dedicated server connection
`COPY`, `PREPARE` statements	Direct Postgres or session mode pgBouncer	Transaction pooling disassociates the connection between statements
Admin / DBA work	Direct Postgres (`uri`)	Avoids pgBouncer’s query parsing overhead

pgBouncer in transaction pooling mode does not support SET statements that persist across transactions, server-side prepared statements (unless server_reset_query is configured), or LISTEN/NOTIFY. Use session pooling mode or a direct connection for these use cases.

Custom TLS for pgBouncer

To supply your own TLS certificate for the pgBouncer endpoint, reference a Secret projection containing tls.crt, tls.key, and ca.crt:

spec:
  proxy:
    pgBouncer:
      customTLSSecret:
        name: my-pgbouncer-tls
        items:
          - key: tls.crt
            path: tls.crt
          - key: tls.key
            path: tls.key
          - key: ca.crt
            path: ca.crt

Create a cluster

Configure instances, storage, and Postgres parameters.

High availability

Run multiple replicas with automatic failover via Patroni.

TLS

Manage certificates for encrypted Postgres and pgBouncer connections.

Custom Resource Reference

Full field reference for spec.proxy.pgBouncer.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Configure pgBouncer connection pooling for Postgres

Enable pgBouncer

Configure pool size and mode

Scale pgBouncer replicas

Database routing

Per-user settings

Expose pgBouncer externally

Retrieve the connection endpoint

Direct Postgres vs. pgBouncer

Custom TLS for pgBouncer

Create a cluster

High availability

TLS

Custom Resource Reference

​Enable pgBouncer

​Configure pool size and mode

​Scale pgBouncer replicas

​Database routing

​Per-user settings

​Expose pgBouncer externally

​Retrieve the connection endpoint

​Direct Postgres vs. pgBouncer

​Custom TLS for pgBouncer

Create a cluster

High availability

TLS

Custom Resource Reference

Enable pgBouncer

Configure pool size and mode

Scale pgBouncer replicas

Database routing

Per-user settings

Expose pgBouncer externally

Retrieve the connection endpoint

Direct Postgres vs. pgBouncer

Custom TLS for pgBouncer