PostgreSQL

PgBouncer Pool Size: Why the Rule of Thumb Is Too Small

Dr. Somya Hallan · Nov 20, 2026 · 28 min read
PgBouncer Pool Size: Why the Rule of Thumb Is Too Small

Tested by M. Aziz, November 2026 on PostgreSQL 18.7 and PgBouncer 1.26.1, AWS ap-south-1 · Tested by Mohammad Aziz, backend engineer at Selfhost.dev ·

The PostgreSQL wiki’s rule of thumb gives a 2 vCPU database about 4 active connections. In the Selfhost.dev PgBouncer pool-size test (Nov 2026), throughput peaked at 40.

PgBouncer lets thousands of clients share a few dozen Postgres server connections. Across 2, 4 and 8 vCPU, the best PgBouncer pool size for 500 clients was 40 to 80: far above the per-core formulas, far below the client count. Every command and output below comes from a dated run.

KEY FACTS

  • Pool size: in Selfhost.dev’s test, a 2 vCPU Postgres 18 instance with 500 clients peaked at 4,863 TPS with 40 server connections, and ran 13% slower at 160.
  • Starting point: Selfhost.dev’s measured starting point is about 20 server connections per vCPU, capped near 80, which fit every size tested. Per-core rules in guides and AI answers give 2 to 4 per vCPU.
  • Connection churn: with 500 clients opening a connection per transaction, direct Postgres served 192 TPS at 61% CPU. Through Selfhost.dev’s managed PgBouncer it served 313 TPS at 17% CPU.
  • Prepared statements: they work in PgBouncer transaction mode since 1.21 when max_prepared_statements is above 0, which is the default (200) since 1.24.0.
  • search_path: on Postgres 18 with PgBouncer 1.26.0 or later, SET search_path no longer leaks between clients. SET statement_timeout still does.
  • A 2 vCPU / 8 GB managed Postgres, the same size as the tested instance, costs $52.76 a month in Mumbai with PgBouncer included: see that setup priced, with nothing to fill in.

What is PgBouncer, and when do you need it

PgBouncer is a lightweight connection pooler that sits between your application and PostgreSQL and serves many client connections from a small pool of server connections. It usually listens on port 6432. In transaction mode, the default most people should use, a client holds a real server connection for one transaction and returns it at COMMIT.

app instances (hundreds or thousands of connections)
        │
        ▼
PgBouncer :6432   ── client side: cheap, thousands are fine
        │
        ▼
a few dozen server connections
        │
        ▼
Postgres :5432    ── one process per connection

Postgres starts an operating-system process for every connection, and each one costs memory even when idle. As traffic grows, connection limits are often what breaks first.

Signals that you need it:

  • Your app gets remaining connection slots are reserved for roles with the SUPERUSER attribute or sorry, too many clients already.
  • pg_stat_activity shows many idle connections. Selfhost.dev’s test measured about 1.7 MiB of RAM per idle direct connection (400 took the instance from 9.3% to 18.1% of 7.6 GiB).
  • Your app opens a connection per request (serverless, PHP, many Python setups), or autoscaled app servers each bring their own pool.

When you don’t need it: one long-running app server with a well-sized built-in pool (HikariCP, SQLAlchemy, pgx) under max_connections. At 50 clients, direct connections gave 4,325 TPS and PgBouncer 3,588.

How we tested

PartSetup
DatabaseSelfhost.dev managed PostgreSQL 18.7 on m7i.large (2 vCPU, 8 GB); sweeps also on m7i.xlarge (4 vCPU) and m7i.2xlarge (8 vCPU). 50 GB gp3, max_connections 512, 3 reserved for superusers
Managed poolerSelfhost.dev managed pooling: PgBouncer 1.26.1 on the database host, port 6432, scram-sha-256 logins only. Defaults: transaction mode, default_pool_size 20, reserve_pool_size 5, min_pool_size 0, max_client_conn 100 (raised to 1,100 here). Upstream PgBouncer defaults to session mode and no reserve pool
Self-run poolerPgBouncer 1.26.1 in Docker on its own 2 vCPU c7i.large, same settings unless a test says otherwise
Clientc7i.xlarge (4 vCPU, 4 pgbench threads) in the same zone; c7i.2xlarge (8 threads) for the 8 vCPU sweep, where it stayed 84% idle
Datapgbench -i -s 100, 1,503 MB
WorkloadsA: TPC-B read/write · B: pgbench -S read-only · C: pgbench -C, a new connection per transaction
Each run60 s; percentiles from a 20% sample of transaction logs; backends sampled each second

