What is pgbouncer-multicore-limit?

pgbouncer-multicore-limit is a research project that reproduces and measures a specific performance limit in PgBouncer, the popular PostgreSQL connection pooler. PgBouncer normally runs as a single process, which caps it at using one CPU core no matter how powerful the server is. This repo tests what happens when you run several PgBouncer processes side by side, sharing the same pool of database connections, to see how much extra throughput that unlocks. You can run a smaller functional version of the experiment on your own laptop using Docker Compose, which needs Docker, Rust, the uv Python tool, and Terraform installed. A single command builds PostgreSQL, builds PgBouncer from source with checksum verification, builds a custom Rust load testing tool, and then runs a full local test sequence: it loads a fixed dataset, sends traffic through one PgBouncer process, then through four processes sharing a port, checks an exported data stream, and finally validates and files each run as accepted or rejected. The local run uses a small dataset so it is meant for checking the process works, not for drawing performance conclusions. The custom Rust load generator can simulate several kinds of traffic, including steady API requests, data exports, new connections, cancellations, and mixed workloads, and it records detailed timing statistics for each run, down to full latency histograms. The real measured results come from a matching setup on AWS, built and torn down with Terraform and Ansible, and none of that cloud infrastructure gets created until you explicitly run a specific setup command and approve the plan. In the completed AWS test, using 256 clients and a fixed total connection budget, going from one PgBouncer process to eight roughly quadrupled throughput, from about 45,000 to about 210,000 queries per second, while the response time got faster too. At that point PostgreSQL itself became the bottleneck rather than PgBouncer. A blog post linked from the README explains the full methodology and its limitations, and every run raw data, logs, and validation status are saved for inspection, whether the run passed or was rejected. The project includes commands to generate charts and summaries from all accepted results.