Postgres Pgpool-II Ubuntu: Step-by-Step Configuration

Install Pgpool-II on Ubuntu with sudo apt install pgpool2, then point your application at port 9999 — not 5432. 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. A previous version of this page walked through installing that web panel behind an Apache block with allow from all and no authentication directive of any kind, over plain HTTP — an unauthenticated, internet-reachable control panel for your database cluster. That section has been deleted rather than repaired, and its instructions could not have worked in any case.

Why the pgpoolAdmin section is gone

Checked on 9 August 2026:

• The old article’s 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.)

The five settings the old guide omitted

The previous instructions covered listen_addresses, backend_hostname, backend_port and backend_weight, then declared the setup complete. 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 whichever default your package carries.

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 old article contradicted itself, suggesting journalctl -u pgpool2 in one troubleshooting entry and tail -f /var/log/pgpool/pgpool.log in another. 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, and PostgreSQL 17.10’s password_encryption boot value.

Not run here: Pgpool-II itself. 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. 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.

Check this yourself. Every command and every block of output on this page is reproduced by /verify/install-pgpool-ii-ubuntu.sh. Download it and run it: it creates its own scratch files, prints one line per claim, cleans up after itself, and exits non-zero if any claim here turns out to be wrong. If it disagrees with this page, the page is wrong.