Each sweep point ran once for 60 seconds, and TLS was off on all test connections. Four of five repeated runs landed within 2%; one read-only run differed by half, so treat small differences between single runs as noise.

Postgres connection pooling vs direct connections, measured

Selfhost.dev’s managed PgBouncer kept every run working at 200 clients and more, while direct connections failed at 500, and it halved p95 latency at 200 clients. With a new connection per transaction, it raised throughput by about half and cut database CPU from about 60% to under 20%. With 50 long-lived clients, direct was slightly faster.

Table 1: Selfhost.dev PgBouncer pool-size test (Nov 2026), throughput and p95 latency, direct vs managed pooler, 2 vCPU

Workload · clientsDirect TPSDirect p95 msPooled TPSPooled p95 ms
A · 504,32522.53,58817.2
A · 2004,035106.83,74758.1
A · 500run failedn/a3,679162.1
B · 5032,6702.231,5122.1
B · 20032,68110.031,5327.0
B · 500run failedn/a31,29116.9
C · 50210280.4308172.3
C · 2002091,256.3325642.3
C · 5001924,660.63131,660.0

Table 2: Selfhost.dev PgBouncer pool-size test (Nov 2026), backends, host RAM and errors, same runs

Workload · clientsDirect backendsDirect RAMDirect errorsPooled backendsPooled RAMPooled errors
A · 506228.5%03429.5%0
A · 20023442.2%03530.8%0
A · 500n/an/ano slots3531.1%0
B · 5056n/m025n/m0
B · 200225n/m02531.3%0
B · 500n/an/ano slots2531.0%0
C · 505631.4%02531.0%0
C · 20021936.0%02531.3%0
C · 50050243.4%14 clients2531.3%0

“No slots”: Postgres refused connections and pgbench stopped; “14 clients”: clients pgbench dropped after a refusal. RAM: peak use of the 7.6 GiB host, from the console’s metrics; n/m = not measured. Backends include about ten monitoring and idle pooler connections.

Those 313 TPS came through a pooler that is a setting on the database, not a second server: see what managed Postgres with PgBouncer included gives you.

At C · 500, direct connections spent most of their 61% CPU starting processes and checking passwords. On reads, the extra hop cost little measurable throughput and bought lower p95 at 200 clients (7.0 vs 10.0 ms).

PgBouncer tuning: how big should the pool be

PgBouncer’s pool size should start from the database’s CPU and then be tested upward. On Selfhost.dev’s 2 vCPU instance, throughput climbed until 40 server connections, stayed flat at 80 and fell at 160. On 4 vCPU it peaked between 40 and 80, and on 8 vCPU at 80.

The Selfhost.dev pool-size sweep (Nov 2026)

500 clients, workload A, reserve_pool_size 0, one 60-second run per pool size. Managed pooler at 2, 4 and 8 vCPU; self-run pooler against the 2 and 8 vCPU databases.

PgBouncer pool size vs throughput at 500 clients on 2, 4 and 8 vCPU Postgres: throughput peaks at 40 to 80 server connections and falls at 160
Selfhost.dev PgBouncer pool-size test (Nov 2026): throughput at 500 clients by pool size, managed pooler. The larger dot on each line is its peak.

Table: Selfhost.dev PgBouncer pool-size sweep (Nov 2026), 2 vCPU database, managed and self-run pooler

Pool sizeManaged TPSp95 msDB CPUSelf-run TPSp95 mscl_waiting peak
51,537332.664%1,238419.8495
102,681196.178%2,454215.1490
203,723141.294%4,038131.3480
404,054130.799%4,863116.0460
804,072136.699%4,721121.4457
1603,750164.999%4,217158.4454

Table: Selfhost.dev PgBouncer pool-size sweep (Nov 2026), 4 vCPU database, managed pooler

Pool sizeManaged TPSp95 msDB CPU
51,896278.841%
103,348167.554%
204,739118.667%
406,250102.280%
806,303115.885%
1606,097126.788%

Table: Selfhost.dev PgBouncer pool-size sweep (Nov 2026), 8 vCPU database, managed and self-run pooler

