Open-source project
pgbouncer/pgbouncer avatar
pgbouncer/pgbouncer

PgBouncer in C: pooling PostgreSQL connections one process at a time

lightweight connection pooler for PostgreSQL

4,449 stars615 forksCNOASSERTION

At a glance

What is it?
PgBouncer is a lightweight connection pooler for PostgreSQL, written in C and built around an asynchronous event loop. Its value is narrow and well defined, and its cost is that it terminates and re-establishes the client protocol rather than passing traffic through.
Who is it for?
Adopt PgBouncer when your bottleneck is the number of PostgreSQL connections your application opens, and you can accept a pooler that rewrites the session. Do not adopt it as a load balancer or as transparent routing in front of a cluster.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 9 days ago.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pgbouncer/pgbouncer4,449 ★ · +77
Star history
Repository2026-09-232026-11-14
pgbouncer/pgbouncer4.4k4.4k

77 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem is connection count, not query latency

PgBouncer exists for one narrow reason: a PostgreSQL server spends a backend process on every open client connection, so an application fleet that opens and closes connections cheaply can exhaust server slots long before the CPU is busy. The README calls it a "Lightweight connection pooler for PostgreSQL" and nothing more. Read that literally. It is not a proxy that forwards packets, and it is not a cluster router. The word "lightweight" is doing real work here, since the source tree is a single C binary built from about two dozen files under `src/`.

The audience is whoever owns that server connection budget: an application team deploying a web framework with request-scoped database handles, or an operator who needs one port in front of a database that has a hard `max_connections`. What it is not for is anyone trying to spread reads and writes across replicas. The README contains no word about replication routing, no read/write split and no cluster membership, and none of that appears anywhere in the file layout either. Absence of evidence is worth something here, because a load balancing feature would be documented somewhere in `doc/` or `etc/`.

The documentation describes pooling, authentication types, DNS backends and build systems, and nothing about load balancing or replication routing.

Client and server sockets meet in an event loop, not in a proxy

The mechanism is visible in the source filenames rather than in prose. `src/pooler.c` holds the polling layer, `src/client.c` and `src/server.c` hold the two ends of a connection, and `src/proto.c` handles the wire protocol between them. `src/sbuf.c` is the buffered stream abstraction those three share, which is the signature of an event-driven design built on Libevent. Build dependencies confirm it: Libevent 2.0+ is required, not optional.

That structure matters for what the tool can and cannot do. A client speaks the PostgreSQL wire protocol to PgBouncer, and PgBouncer speaks it again to the server on a connection it picked from the pool. Anything that depends on the client's socket being the server's socket, such as source-IP-based access control on the PostgreSQL side or a `LISTEN`/`NOTIFY` channel that must survive indefinitely, does not fit this shape.

Protocol support is narrower than the name suggests. SCRAM lives in `src/scram.c`, with SASL preparation, HMAC, SHA-2 and Unicode normalisation pulled into `src/common/`. Prepared statements have their own file, `src/prepare.c`. Anyone moving an application from direct connections to a pooled path should assume feature gaps here and check the source rather than assume wire transparency.

Hostname lookup happens at connect time, so the resolver is a build decision

This is the detail a skim misses and the one most likely to cause a production incident. PgBouncer "does host name lookups at connect time instead of just once at configuration load time", which requires an asynchronous resolver. Four backends are supported, and they are not equivalent. c-ares does parallel lookups, supports EDNS0, reads `/etc/hosts` and performs SOA lookups. Libevent's evdns does parallel lookups and reads `/etc/hosts`, but does not support EDNS0 and, in the project's own words, "does not check /etc/hosts updates". The glibc and libc paths support EDNS0 but no SOA lookup, and the plain libc path is not parallel.

The consequences are concrete. EDNS0 is required to get more than eight addresses behind one host name. SOA lookup is what lets PgBouncer notice a zone serial change and re-resolve, so a failover DNS change may not be picked up. The fix for EDNS0 is a line in `/etc/resolv.conf`, not in PgBouncer's own configuration.

Backends are chosen at compile time. c-ares is used if found, forced with `-Dcares=enabled` or `--with-cares`, disabled with `-Dcares=disabled` or `--without-cares`, and Libevent's evdns can be turned off with `-Devdns=false` or `--disable-evdns`. You cannot change this in `config.ini`. Verify it at build time, then remember it.

Building it: Autoconf for production, Meson as the future default

There are two build systems and the README is unusually direct about which one to use. Autoconf is "the recommended choice for production builds and packaging for now", while Meson is described as "newer, still experimental" and is expected to become the default with Autoconf removed in a future release. Building from a source tarball with Autoconf needs three steps after the dependencies are in place:

bash
$ ./configure --prefix=/usr/local
$ make
$ make install

Everything lands under `/usr/local` unless the prefix says otherwise. Dependencies are Libevent 2.0+, pkg-config, a C11-capable compiler, and OpenSSL 1.0.1+ for TLS. c-ares, LDAP and PAM are optional.

Building from Git needs the generated files first, so `autogen.sh` comes before `./configure`, and it additionally requires autoconf, automake, libtool and pandoc:

bash
$ git clone https://github.com/pgbouncer/pgbouncer.git
$ cd pgbouncer
$ ./autogen.sh
$ ./configure

