pgbouncer-pool-modes

Choosing the right PgBouncer pool mode depends on your stack's connection lifecycle. Transaction pooling suits most web frameworks like Django and FastAPI, while session pooling is needed for features relying on session-level state.

Prepared statements break with PgBouncer transaction pooling because session state is reset between transactions. You must disable server-side prepared statements or use session pooling to maintain statement persistence across pooled connections.

Running Django migrations behind PgBouncer requires a safe connectivity strategy. Bypass transaction pooling during migrations by connecting directly to Postgres or using a session-pooled admin connection to avoid locking conflicts.

Configure default_pool_size and max_client_conn to balance Postgres resource limits against client concurrency. Setting default_pool_size caps backend connections per database, while max_client_conn limits total incoming client connections to prevent overload.

Session pooling is preferable for Celery workers when tasks require persistent session state or server-side prepared statements. Transaction pooling works better for short, independent tasks to maximize connection reuse and throughput.

Statement pooling in PgBouncer limits multi-statement transactions and breaks session-level features. It only works when queries never rely on transaction boundaries, making it unsuitable for most Django and FastAPI application workloads.