Pool sizeManaged TPSp95 msDB CPUSelf-run TPSp95 ms
5971544.920%867599.7
102,432217.128%1,799288.0
204,513121.137%4,050138.8
406,73983.349%6,65797.7
807,302111.955%7,085127.5
1606,920140.853%7,038141.7

DB CPU: median host CPU from the console’s metrics. cl_waiting: from SHOW POOLS, self-run only.

On a 2 vCPU Postgres instance with 500 clients, Selfhost.dev’s test peaked at 40 server connections (4,863 TPS). At 160 connections throughput dropped 13% and p95 latency rose from 116 ms to 158 ms.

A pooler on its own server helped on the smallest database: 4,863 TPS against 4,072 for a pooler on the database host at 2 vCPU. On 8 vCPU the gap was gone (7,085 vs 7,302).

Why the rule of thumb is too small

The common pool-size formulas count CPU cores, and Selfhost.dev’s test found the best pool five to ten times larger. A connection in a transaction spends much of its time waiting on network round trips, write-ahead log (WAL) writes and row locks, not using CPU.

Common adviceWhat Selfhost.dev measured
The PostgreSQL wiki: about “((core_count * 2) + effective_spindle_count)” active connections, about 4 on 2 vCPUPeak at 40 on 2 vCPU. The wiki itself notes the formula hasn’t been analysed for SSDs
Guides and AI answers: 2 to 4 server connections per vCPU40 on 2 vCPU, which is 20 per vCPU
More cores need a bigger poolPeak throughput rose from 4,072 TPS (2 vCPU) to 6,303 (4) and 7,302 (8), but the best pool stayed at 40 to 80
More server connections, more throughputPast the peak, throughput fell and p95 rose (pool of 160)
AI answers: “map thousands of clients onto 32 to 50 server connections”Close for 2 vCPU (40); 80 won on 8 vCPU

A TPC-B transaction makes seven round trips, and in transaction mode it keeps its server connection through all of them, network waits included.

On 8 vCPU the database never passed 55% CPU. Sampled at pool 80, active sessions mostly waited on WAL writes (LWLock:WALWrite, 841 samples) and on row locks (Lock:transactionid, 453), because TPC-B updates the same 100 branch rows. Commits and locks set the limit there.

These results come from short read/write transactions with the app on a separate machine, which is how most web apps run. Long CPU-heavy queries were not tested.

The connection math: pools, max_client_conn and max_connections

PgBouncer has four numbers that interact, and Postgres has one more:

  • default_pool_size: server connections per pool. A pool is one user + database pair, so two apps with different users get two pools.
  • reserve_pool_size: extra connections after a client waits reserve_pool_timeout.
  • max_db_connections: a cap across all pools of one database.
  • max_client_conn: total clients PgBouncer accepts.
  • Postgres max_connections, minus superuser_reserved_connections (default 3) and reserved_connections.

Keep pools × (pool size + reserve) + direct connections ≤ max_connections − reserved slots. For two apps (web, worker) and a migration user connecting directly:

pools:      web (40 + 5 reserve) + worker (20 + 5 reserve)   =  70
direct:     migrations 2 + monitoring 5 + admin headroom 10  =  17
needed:                                                         87
available:  max_connections 512 − superuser_reserved 3       = 509   ✓

If you set max_db_connections, it caps the 70 even when every pool is busy. Worker fleets hit this first; n8n queue mode workers follow the same math.

reserve_pool_size and min_pool_size

A reserve pool did not cut tail latency in Selfhost.dev’s burst test: 50 steady clients, then 450 more for 20 seconds, pool 20. With the reserve at 0 and 5, steady clients’ p99 was 144 and 143 ms (managed), and 149 and 146 ms (self-run). On a database already at full CPU, five extra connections can’t help. min_pool_size was not measured.

A practical starting pool size

“I’d start at 20 server connections per vCPU and stop at 80. On a 2 vCPU instance that is 40, where our throughput peaked. Then I’d watch SHOW POOLS under real traffic. If cl_waiting stays above zero while the database has spare CPU, I’d raise the pool. If CPU is at 100% and p95 gets worse as I add connections, I’d lower it. The wiki formula says about 4. At a pool of 5, our database sat near 60% CPU while 495 clients waited, so I’d measure my own workload before trusting any formula.”
Mohammad Aziz, backend engineer, Selfhost.dev

