ClickHouse Scales PgBouncer to 4× Throughput With Linux Kernel Primitive

The ClickHouse engineering team ran a fleet of PgBouncer processes sharing a single port via SO_REUSEPORT, with peering to handle cancel requests — achieving 4× throughput on the same hardware.

PgBouncer, the de facto connection pooler for PostgreSQL, has a well-known limitation: it is single-threaded. No matter how many CPU cores a server has, a single PgBouncer process tops out at one core. On a 16-vCPU box, that leaves fifteen cores idle while the pooler becomes the bottleneck.

ClickHouse's managed Postgres team ran a fleet of PgBouncer processes — one per core — all bound to the same port using Linux's SO_REUSEPORT socket option. The kernel load-balances incoming connections across the fleet, so clients connect to a single endpoint and never know there is more than one PgBouncer behind it.

The challenge: Postgres cancel requests arrive on fresh connections carrying a cancel key. With SO_REUSEPORT, the kernel can route that cancellation to a process that has never seen the query, and nothing happens. ClickHouse solved this with "peering" — all processes in the fleet are aware of each other, and a cancel that lands on the wrong process gets forwarded to the one that actually owns the session.

Benchmarks on identical AWS c7i.4xlarge instances with pgbench in transaction mode: a single PgBouncer process peaked at roughly 87,000 transactions per second before degrading under load. The 16-process fleet reached approximately 336,000 transactions per second — a 4× improvement. CPU utilization: the single process pinned one core at 97% while the box idled below 10% overall; the fleet spread across roughly 8 cores, reaching 52–60% utilization with headroom to spare.

Connection budgets are divided across fleet members — max_client_conn and max_db_connections are split by process count — so the fleet never oversubscribes Postgres. Every ClickHouse Managed Postgres instance now ships with this setup by default.

Commenters on Hacker News surfaced alternatives, including Yandex's Odyssey (a multi-threaded PgBouncer-compatible pooler), PgDog (a Rust-based pooler with sharding), and running multiple PgBouncer instances behind HAProxy in Kubernetes. Several noted that SO_REUSEPORT and peering eliminate the need for an external load balancer entirely, reducing operational complexity.

The broader takeaway: a 20-year-old piece of infrastructure software, running unchanged, can scale across modern multi-core hardware with the right OS primitives and a small amount of coordination logic — no rewrite required.

Sources: ClickHouse Engineering Blog, Hacker News Discussion