Install Pgpool-II on Ubuntu 24.04: Skip the Stale Repo

Updated

Installing Pgpool-II on Ubuntu

Install Pgpool-II on Ubuntu with sudo apt install pgpool2, then point your application at port 9999 — not 5432. One thing it doesn’t tell you: on Ubuntu 24.04 that’s a two-year-old release (see below). If you only need connection pooling — not load balancing or automatic failover — PgBouncer is the simpler tool; here’s what happened when I ran both against the same cluster. Manage the cluster from the command line with the PCP tools and SHOW POOL_NODES:

sudo apt update && sudo apt install pgpool2
psql -h 127.0.0.1 -p 9999 -U youruser -c "SHOW POOL_NODES;"
pcp_node_info -h 127.0.0.1 -p 9898 -U pcpuser -a

Do not install pgpoolAdmin. Setting that web panel up behind an Apache block with allow from all and no authentication directive of any kind, over plain HTTP, gives you an unauthenticated, internet-reachable control panel for your database cluster.

Why pgpoolAdmin is not an option

Checked on 9 August 2026:

  • The download command wget http://www.pgpool.net/download.php?f=pgpoolAdmin-3.10.1.tar.gz returns HTTP 404 — a 9,379-byte HTML error page. The next step, tar -xf, fails with tar: Error opening archive: Unrecognized archive format (exit 1). pgpoolAdmin-3.10.1 appears never to have existed: the tags jump from V3_7_1 to V4_0_0.
  • The source repository (github.com/pgpool/pgpooladmin, official mirror of the postgresql.org git repo) was last pushed on 2021-06-17, and its highest tag is V4_2_0 — no commits in five years, and no release compatible with any supported Pgpool-II.
  • pgpoolAdmin no longer appears on the pgpool.net downloads page at all.

The Pgpool Global Development Group declared pgpoolAdmin end-of-life in an announcement dated 17 February 2023: maintenance for 4.0, 4.1 and 4.2 ended 31 December 2023, after which “bug fixes and security fixes for these versions will no longer be provided”, and “pgpoolAdmin for Pgpool-II 4.3 or later will not be released”. There is no successor web UI. Current Pgpool-II is 4.7.2, so pgpoolAdmin cannot be used with any supported release. (The notice was removed in pgpool.net’s site redesign; it survives in the archived wiki.)

Ubuntu’s own repo ships an old Pgpool-II — here’s how to get current

sudo apt install pgpool2 works, but “works” and “current” aren’t the same thing. Ubuntu 24.04’s package is 4.3.7-1ubuntu4 (in universe) — four minor lines behind current 4.7.2. Ubuntu 26.04, the current LTS, ships 4.7.0-1 — two patches behind. Neither is current.

The fix is the PGDG repository — its setup changed too: apt-key add is deprecated, replaced by PostgreSQL’s own script for the modern DEB822 format. Not run here — no Ubuntu/container host; quoted from the docs, not executed:

sudo apt install -y postgresql-common ca-certificates
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt update
sudo apt install pgpool2

That writes a DEB822 pgdg.sources file with an inline key reference, not the single-line deb ... entry plus piped apt-key add that older guides (pgpool.net’s own apt page included) still show.

Five settings to configure

Setting listen_addresses, backend_hostname, backend_port and backend_weight is not enough on its own. Omitting any of the following produces a cluster that starts cleanly and then misbehaves silently.

1. pcp.conf is mandatory

The docs are unambiguous: “All operation modes require the pcp.conf file to be set.” Without it you have no administrative interface — no pcp_node_info, no pcp_attach_node, no way to bring a recovered node back.

sudo cp /etc/pgpool2/pcp.conf.sample /etc/pgpool2/pcp.conf
pg_md5 your_pcp_password        # then add  pcpuser:<hash>  to pcp.conf

2. health_check_period defaults to 0, which means failover does not work

Per the docs: “Default is 0, which means health check is disabled.” Until you set it, Pgpool-II never notices a dead backend and the automatic failover you installed it for never fires:

health_check_period = 10
health_check_timeout = 20
health_check_user = 'pgpool_check'
health_check_password = 'secret'