PgBouncer on Selfhost.dev managed Postgres

Selfhost.dev runs managed PostgreSQL on AWS from $8.10/mo in ap-south-1 (Mumbai), with PgBouncer pooling included on port 6432 and no separate proxy to run or pay for. Pooling is a toggle with three modes, and the console marks transaction mode recommended.

What the test showed about it:

  • Connection churn: 313 TPS at 17% CPU with 500 clients opening a connection per transaction, against 192 TPS at 61% direct.
  • Prepared statements on by default: max_prepared_statements 200, and 1,000 psycopg prepared queries with no errors.
  • Current and patched: pools enabled or reconfigured from 19 November 2026 run PgBouncer 1.26.1 with scram-sha-256 logins.
  • Large instances: a 7,302 TPS peak on 8 vCPU, level with a pooler on its own server (7,085).

The console’s default pool of 20 suits the smallest instances, where a 1 GB database accepts 20 Postgres connections. On 8 GB and larger, the sweep says start near 40. You change it in the console, or from an AI editor through Selfhost.dev’s MCP server. Pooling is one of the features we line up in our managed PostgreSQL comparison.

A self-run PgBouncer exposes its full SHOW POOLS counters. Selfhost.dev’s console shows the pooler’s status, port and settings, and the Metrics page shows Postgres connection use, without waiting-client counts.

Teams that tune by cl_waiting can run their own PgBouncer, as in the Docker setup below. Selfhost.dev’s trade-off is a pooler you never install, patch or restart: PgBouncer 1.26.1 with scram-sha-256 on port 6432, included with the database.

Want to see where these settings live? The live demo console shows the pooling panel, default pool of 20 included, without creating an account.

PgBouncer transaction mode vs session vs statement mode

PgBouncer transaction mode is the right default unless something in your app needs a connection to stay its own between transactions. Session mode is the safe fallback for those clients. Statement mode is for special cases only, because it refuses multi-statement transactions.

ModeServer connection is releasedWhat worksWho should use it
sessionwhen the client disconnectseverything Postgres supportsmigrations, LISTEN, apps that rely on session state; gives you little pooling
transactionat COMMIT or ROLLBACKeverything inside a transaction; protocol-level prepared statements with max_prepared_statements > 0most web apps, workers and serverless functions
statementafter every statementsingle-statement autocommit only; multi-statement transactions are refusedrarely. Through our managed pooler (4 vCPU) it refused BEGIN with FATAL: transaction blocks not allowed in statement pooling mode, and single-statement reads were slower than in transaction mode (50,974 vs 61,436 TPS, one 30-second run each)

PgBouncer’s feature map lists what works in each mode. The next section shows what happens when you ignore it.

What PgBouncer transaction mode breaks: six things we reproduced

PgBouncer transaction mode breaks anything that expects session state to last between transactions. Selfhost.dev’s test broke six such features on purpose through PgBouncer 1.26.1, on the managed pooler and a self-run one, and both behaved the same. Forty background clients shared the pool, and a one-connection pool made leaks deterministic.

1. Session settings: some leak, some vanish

SET search_path stopped leaking in Selfhost.dev’s test, because Postgres 18 now reports search_path to clients like TimeZone. PgBouncer tracks it by default since 1.26.0.

A client that ran SET search_path kept it on its next statement, and 0 of 20 other clients saw it, even through a one-connection pool. You need both versions: on Postgres 17, or PgBouncer before 1.26.0, it still leaks.

Settings Postgres doesn’t report still break. Client A ran SET statement_timeout = '1234ms':

20 new clients ran SHOW statement_timeout: 1/20 saw 1234ms     (pool of 20, under load)
client A's own next statement sees statement_timeout = 0

through a one-connection pool:
20 new clients ran SHOW statement_timeout: 20/20 saw 1234ms

So the client that set it lost it, and a stranger got it.

Fix: use SET LOCAL inside the transaction; 0 of 20 clients then saw the value. Or set it per role with ALTER ROLE app SET statement_timeout = '5s', which 20 of 20 new connections picked up. Don’t rely on the connection string’s options=-c statement_timeout=…. Our managed pooler refused it (FATAL: unsupported startup parameter in options: statement_timeout). Our self-run one, which lists options in ignore_startup_parameters, dropped it without a word.

