2025 年 12 月 23 日、Pgpool-II の新しいメジャーバージョン 4.7 がリリースされました。
Pgpool-II 4.7 では、クライアント情報表示機能や、Watchdog と heartbeat receiver のセキュリティ強化、オンラインリカバリの機能が強化されました。また、フロントエンド/バックエンドプロトコルバージョン 3.2 サポートの追加、PostgreSQL 18 への対応も行われました。
Pgpool-II 4.7 の新機能及び変更点は Pgpool-II 公式ドキュメントの以下のページに記載されています。
本記事では、これらの新機能について詳しく紹介します。
クライアント情報を表示するための pcp_proc_info, show pool_pools の機能強化
4.6 までは Pgpool-II 経由で PostgreSQL に接続した場合、PostgreSQL 側からは各クライアントの接続情報を確認することができず、Pgpool-II のネットワークアドレスとポート番号のみしかわかりませんでした。
そのため障害が起きてもどのクライアント接続で障害が発生しているのかを調査することが困難でした。
4.7 からは pcp_proc_info, show pool_pools コマンドで Pgpool-II 経由で接続しているクライアントのホスト名、ポート番号、最後に実行した SQL を参照できるようになりました。
Pgpool-II の子プロセス情報を表示する pcp_proc_info コマンドでは client_host(ホスト名), client_port(ポート番号), statement(最後に実行した SQL) が追加されました。
これにより PostgreSQL からでも Pgpool-II 経由で接続しているクライアントの接続情報や最後に実行したクエリ情報を参照できるようになり障害時などに障害が起きているクライアント接続を調査することが容易になりました。
sraoss@server1:~/setuptest$ pcp_proc_info -p 50001 --verbose Database : test Username : sraoss Start time : 2026-01-08 12:15:18 (0:15 before process restarting) Client connection count : 1 Major : 3 Minor : 0 Backend connection time : 2026-01-08 12:15:18 Client connection time : 2026-01-08 12:15:18 Client idle duration : 0 Client disconnection time : 2026-01-08 12:16:38 Pool Counter : 1 Backend PID : 20250 Connected : 0 PID : 20195 Backend ID : 0 Status : Wait for connection Load balance node : 0 client_host : 127.0.0.1 client_port : 54726 statement : SELECT 1;
Pgpool-II のコネクションプールの状態を表示する show pool_pools コマンドにも、client_host(ホスト名), client_port(ポート番号), statement(最後に実行した SQL) が追加されました。
これらの変更で子プロセスやコネクションプーリングの情報とあわせてクライアント情報を参照できるようになりました。
test=# show pool_pools; pool_pid | start_time | client_connection_count | pool_id | backend_id | database | username | backend_connection_time | client_connection_time | client_disconnection_time | client_idle_duration | majorversion | minorversion | pool_counter | pool_backendpid | pool_connected | status | load_balance_node | client_host | client_port | statement ----------+------------------------------------------------------+-------------------------+---------+------------+----------+----------+-------------------------+------------------------+---------------------------+----------------------+--------------+--------------+--------------+-----------------+----------------+---------------------+-------------------+---------------+-------------+------------- [snip] 1336537 | 2025-06-24 10:53:35 | 0 | 0 | 0 | test | sraoss | 2025-06-24 10:55:58 | 2025-06-24 10:55:59 | | 0 | 3 | 0 | 1 | 1336703 | 1 | Idle | 0 | 192.168.10.11 | 39216 | 1336537 | 2025-06-24 10:53:35 | 0 | 0 | 1 | test | sraoss | 2025-06-24 10:55:58 | 2025-06-24 10:55:59 | | 0 | 3 | 0 | 1 | 1336704 | 1 | Idle | 1 | 192.168.10.11 | 39216 | select 1; 1336537 | 2025-06-24 10:53:35 | 0 | 1 | 0 | | | | | | 0 | 0 | 0 | 0 | 0 | 0 | Idle | 0 | 192.168.10.11 | 39216 | 1336537 | 2025-06-24 10:53:35 | 0 | 1 | 1 | | | | | | 0 | 0 | 0 | 0 | 0 | 0 | Idle | 0 | 192.168.10.11 | 39216 | select 1;
pgpool_adm_pcp_proc_info 関数の追加
pgpool_adm エクステンションに、Pgpool-II の子プロセスの情報を表示する pgool_adm_pcp_proc_info 関数が追加されました。 pgpool_adm エクステンションは Pgpool-II 経由でも、あるいは直接 PostgreSQL から呼び出せる関数群です。
pgool_adm_pcp_proc_info で表示される情報は pcp_proc_info コマンドと同様ですが、pgpool_adm エクステンションの関数であるため 、PostgreSQL クライアントからでも呼び出せます。
pgpool_adm を使うメリットは、SQLが使用でき WHERE 句で条件を指定して表示内容を絞り込むことができることです。(pcp コマンドの場合は、出力結果を整形するために OS のコマンドを併用する必要があります。)
導入には以下コマンドで各サーバーで pgpool_adm をインストールしてください。
# 各サーバーで以下を実行してインストール $ psql test test=# CREATE EXTENSION pgpool_adm;
その後 Pgpool-II や PostgreSQL のクライアント上で pgpool_adm_pcp_proc_info を実行します。
connected 列は接続状況を表示(0=接続なし, 1=接続中) しており、今回の例のように WHERE 句に “connected = 1” を指定することで接続中の情報に絞ることもできます。
test=# select * from pcp_proc_info(host => '', port => 11001, username => 'sraoss', password => 'sraoss') where connected = '1'; -[ RECORD 1 ]-------------+---------------------------------------------------------------------------------------------------------------------------- database | test username | sraoss start_time | 2026-01-08 10:56:08 client_connection_count | 0 major | 3 minor | 0 backend_connection_time | 2026-01-08 10:58:37 client_connection_time | 2026-01-08 10:58:37 client_idle_duration | 0 client_disconnection_time | pool_counter | 1 backend_pid | 14750 connected | 1 pid | 14585 backend_id | 0 status | Execute command load_balance_node | 1 client_host | 127.0.0.1 client_port | 59120 statement | select * from pcp_proc_info(host => '', port => 11001, username => 'sraoss', password => 'sraoss') where connected = '1';
また pg_stat_activity と組み合わせてより詳細な情報を表示することも可能です。
以下の SQL では pgpool_adm_pcp_proc_info とpg_stat_activity を結合して pgool_adm_pcp_proc_info では取得できない state を pg_stat_activity をから取得しています。
他にも wait_event など pg_stat_activity にしかない情報も同時に取得するなど要件に応じてクライアント情報を取得できます。
test=# SELECT p.username, p.database, p.client_port, s.state, s.wait_event, s.query, p.pid as pgpool_pid, s.pid as backend_pid FROM pcp_proc_info(host => '', port => 11001, username => 'sraoss', password => 'sraoss') AS p JOIN pg_stat_activity AS s ON s.pid::text = p.backend_pid; -[ RECORD 1 ]-------------+---------------------------------------------------------------------------------------------------------------------------- username | sraoss database | test client_host | 192.168.100.101 client_port | 50001 state | active query | select 1; pgpool_pid | 21467 backend_pid | 21500
ライフチェックログの改善
ライフチェックが開始したとき Watchdog は ライフチェックが開始したことを知らせるログを出力します。
4.6 までは正常に開始したタイミングでしかログが出力されないため、正常に動作しているかを確認するために開始ログが出るまでログを監視する必要があり、またライフチェックが正常に開始していない状況に気づくのが困難でした。
LOG: watchdog: lifecheck started
4.7 からはライフチェックが開始されるまで定期的にライフチェックが開始していない警告を出力するようになり、ライフチェック開始までログファイルを監視する必要がなくなりました。
間隔は wd_interval × 10 秒です。
WARNING: watchdog: lifecheck has not started yet
Watchdog と heartbeat receiver のセキュリティ強化
Watchdog と heartbeat receiver が受け付けるアドレスを制限することができるようになりました。
4.6 まではいずれのプロセスも、ホストが持つすべてのネットワークアドレスへの接続を受け付けていました。
tcp 0 0 0.0.0.0:9000 0.0.0.0:* LISTEN 3583037/pgpool: watchdog Tcp6 0 0 :::9000 :::* LISTEN 3583037/pgpool: watchdog Udp 0 0 0.0.0.0:9694 0.0.0.0:* 3583050/pgpool: heartbeat receiver udp 0 0 0.0.0.0:9694 0.0.0.0:* 3583044/pgpool: heartbeat receiver udp6 0 0 :::9694 :::* 3583044/pgpool: heartbeat receiver udp6 0 0 :::9694 :::* 3583050/pgpool: heartbeat receiver
4.7 からはセキュリティ上の点から hostname, heartbeat_hostname で指定したネットワークアドレスへのみ接続を受け付けるようになりました。
# pgpool.conf 設定例 hostname0 = '192.168.100.50' wd_port0 = 9000 heartbeat_hostname0 = '192.168.100.101' heartbeat_port0 = 9694 hostname1 = '192.168.100.60' wd_port0 = 9000 heartbeat_hostname1 = '192.168.100.102' heartbeat_port1 = 9694 hostname2 = '192.168.100.70' wd_port0 = 9000 heartbeat_hostname2 = '192.168.100.103' heartbeat_port2 = 9694
tcp 0 0 192.168.100.50:9000 0.0.0.0:* LISTEN 41636/pgpool: watchdog tcp 0 0 192.168.100.50:9000 0.0.0.0:* LISTEN 41638/pgpool: watchdog udp 0 0 192.168.100.101:9694 0.0.0.0:* 41649/pgpool: heartbeat receiver udp 0 0 192.168.100.101:9694 0.0.0.0:* 41650/pgpool: heartbeat receiver
もし他ノードから hostname, heartbeat_hostname で指定したネットワークアドレス以外へ heartbeat を送る設定とすると以下メッセージのように lifecheck に失敗します。
4.7 へ移行する場合は hostname, heartbeat_hostname で watchdog と heartbeat で LISTEN するソケットを設定し、他ノードから heartbeat を送るソケットを hostname, heatbeat_hostname で指定したネットワークアドレスとしてください。
WARNING: watchdog: lifecheck has not started yet
また 4.7. 1 ではさらに Watchdog と heartbeat それぞれについて LISTEN するソケットを個別で指定できるようになりました。
これによりノード外部から見えるアドレスと、ノード内部から認識されるアドレスが異なる可能性があるコンテナ環境や、ポートフォワーディングを設定している場合でも、より柔軟に設定できるようになりました。
Watchdog については wd_listen_address によってネットワークアドレスを、wd_listen_port によってポートも指定することができます。
heartbeat についてはそれぞれ wd_heartbeat_listen_addresses, wd_heartbeat_listen_port によって指定できます。
これらのパラメータが設定されているとき hostname, heartbeat_hostname, wd_port, heartbeat_port のローカルの設定は上書きされてソケットが作成されます。
# pgpool.conf 設定例 hostname0 = '192.168.100.50' wd_port0 = 9000 heartbeat_hostname0 = '192.168.100.101' heartbeat_port0 = 9694 wd_listen_address = 192.168.100.100 wd_listen_port = 50000 wd_heartbeat_listen_addresses = 102.168.100.110 wd_heartbeat_listen_port = 51000
tcp 0 0 192.168.100.100:50000 0.0.0.0:* LISTEN 41636/pgpool: watchdog udp 0 0 192.168.100.110:51000 0.0.0.0:* 41649/pgpool: heartbeat receiver udp 0 0 192.168.100.110:51000 0.0.0.0:* 41650/pgpool: heartbeat receiver
これらのパラメータが導入された背景は、Docker 環境を代表とした TCP 転送ルールを設けているインターフェース間で通信をする際に LISTEN するソケットを転送ルールに合わせて設定したいケースに対応するためです。
例えばノード 0 が IP:192.168.0.0, ポート番号:10000 のソケットに接続しようとし、TCP 転送ルールによってノード 1 の IP:192.168.100.100,ポート番号:20000 のソケットにリダイレクトされる環境の場合、ノード 1 側でリダイレクト後のネットワークアドレス、ポート番号(今回の例では IP:192.168.100.100, ポート番号:20000)に設定することで TCP 転送ルールがある場合でも通信が可能となりました。
オンラインリカバリに使用するデータベースを指定する recovery_database パラメータの追加
オンラインリカバリとは障害が発生して切り離されてしまった PostgreSQL ノードをプライマリに再同期して復帰する処理を各ノードを停止することなく行うことができる機能です。
以前はオンラインリカバリに template1 データベースを使用するようにしていましたが、今回追加された recovery_databse パラメータにオンラインリカバリに使用するデータベースを指定することができるようになりました。
#pgpool.conf の recovery_database を指定 recovery_database = 'postgres'
デフォルト値は postgres になっています。
4.6 以前から移行をする際には recovery_database に指定したデータベースで下記コマンドを実施してオンラインリカバリに必要な関数をインストールしておく必要があります。
psql postgres -c "CREATE EXTENSION pgpool_recovery"
.pcppassファイルからの読み取りに失敗時の挙動改善
.pcppass ファイルは pcp コマンドを実行したときに読み込まれるパスワードファイルです。
4.6 までは pcp コマンド実行時に .pcppass ファイルが未作成かパスワードファイルの権限設定が不適切の場合、エラーで終了していました。
また -d, –debug オプションがないとデバッグ情報が出力されず失敗の原因も特定できませんでした。
FATAL: authentication failed for user "sraoss" DETAIL: username and/or password does not match
失敗後は .pcppass ファイルを適切な権限で作成するか、パスワード入力を受け付けるオプションである -W オプションをつけて pcp コマンドを再実行する必要がありました。
pcp_node_info -p 9898 -W Password:
4.7 からはエラーを出力して終了するのではなく、クライアントのコマンドプロンプトにフォールバックして引き続きパスワードを入力することができるようになりました。
また WARNING による警告が -d, –debug オプションなく出力される仕様に変更され、読み取りができなかった原因もメッセージから特定することができます。
WARNING: password file ~/.pcppass is not a plain file WARNING: password file ~/.pcppass has group or world access; permissions should be u=rw (0600) or less
フロントエンド / バックエンドプロトコルバージョン 3.2 サポートの追加
PostgreSQL 18 ではプロトコルバージョン 3.2 に対応し、可変長のキャンセルキーが用いることができるようになりました。
この変更に合わせ、Pgpool-II でもプロトコルバージョン 3.2 を利用できるように改善がされました。
max_protocol_version や PGMAXPROTOCOLVERSION を用いた以下のようなコマンドで 3.2 プロトコルを使用して PostgreSQL のフロントエンドとバックエンドを接続することができます。
バージョンには 3.2 だけでなく PostgreSQL 18 のデフォルトのプロトコルバージョンである 3.0 を指定することもできます。
# max_protocol_version オプションで 3.0 バージョンで接続 psql "host=localhost dbname=test user=sraoss max_protocol_version=3.0 port=11000" # 環境変数 PGMAXPROTOCOLVERSION に 3.2 を指定して接続 PGMAXPROTOCOLVERSION="3.2" psql -p 11000 test
新規接続時は指定したプロトコルバージョンで接続を確立しますが、コネクションプーリングのキャッシュがある場合は既存のキャッシュに保存されたのプロトコルバージョンを用いて接続を行うため確立済みの接続間でバージョンが異なることによるエラーの心配もありません。
PostgreSQL 18 の SQL パーサの導入
Pgpool-II ではメジャーリリースするたびに、PostgreSQL の最新パーサを移植しています。今回のリリースでは PostgreSQL 18 の新しいパーサを取り込みました。
Pgpool-II の負荷分散機能では、SQL を解析して参照か更新かを判別し、どのノードに振り分けるかを決めています。そのため、PostgreSQL の新バージョンでの SQL の変更に対応するには、SQL パーサを移植する必要があります。
PostgreSQL 18 での SQL のおもな変更点は以下のとおりです。
- 生成列を仮想列として使用可能に
- DML クエリの RETURNING にOLD/NEWのサポートを追加
- 各種制約の追加(例: WITHOUT OVERLAPS、ENFORCED/NOT ENFORCED)
Pgpool-II 4.7 では上記の変更点に対応しています。
logdir パラメータ名を work_dir へ変更
4.6 までは Pgpool-II の起動状態を記述する pgpool_status や memq_lock_file といった管理ファイルを logdir に指定するディレクトリに保存していました。
しかし logdir というパラメータ名はログ関連のファイルを格納するディレクトリの設定パラメータと誤解されやすい問題がありました。
4.7 からはパラメータ名が work_dir へ変更となりました。
logdir のパラメータ自体も引き続き利用することができ、logdir に指定した値が work_dir の設定値へと再設定され Pgpool-II の終了時に以下ワーニングが表示されます。
2026-01-08 11:50:48.193: main pid 18667: WARNING: logdir is changed to work_dir 2026-01-08 11:50:48.193: main pid 18667: DETAIL: if logdir is specified, the value will be set to work_dir
Slony モードの廃止
backend_clustering_mode で指定することができていた Slony モードが廃止されました。
データのレプリケーションを Slony-I が行うクラスタリングモードの一つでしたが、Slony-I は 3 年前からリリースが停止しています。
現在は Slony モードについて積極的に利用するユーザーが見られず、廃止のアナウンスに異議がなかったため 4.7 からは廃止となりました。
Pgpool-II の libpcp ライブラリの名称を libpgpoolpcp に変更
4.7.1 のマイナリリースにて Pgpool-II のライブラリである libpcp の名称を libpgpoolpcp に変更されました。
背景として、RHEL の libpcp ライブラリと Pgpool-II の libpcp ライブラリがコンフリクトする問題があったためです。
おわりに
今回は、Pgpool-II 4.7 の新機能について紹介しました。
Pgpool-II 4.7 では、より実用的で便利な機能が数多く追加・改善されています。PostgreSQL の高可用性構成や負荷分散の実現を検討されている方にとって、Pgpool-II は有力な選択肢です。ぜひこの機会に Pgpool-II の導入をご検討ください。