Since PgBouncer runs as a single process, it is not straightforward to make use of multiple CPUs on a host. When you are running on real hardware, this is wasteful, since single-CPU server machines don’t exist anymore, as far as I can tell. When using virtualization, you could just provision a single CPU per virtual host and run multiple virtual hosts with a single PgBouncer instance each. But there are also ways to run multiple instances of PgBouncer on a single host, so let’s explore that. Since version 1.12, PgBouncer supports the SO_REUSEPORT socket option, which allows running multiple instances of PgBouncer on the same host on the same port and they will share the connections.
First, let’s set up the basics of how to run a single instance of PgBouncer via systemd. PgBouncer ships with a sample service unit configuration file at etc/pgbouncer.service in the source tree that you can use to get started. Copy that file to /etc/systemd/system/pgbouncer.service and run sudo systemctl daemon-reload . Then you can run sudo systemctl start pgbouncer .
This is the unit file I’m using for this example. It is a slightly adjusted and abbreviated version of the file in the source tree.
[Unit] Description=connection pooler for PostgreSQL After=network.target [Service] Type=notify User=postgres ExecStart=/usr/local/bin/pgbouncer /etc/pgbouncer/pgbouncer.ini ExecReload=/bin/kill -HUP $MAINPID KillSignal=SIGINT [Install] WantedBy=multi-user.target
And this is the PgBouncer configuration file I’m using:
[databases] ;; add yours here [pgbouncer] listen_addr = localhost listen_port = 6432 unix_socket_dir = /tmp so_reuseport = 1
Now if you want to run multiple instances, you can obviously just make copies of these files and run them as entirely separate services. But here we want to make use of the systemd template system. So create a file /etc/systemd/system/pgbouncer@.service that looks like this:
[Unit] Description=connection pooler for PostgreSQL (%i) After=network.target [Service] Type=notify User=postgres ExecStart=/usr/local/bin/pgbouncer /etc/pgbouncer/pgbouncer.ini ExecReload=/bin/kill -HUP $MAINPID KillSignal=SIGINT [Install] WantedBy=multi-user.target
(Remember to daemon-reload at appropriate times. I’m not going to repeat that every time.)
Then use
systemctl start pgbouncer@1 systemctl start pgbouncer@2 # etc.
and you can start as many as you want. The specific numbers here are irrelevant, they just serve as identifiers. (They don’t even have to be numbers.)
The problem with that setup is that while the TCP/IP listen sockets will happily share between all instances, per the so_reuseport setting, this does not apply to the Unix-domain sockets. So you would either have to turn off Unix-domain sockets, or create separate configuration files for each instance with different directories for the Unix-domain sockets, which would remove some of the elegance of this approach.
I recommend a new approach using socket activation, which is supported as of PgBouncer 1.14.
Create a file /etc/systemd/system/pgbouncer@.socket :
[Unit] Description=sockets for PgBouncer [Socket] ListenStream=6432 ListenStream=%i ListenStream=/tmp/.s.PGSQL.%i ReusePort=true [Install] WantedBy=sockets.target
This gives us:
- A TCP/IP socket on port 6432 for normal use. (You could also use 5432.)
- Per-instance TCP/IP and Unix-domain sockets, for administration and monitoring.
The ReusePort setting corresponds to the so_reuseport setting in pgbouncer.ini. (When you use systemd socket activation, the listen socket settings in pgbouncer.ini are ignored.)
Then change pgbouncer@.service like this:
[Unit] Description=connection pooler for PostgreSQL (%i) After=network.target Requires=pgbouncer@%i.socket [Service] Type=notify User=postgres ExecStart=/usr/local/bin/pgbouncer /etc/pgbouncer/pgbouncer.ini ExecReload=/bin/kill -HUP $MAINPID KillSignal=SIGINT [Install] WantedBy=multi-user.target
and then you can start
systemctl start pgbouncer@50001 systemctl start pgbouncer@50002 systemctl start pgbouncer@50003 systemctl start pgbouncer@50004
or
systemctl enable pgbouncer@50001 # etc.
to enable them for system start.
Here, the 50001+ numbers are the administration port numbers. You can use any numbers you want that are not used by anything else.
Now, for production traffic, you can connect like this as normal:
psql -h somehost -p 6432 -d yourdb ...
(must be TCP/IP). For monitoring and administration, you connect to each instance like this:
psql -p 50001 -d pgbouncer -U pgbouncer -c 'SHOW ...'
As alluded to at the beginning, there are many ways to set up and deploy PgBouncer. It depends on available hardware, deployment tools, and architecture requirements. If you have other ideas, please leave a comment or join the discussion on Gitter.