2. Prepared statements: mostly fine now, if the setting is on

Since PgBouncer 1.21, protocol-level prepared statements work in transaction mode once max_prepared_statements is above zero. That is what psycopg 3, pgx, asyncpg, JDBC and most ORMs use.

Since 1.24.0 the default is 200, and Selfhost.dev’s managed pooler uses that default: 20 psycopg clients ran 1,000 prepared queries through it with no errors. To see the failure we set it to 0 on the self-run pooler, using psycopg 3.1 with prepare_threshold=0 and pgbench in -M prepared mode:

self-run pooler, max_prepared_statements = 0
  psycopg: 20 clients x 50 executions: 102 succeeded, 18 clients failed
    prepared statement "_pg3_0" already exists
    prepared statement "_pg3_0" does not exist
  pgbench -M prepared: ERROR:  prepared statement "P_0" already exists

self-run pooler, max_prepared_statements = 200 (the default)
  psycopg: 1000 succeeded, 0 clients failed
  pgbench -M prepared: 53,848 TPS, no errors

SQL-level PREPARE and EXECUTE still fail, because PgBouncer doesn’t track them. PREPARE once, then EXECUTE 30 times: 29 failed with prepared statement "get_bal" does not exist. Fix: let your driver prepare statements at the protocol level, and check that max_prepared_statements isn’t 0 in your config.

3. LISTEN never hears anything

A listener behind PgBouncer missed the notifications in Selfhost.dev’s test. A client ran LISTEN blog_channel through the pooler and we sent five NOTIFY messages on a direct connection. It received 0 of 5 (1 of 5 through a one-connection pool, by luck of timing).

NOTIFY through the pooler itself worked without error. Fix: listeners connect directly to Postgres (port 5432) or through a session-mode pool.

4. Session advisory locks outlive the client

managed pooler, 40 background clients
client A: pg_advisory_lock(42)       -> ok, on backend pid 22753
client B: pg_try_advisory_lock(42)   -> false
client A: pg_advisory_unlock(42)     -> false, on backend pid 59954
  WARNING: you don't own a lock of type ExclusiveLock
after both clients disconnected, lock 42 is still held by:
  pid 22753, application_name 'pgbench', client 127.0.0.1

Client A’s unlock ran on a different server connection, so it couldn’t release its own lock. After both clients left, a pooled server connection still held it, labelled with the application_name of whoever used it last. That’s how a cron job ends up blocked by a lock nobody owns.

Through a one-connection pool, client B instead “acquired” the lock A already held, because they shared a session. Fix: pg_advisory_xact_lock() inside a transaction. It was held inside the transaction and released at COMMIT.

5. Temp tables disappear, or show up for someone else

One client ran CREATE TEMP TABLE tmp_report (x int) and then 30 inserts. 29 of 30 failed with relation "tmp_report" does not exist.

Through a one-connection pool every insert worked, and all 20 other clients could see the table. Fix: create it inside the transaction that uses it, with ON COMMIT DROP. That worked every time: create, fill 100 rows, read, dropped at COMMIT.

6. Migrations lose their safety settings

A migration’s SET lock_timeout vanished before its ALTER TABLE in Selfhost.dev’s test. We ran a typical migration file through the managed pooler with psql -f (autocommit) while 40 clients used the pool:

SET lock_timeout = '2s';
SHOW lock_timeout;                 -- returned 0 in 3 of 3 runs
ALTER TABLE pgbench_branches ADD COLUMN note text;
CREATE INDEX CONCURRENTLY pgbench_history_mtime_idx ON pgbench_history (mtime);

The lock_timeout was gone by the very next statement, so the ALTER TABLE ran with no timeout. A migration meant to give up after two seconds can instead queue behind a long transaction and block every query on that table.

pg_dump did work through the managed pooler, because it runs inside one transaction: the 10-million-row table dumped without errors. Fix: run migrations, dumps and long analytics jobs on a direct connection (port 5432) or a session-mode pool. For heavy, repeated analytics, it often pays to move heavy analytics off Postgres altogether.

That is why both ports are on every managed Postgres instance with pooling on: 5432 for migrations, dumps and LISTEN, and 6432 for the pool.

Common PgBouncer errors and what they mean

Most PgBouncer errors mean one of three things: too many clients, a pool too small for the load, or a restarting database. Selfhost.dev’s test caused each error below on purpose and recorded the exact message, its cause and the setting that fixes it.