3. sr_check_user / sr_check_password identify the primary

Both default to empty. The docs note they “are used even when sr_check_period is set to 0 (disabled) for the identification of the primary server” — leave them blank and Pgpool-II cannot reliably tell which node is primary, so write routing and load balancing go wrong. The user must have LOGIN and be a superuser or in pg_monitor:

GRANT pg_monitor TO sr_check_user;

4. pool_passwd, because PostgreSQL defaults to scram-sha-256

Modern PostgreSQL ships password_encryption = scram-sha-256 as its compiled-in default — confirmed on PostgreSQL 17.10, whose pg_settings.boot_val reads scram-sha-256. Pgpool-II never sees the server’s stored password, so per the docs “SCRAM authentication is supported using the pool_passwd authentication file”. Without a populated pool_passwd, authentication through Pgpool-II fails. Entries must be plain text or AES (via pg_enc): “md5 type user passwords in pool_passwd file can’t be used for scram authentication”.

5. Port 9999 and listen_addresses

port defaults to 9999 and listen_addresses to localhost — “which allows only local TCP/IP loopback connections”. Clients still pointing at 5432 bypass Pgpool-II and talk straight to a backend, which is easy to miss because everything works until failover.

One version-dependent trap: load_balance_mode has defaulted to on only since 4.3. The 4.2 docs say “Default is off”; the 4.3 docs say “Default is on”. Set it explicitly rather than inheriting your package’s default — Ubuntu 24.04’s 4.3.7 sits right on that boundary.

Managing Pgpool-II without a web panel

Everything pgpoolAdmin did is available from SQL and the shell. Connected on 9999, SHOW POOL_NODES; lists every backend with its status, role, weight, SELECT counts and replication delay. The PCP tools handle administration — pcp_node_info, pcp_detach_node and pcp_attach_node to pull a node out of rotation and bring it back, pcp_watchdog_info for watchdog state. They authenticate against pcp.conf on port 9898 and read credentials from ~/.pcppass.

For the same data inside SQL, install the pgpool_adm extension on your PostgreSQL servers (CREATE EXTENSION pgpool_adm;). It exposes the PCP commands as SQL functions via a foreign data wrapper — the supported way to build your own UI.

Where the logs actually are

Use journalctl, not a file path:

sudo journalctl -u pgpool2 -n 100 --no-pager

The journal is correct for the Debian/Ubuntu package: its systemd unit runs /usr/sbin/pgpool -n with StandardOutput=syslog and SyslogFacility=local0. Pgpool-II’s defaults agree — log_destination defaults to stderr, and log_directory (when logging_collector is on) to /tmp/pgpool_logs. /var/log/pgpool/pgpool.log is not a default anywhere.

What was verified, and what was not

Directly checked: the dead download URL and its HTTP status, the tar failure, the repository’s last-push date and tags via the GitHub API, pgpoolAdmin’s absence from the downloads page, the differing load_balance_mode defaults in the 4.2 and 4.3 docs, the Debian pgpool2.service unit, PostgreSQL 17.10’s password_encryption boot value, the exact Ubuntu 24.04/26.04 package versions (fetched from packages.ubuntu.com and Launchpad), and that PostgreSQL’s current apt docs use DEB822/Signed-By, not apt-key.

Not run here: Pgpool-II itself, on any Ubuntu version. This machine is macOS with no Linux host and no container runtime, so no apt install, failover test or PCP session was executed — the configuration guidance is quoted from the official 4.7.2 documentation, not reproduced on a live cluster, and the PGDG setup above is quoted from postgresql.org, not run. Test failover in staging before relying on it; a health check that is configured but never exercised is not meaningfully different from one that is disabled.

Photo of author
Sudhir P. founded HeatWare.com in 1999 and has built and operated it full-stack ever since; it is now used by more than 88,000 people. He writes here about the PostgreSQL, MySQL, Linux and DevOps work that keeps it running. Articles are rewritten only after the commands in them have actually been run, and the verification scripts are published alongside them so anyone can check the claims. Reach him at blog@heatware.net.