The Meson path runs `meson setup build`, then `meson compile -C build`, then `meson install -C build`, and needs Meson 0.58+ and Ninja. The optional features behave differently between the two builds, which is a genuine trap: Meson auto-detects PAM, LDAP and systemd because `-Dpam`, `-Dldap` and `-Dsystemd` default to `auto`, while the Autoconf build requires you to opt in with `--with-pam`, `--with-ldap` or `--with-systemd`. A binary built with Autoconf and no flags has no PAM and no LDAP.

Windows support is MinGW only, and two switches stop working

The Windows story is narrow enough to state precisely. "The only supported build environment on Windows is MinGW", and the README rules out Cygwin and Visual Studio builds by name. Cross-compiling from Unix works through a host triple:

bash
$ ./configure --host=i586-mingw32msvc

The LDAP build option is not supported on Windows at all, so a deployment plan that pairs LDAP authentication with Windows is already broken before configuration.

At runtime the limits are just as concrete. The `-d` switch that daemonizes and the `-u` switch that changes user do not work, which means process management on Windows must come from the service wrapper. Registering that service requires the `service_name` parameter to be set in the configuration file first:

bash
$ pgbouncer -regservice config.ini
$ pgbouncer -unregservice config.ini

Writing to the Windows event log needs `syslog = 1` in the configuration file, and registering `pgbevent.dll` with `regsvr32` beforehand. That is a separate step from service registration and the README treats them as independent.

Authentication methods decide which optional library you must build in

PgBouncer has its own `auth_type` settings and its own credential stores, which means an authentication method that the PostgreSQL build supports may still be missing from your PgBouncer binary. Two global authentication types exist only when compiled in: `pam`, available when the build has PAM support, and `ldap`, available when it has LDAP support. Neither is available in a binary built without the corresponding library.

This is where the project differs most sharply from simply pointing clients at PostgreSQL. PgBouncer validates the client itself, against its own user list or its own PAM or LDAP stack, before it decides which pooled server connection to hand out. Its `hba.c` and `ldapauth.c` files are the code that makes that split possible. Any migration plan that keeps a single credential store working through the pooler has to check which library is actually linked.

systemd integration is the third optional feature and the least surprising. It enables `Type=notify`, `Type=notify-reload` on systemd 253 or later, and socket activation, with worked examples checked into the repository as `etc/pgbouncer.service` and `etc/pgbouncer.socket`.

Against pgpool, PgBouncer moves the session boundary

The comparison people actually make is with pgpool-II, and the difference is architectural rather than a matter of speed. PgBouncer sits at the socket level only, terminating the client session and multiplexing many clients over a small number of server connections. Nothing in the README describes routing or load balancing.

The tradeoff follows directly. Because PgBouncer owns the client session, session-scoped state that assumes a persistent server socket is where implementations differ most, and that is the ground to test rather than argue about. Because it does not route, adding read replicas is outside its remit, and a deployment that needs both pooling and distribution needs two tools.

What PgBouncer does instead it does in a small C binary with a narrow dependency set, which makes it a much easier thing to compile, package and run under a process supervisor than an extension plus middleware combination. The repository shows the same discipline in testing: `pyproject.toml` exists purely to declare pytest, pytest-asyncio, pytest-timeout, pytest-xdist, psycopg and filelock for the pytest-based suite, with a 30 second timeout and an `md5` marker for tests that use MD5 and will fail in FIPS mode. Details on running it are in `test/README.md`.

The last push to the repository was on 2026-11-02, and the latest release is PgBouncer 1.26.1 ("Only startup once") from 2026-10-14, following 1.26.0 ("Ignore all previous search_path") on 2026-09-23 and 1.25.2 on 2026-05-08.

Editorial conclusion

Adopt PgBouncer when your bottleneck is the number of PostgreSQL connections your application opens, and you can accept a pooler that rewrites the session. Do not adopt it as a load balancer or as transparent routing in front of a cluster. Before anything else, verify the DNS backend your build actually compiled in, because c-ares and Libevent evdns differ on EDNS0 and on /etc/hosts updates, and that choice is baked in at build time.

Frequently asked questions

What is PgBouncer for?

It is a lightweight connection pooler for PostgreSQL, written in C and built around Libevent. It pools server connections so that many clients can share a small number of PostgreSQL backends.

how to install pgbouncer

From a release source tree, run ./configure --prefix=/usr/local, then make and make install. The Autoconf build is the recommended choice for production builds and packaging for now.

how to install pgbouncer in linux

The build needs Libevent 2.0+, pkg-config, a C11-capable compiler, and OpenSSL 1.0.1+ for TLS, with c-ares, LDAP and PAM optional. From Git you must run ./autogen.sh first, which additionally requires autoconf, automake, libtool and pandoc.

How do I install PgBouncer on Windows?

MinGW is the only supported Windows build environment, and Cygwin and Visual Studio builds are not supported. The LDAP build option is not supported on Windows either.

Official sources

  1. Issues
  2. pgbouncer/pgbouncer on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pgbouncer-pgbouncer.svg)](https://hysenlabs.com/projects/pgbouncer-pgbouncer)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pgbouncer-pgbouncer.svg)](https://hysenlabs.com/projects/pgbouncer-pgbouncer)

Was this useful?