FATAL: no more connections allowed (max_client_conn)

Managed pooler, 200 clients against our default of 100. Raise max_client_conn and the process’s open-file limit; PgBouncer logs both at startup (kernel file descriptor limit: 65536 ... max expected fd use: 2014).

FATAL: query_wait_timeout

Self-run pooler. A client waited longer than query_wait_timeout (default 120 s) for a server connection. With a one-connection pool, a 12-second query and a 5 s timeout, the second client gave up after 5.2 s as maxwait climbed.

FATAL: remaining connection slots are reserved for roles with the SUPERUSER attribute · FATAL: sorry, too many clients already

Direct to Postgres. The first means only superuser slots are left, the second that every slot is taken. With 1,000 churning clients, 189 got the first and 325 the second.

FATAL: server login has been failing, cached error: the database system is shutting down (server_login_retry)

During a Postgres restart. PgBouncer caches a failed server login for server_login_retry (default 15 s) and refuses new clients until it expires. Direct connections were back in 0.4 to 2.5 s. The self-run pooler, which didn’t attempt a login mid-shutdown, lost 0 to 1 queries. Lower server_login_retry to recover faster.

FATAL: SASL authentication failed · FATAL: no such user · server requested SASL authentication

Managed pooler (scram-sha-256 only): a wrong password, an unknown user, and a client that insists on md5 (libpq require_auth=md5), as old md5-only drivers do.

PgBouncer stats: reading SHOW POOLS and SHOW STATS

PgBouncer’s stats come from its admin console, a virtual database called pgbouncer on the pooler’s port. SHOW POOLS tells you whether the pool is too small, and SHOW STATS how long transactions wait for a server connection. Users listed in admin_users or stats_users can connect:

psql -h <pgbouncer-host> -p 6432 -U admin -d pgbouncer -c "SHOW POOLS"

This is from our self-run pooler during the sweep, with a pool of 20 and 500 clients (columns trimmed):

 database | user  | cl_active | cl_waiting | sv_active | sv_idle | maxwait_us | pool_mode
----------+-------+-----------+------------+-----------+---------+------------+-------------
 postgres | admin |        20 |        480 |        20 |       0 |     119592 | transaction
  • Pool too small: cl_waiting above zero and maxwait growing while database CPU has room. Here 480 clients each waited about 120 ms, almost all of their 123 ms median latency.
  • Pool too big: database CPU pinned, or latency rising as you add connections (our pool of 160).

SHOW STATS averages each counter over the last 60-second stats period. This is the self-run pooler after two minutes of steady load, 500 clients, 4 vCPU database:

 pool | avg_xact_count | avg_xact_time | avg_query_time | avg_wait_time
------+----------------+---------------+----------------+--------------
   20 |           4410 |        113205 |          16076 |        108671
   40 |           6598 |         75618 |          10703 |         69555

Times are in microseconds and include the wait for a server connection. Graph avg_xact_count (transactions per second), avg_wait_time, and avg_xact_time − avg_wait_time, the time a transaction really holds a connection: 4.5 ms at pool 20, 6.1 ms at 40. Doubling the pool cut the wait from 109 to 70 ms.

Little’s Law, which most sizing advice uses, fits these numbers. On the 4 vCPU database, 4,410 TPS × 4.5 ms per transaction means 20 connections busy at every instant, so Selfhost.dev’s pool of 20 was full. A pool of 40 served 6,598 TPS, 50% more.

The numbers to alert on

Three PgBouncer alerts, with thresholds from Selfhost.dev’s sweep:

  • cl_waiting > 0 for 5 minutes with database CPU under 70%. On 4 vCPU, pools of 5 to 20 ran at 41 to 67% CPU with about 480 clients waiting. That was 25 to 70% below peak throughput. Raise the pool.
  • maxwait above 1 s for 5 minutes. Our most starved run kept p95 under 0.6 s.
  • PgBouncer above 70% of one core. It’s single-threaded and used 74 to 76% at 55,000 to 74,000 reads a second. Add processes with so_reuseport.

PgBouncer Docker setup and configuration

A self-run PgBouncer needs a pinned image, a pgbouncer.ini, a user list and an open-file limit above max_client_conn. Ours ran in Docker on its own 2 vCPU server beside the database, on a private subnet whose firewall let only the benchmark client in.

edoburu/pgbouncer:v1.26.1-p0 is a community image of the official release. The PgBouncer project publishes source and links to distro packages, not a Docker image. Host networking keeps Docker’s NAT out of the path.

# docker-compose.yml
services:
  pgbouncer:
    image: edoburu/pgbouncer:v1.26.1-p0
    restart: unless-stopped
    network_mode: host
    ulimits:
      nofile: { soft: 65536, hard: 65536 }
    volumes:
      - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro
      - ./userlist.txt:/etc/pgbouncer/userlist.txt:ro
# pgbouncer.ini
[databases]
* = host=<postgres-host> port=5432

[pgbouncer]
; set the host's private address to reach it from app servers;
; never 0.0.0.0 on a public IP: the admin console shares this port
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
admin_users = admin
stats_users = admin
pool_mode = transaction
max_client_conn = 2000
default_pool_size = 20
reserve_pool_size = 5
reserve_pool_timeout = 5
max_prepared_statements = 200
query_wait_timeout = 120
server_lifetime = 3600
server_idle_timeout = 600
ignore_startup_parameters = extra_float_digits,options

userlist.txt holds "user" "secret" lines, where the secret is a SCRAM verifier or a plain password. For many users, set auth_user and auth_query so PgBouncer reads SCRAM secrets from Postgres. Keep port 6432 closed to the internet and allow only your app servers through the firewall.

Keep the image current. PgBouncer 1.26.1 fixed three CVEs, including an authentication bypass: a client who knew one SCRAM user’s password could log in as another, admins included.

PgBouncer vs Pgpool-II vs PgCat vs RDS Proxy vs Supavisor

PgBouncer only pools connections. Pgpool-II adds read/write splitting and failover, PgCat adds replica load balancing, RDS Proxy is AWS’s managed pooler and Supavisor is Supabase’s. Selfhost.dev tested only PgBouncer; this table comes from each project’s docs.

PgBouncerPgpool-IIPgCatRDS ProxySupavisor
Pool modessession, transaction, statementsession only: a per-process connection cache (no transaction pooling, per the maintainer in 2016)session, transactiontransaction-level reuse; pins the session when state changestransaction and session (per Supabase’s docs)
Read/write split, load balancingno split; round-robins new connections across a host listyes, reads and writes told apart automaticallyyes, reads balanced across replicas and primaryno split; Aurora clusters get read-only endpoints your app connects tonot yet (listed as future work)
Failoverno; it can’t skip an unreachable hostyes (high availability, watchdog)routes around broken replicas after health checksfollows a Multi-AZ failover to the new primarybuffers connections briefly through restarts and failovers; doesn’t run Postgres failover
Threadssingle-threaded (so_reuseport runs several processes)multi-processmulti-threaded (Rust)managed serviceElixir (BEAM)
Prepared statements, transaction modeprotocol-level, since 1.21n/a (session pooling)README: not supported (an undocumented cache setting exists)SQL PREPARE/EXECUTE pin the sessionnot supported (per Supabase’s docs)
Session state (SET, temp tables, advisory locks, LISTEN)breaks, as shown aboveworks (session pooling)breaks in transaction modepins the session instead of breaking (per AWS docs)dropped in transaction mode (per Supabase’s docs)
Where it runsanywhereanywhereanywhereAWS only, for RDS and Auroraanywhere; built for Supabase
Latest release (as of 18 Nov 2026)1.26.1, 14 Oct 20264.7.3, Sep 2026last tag v1.2.0, Aug 2024; last commit Feb 2025managed service2.10.1, 14 Nov 2026

Sources: PgBouncer · Pgpool-II + maintainer, 2016 · PgCat · RDS Proxy concepts, pinning, endpoints · Supavisor + Supabase docs. Release dates from each GitHub repository.

RDS Proxy is billed separately: see RDS Proxy’s per-vCPU-hour pricing ($0.015 per vCPU-hour, 2-vCPU minimum) and what it adds to an RDS bill. Supavisor comes with the Supabase stack, including when self-hosting Supabase.

When to pick another pooler

“If all I need is more connections, I use PgBouncer. It is small, it still ships releases, and this post shows how it fails. I haven’t run Pgpool-II, PgCat or RDS Proxy myself, so this part comes from their docs. To send reads to replicas without changing app code, I’d try Pgpool-II before PgCat. PgCat’s last release was in 2024, and its README says prepared statements don’t work in transaction mode. On RDS or Aurora, RDS Proxy is one less thing to run. It pins the session on any SET, so an app that sets values per connection gets little pooling from it.”
Mohammad Aziz, backend engineer, Selfhost.dev

PgBouncer production checklist

A production PgBouncer comes down to eight settings and habits, each taken from a test above. The first three size the pool and pick the mode. The next three stop session state from breaking, and the last two keep the pooler visible and patched.

  • Size default_pool_size from database CPU, then measure: 40 won at 500 clients on 2 vCPU.
  • Keep pools × (pool size + reserve) plus direct connections under max_connections minus reserved slots.
  • Default to transaction mode; give session mode only to clients that need it.
  • Keep max_prepared_statements above 0 for ORM prepared statements.
  • Use SET LOCAL or per-role settings, and pg_advisory_xact_lock.
  • Run migrations, dumps and LISTEN on a direct connection.
  • Set query_wait_timeout below your app’s timeout; alert on cl_waiting and maxwait.
  • Raise the open-file limit above max_client_conn, use scram-sha-256, and run 1.26.1 or later.

Should you run PgBouncer yourself or use managed pooling?

PgBouncer pays off with more than a couple of hundred clients, a connection per request, or connection errors as you scale. There it turned Selfhost.dev’s failed runs into working ones and cut database CPU from 61% to 17%. Whether to run it yourself depends on what you need to see and control.

  • Wait if one or two app servers with well-sized pools stay under max_connections, or your app relies on session state. Fix that code first.
  • Run your own PgBouncer if you tune from SHOW POOLS counters or need read/write splitting beside it.
  • Choose Selfhost.dev managed pooling if you want a patched PgBouncer without running one. It is a toggle on managed Postgres from $8.10/mo in Mumbai.

Turn on pooling for a new managed Postgres instance with the $5 welcome credit, no card needed, and set the pool near 40 on an 8 GB instance.

PgBouncer FAQ

What port does PgBouncer use?

PgBouncer uses port 6432 by convention, and both Selfhost.dev’s managed pooling and our self-run PgBouncer used it. Postgres stays on 5432, so apps switch to pooling by changing only the port. Keep 5432 reachable for migrations, dumps and LISTEN, which should not go through a transaction-mode pool.

How many connections can PgBouncer handle?

One self-run PgBouncer 1.26.1 held 1,000 clients at 4,578 TPS using 28% of one CPU core in Selfhost.dev’s test. It is single-threaded, so query rate matters more than client count: at 74,000 read queries a second it used 74% of a core. Past that, run several processes with so_reuseport.

What is the difference between PgBouncer and Pgpool-II?

PgBouncer is a lightweight connection pooler with transaction pooling. Pgpool-II pools connections per session and adds load balancing, read/write splitting and failover. If you only need more connections, PgBouncer is simpler; if you need replicas used automatically, Pgpool-II does more but has more to configure and run.

Do prepared statements work with PgBouncer transaction mode?

Yes, protocol-level prepared statements work in PgBouncer transaction mode since 1.21, when max_prepared_statements is above 0 (the default is 200 since 1.24.0). In Selfhost.dev’s test, 20 psycopg clients ran 1,000 prepared queries with no errors; with the setting at 0, 18 of 20 failed. SQL-level PREPARE still fails.

Does PgBouncer work with Postgres 19?

PostgreSQL 19 was released on 19 November 2026, and PgBouncer’s release notes up to 1.26.1 don’t mention it yet, so check them before you upgrade. Selfhost.dev tested on PostgreSQL 18.7. Postgres 19 warns on md5 logins, so use scram-sha-256 from client to pooler to database.

Keep reading: Managed PostgreSQL on Selfhost.dev · Compare managed Postgres providers on price and features · What every AWS RDS charge costs, RDS Proxy included · n8n queue mode, tested with 1, 2 and 4 workers

Run managed Postgres, your way.

Dedicated PostgreSQL on AWS with PITR, connection pooling, Multi-AZ, pgvector and BYOC. From $8.10/mo in Mumbai (ap-south-1), with no surprise invoices. Limited-time offer: get $5 in free credit at signup, no card needed.

cost check