なお、PostgreSQLのロジカルレプリケーション自体についての基本的な解説は、以下の記事を参考にしてください。

• ロジカルレプリケーションの紹介 (1)
• ロジカルレプリケーションの紹介 (2)
• ロジカルレプリケーションの紹介 (3)

ロジカルレプリケーションによるアップグレードの概要

ロジカルレプリケーションを利用することで、異なるメジャーバージョン間でデータを同期しながら新しい環境を構築することが可能です。新旧データベースを並行稼働させ、最終的に接続先を切り替えることで、数秒程度のダウンタイムで移行を実現できます。

上記イメージはロジカルレプリケーションを用いたバージョンアップのアーキテクチャイメージです。

対応バージョンとしては、Publisher（旧バージョンのデータベース）は PostgreSQL 10 以上である必要があります。例えば PostgreSQL 13 から 16 へのアップグレードは可能ですが、9.6 からの移行には対応していません。

全体の流れは以下のとおりです。これらの手順について詳しく解説します。
ロジカルレプリケーションはデータベース単位で構成されるため、各データベースごとに個別に設定・同期を行います。

1. 旧バージョンのデータベースを稼働させたまま、新バージョンのデータベースクラスタを initdb で構築し起動する

以下の手順を、対象となるすべてのデータベースに対して実施します。

2. 旧バージョンの各データベースで全テーブルを対象としたパブリケーションを作成
3. 新バージョン側に移行するデータベースを作成
4. 旧バージョンの各データベースから pg_dump -s でスキーマ定義の SQL を取得して新バージョンの各データベースにリストア
5. 新バージョンの各データベースでサブスクリプションを作成

すべてのデータベースでサブスクリプション作成および同期が完了した後、
以下の作業を実施します。

6. 旧バージョンのデータベースクラスタへの更新処理を停止する
7. 各データベースで pg_stat_subscription を確認し、LSN の一致を確認する
8. 同期完了後、シーケンス位置やラージオブジェクトなどロジカルレプリケーションで同期されないデータを各データベースで手動同期する
9. アプリケーションの接続先を切り替える

ロジカルレプリケーションによるアップグレードの注意点

ロジカルレプリケーションでは、テーブルの行データに対する変更がサブスクライバへ同期されます。一方で、行データ以外の更新情報は同期されません。

そのため、以下のようなオブジェクトは別途作成または移行する必要があります。

• テーブルやスキーマの定義
• ビューおよびマテリアライズドビューの定義
• パーティションテーブルや外部テーブルの定義
• シーケンスの現在値
• ラージオブジェクト
• 拡張機能
• UNLOGGED TABLE
• ロール

特にスキーマ、テーブル定義についてはロジカルレプリケーションでは同期されず、サブスクライバ側で定義されていない状態でロジカルレプリケーションを行うと伝播先のテーブルがないとしてレプリケーションに失敗します。よってスキーマ、テーブル定義については pg_dump を用いて定義の SQL を取得して新バージョンのデータベースで実行するなどして事前にリストアしておく必要があります。今回紹介する手順では pg_dump に -s  オプションを付与して実行し、各 DDL を取得してロジカルレプリケーション前に新バージョンのデータベースで実行するようにします。

またその他にも拡張機能やロールなどもロジカルレプリケーションでレプリケーションされないため必要に応じて別途リストアする必要があります。

アップグレード手順

旧バージョンデータベースのロジカルレプリケーションのセットアップ

今回使用する環境は以下の通りで、PostgreSQL 14 から PostgreSQL 18 に移行します。

まず最初に旧バージョンのデータベースを稼働させたまま新データベースクラスタを構築し、旧バージョンでロジカルレプリケーションの有効化とパブリケーションを作成を行います。

#新しいバージョンのデータベースクラスタを作成して起動
$ /usr/local/pgsql18/bin/initdb -D /var/lib/pgsql/18
[postgres@server1 ~]$ /usr/local/pgsql18/bin/pg_ctl -D /var/lib/pgsql/18 -o "-p 5433" start

ロジカルレプリケーションではパブリッシャの wal_level は logical である必要があります。ロジカルレプリケーションとは別にストリーミングレプリケーションを利用している場合は既に使用しているレプリケーションスロット数に今回のロジカルレプリケーション用に必要なスロット数を加えた値を max_replication_slots に設定してください。複数のデータベースを新バージョンへ移行する場合は、旧バージョン側でデータベースの数分レプリケーションスロットを作成しますのでその分のスロット数も max_replication_slots に乗じてください。

またパブリッシャから WAL 情報を送信する walsender プロセスの上限を決定する max_wal_senders もレプリケーション接続される数を超えるように設定してください。設定後にサーバーを再起動して設定を反映します。

# ロジカルレプリケーションを利用できるよう旧バージョンの postgresql.conf を編集して再起動
[postgres@server1 ~]$ vi /var/lib/pgsql/14/postgresql.conf
wal_level = logical
#max_replication_slots = 10
#max_wal_senders = 10
[postgres@server1 ~]$ /usr/local/pgsql14/bin/pg_ctl -D /var/lib/pgsql/14 -o "-p 5432" restart

再起動後、今回のレプリケーションの動作確認用に、旧バージョンのデータベースに users テーブルを作成します。

[postgres@server1 ~]$ /usr/local/pgsql14/bin/psql -p 5432
psql (14.22)
Type "help" for help.

postgres=# CREATE TABLE users (
id SERIAL PRIMARY KEY,
name TEXT
);
CREATE TABLE
postgres=# INSERT INTO users(name) VALUES ('taro');
INSERT 0 1
postgres=# INSERT INTO users(name) VALUES ('jiro');
INSERT 0 1
postgres=# \d
List of relations
Schema | Name         | Type     | Owner
-------+--------------+----------+----------
public |    users     |  table   | postgres
public | users_id_seq | sequence | postgres
(2 rows)

postgres=# SELECT * FROM users;
id | name
---+------
1  | taro
2  | jiro
(2 rows)

その後パブリケーションを作成します。パブリケーションの対象を FOR ALL TABLES とし、すべてのテーブルを同期対象にするようにします。複数データベースを移行する場合はデータベースごとにパブリケーションを作成してください。

postgres=# CREATE PUBLICATION pub_all FOR ALL TABLES;

# 他データベースも必要であれば同様に作成する
db2=# CREATE PUBLICATION pub_all_2 FOR ALL TABLES;

旧バージョンデータベースの pg_hba.conf  設定

旧バージョン側  pg_hba.conf には、新バージョンデータベースからのレプリケーション接続を許可する設定を追加します。論理レプリケーションでは、サブスクライバからパブリッシャへ接続してデータ取得を行うため、replication 権限を持つ接続許可が必要です。

# サブスクライバからのレプリケーション接続を許可
host replication postgres 0.0.0.0/0 trust

新バージョンに移行するデータベースとスキーマを移行

ロジカルレプリケーションではテーブルデータのみが同期対象となり、ロール、データベース、スキーマ定義などは自動的には同期されません。そのため、ロジカルレプリケーションを開始する前にこれらを新バージョン側へ移行しておく必要があります。

まずはロールやテーブルスペースなどのグローバルオブジェクトを移行します。

# グローバルオブジェクトをダンプ・リストア
[postgres@server1 ~]$ /usr/local/pgsql18/bin/pg_dumpall -g | /usr/local/pgsql18/bin/psql -p 5433

次に新バージョンの各データベースに pg_dump -s -C でスキーマ定義を旧バージョンのデータベースからリストアしたのちにサブスクリプションを作成してテーブルデータを同期します。注意点でも述べた通りロジカルレプリケーションではスキーマやテーブル定義といった DDL までは同期されないので別途に pg_dump によって手動でリストアしておく必要があります。

pg_dump, psql は -d で対象データベースを指定します。データベースを複数移行する場合はデータベースごとに pg_dump, psql を実施し、-d で指定するデータベースを変更してください。

pg_dump の結果を psql で実行した後に \d でリレーションを確認すると旧バージョンで作成した users テーブルやシーケンスがコピーされていることが分かります。

[postgres@server1 ~]$ /usr/local/pgsql18/bin/pg_dump -p 5432 -s -C -d postgres |  /usr/local/pgsql18/bin/psql -p 5433
[postgres@server1 ~]$ /usr/local/pgsql18/bin/psql -p 5433
psql (18.3)
Type "help" for help.
postgres=# \d
List of relations
Schema | Name         | Type     | Owner
-------+--------------+----------+----------
public | users        |  table   | postgres
public | users_id_seq | sequence | postgres
(2 rows)

新バージョンの各データベースでのサブスクリプションのセットアップ

次に旧バージョンの各データベースで作成したパブリケーションに対してサブスクリプションを作成します。サブスクリプションは移行するデータベースごとに作成し、CONNECTION の引数内の dbname や PUBLICATION でしているパブリケーション名は適宜変更してください。

その後テーブルの中身を SELECT するとテーブルデータが同期されていることが分かります。

postgres=# CREATE SUBSCRIPTION sub_all
CONNECTION 'host=localhost port=5432 dbname=postgres'
PUBLICATION pub_all;
NOTICE: created replication slot "sub_all" on publisher
CREATE SUBSCRIPTION
postgres=# SELECT * FROM users;
id | name
---+------
1  | taro
2  | jiro
(2 rows)

旧バージョンの各データベースへの更新を停止して同期の完了を待ち、シーケンス位置を揃える

サブスクリプション作成後、旧バージョンの各データベースへの更新を一時停止します。これによって旧バージョン側の LSN を止め、新バージョン側の LSN が追い付ける状態にします。

更新処理停止後、新バージョン各データベースごとに pg_stat_subscription 内を確認して received_lsn と latest_end_lsn が一致していることが確認できれば同期は完了です。received_lsn はパブリッシャから受け取った WAL 位置を、latest_end_lsn はパブリッシャから受け取った WAL をサブスクライバで適用し、その完了をパブリッシャに報告した位置を示します。

postgres=# SELECT * FROM pg_stat_subscription;
-[ RECORD 1 ]---------+------------------------------
subid                 | 16395
subname               | sub_all
worker_type           | apply
pid                   | 3457
leader_pid            |
relid                 |
received_lsn          | 0/1718270
last_msg_send_time    | 2026-04-27 15:33:53.961503+09
last_msg_receipt_time | 2026-04-27 15:33:53.961586+09
latest_end_lsn        | 0/1718270
latest_end_time       | 2026-04-27 15:33:53.961503+09

その後シーケンス位置を手動で同期します。ロジカルレプリケーションではシーケンス位置はレプリケーションされず、また pg_dump -s でもシーケンス位置を設定する SQL は出力されません。そのためシーケンスの位置は手動で揃える必要があります。

新バージョン側でシーケンスを調整する前の時点ではシーケンスの開始値が初期値である 1 のままとなっています。そのため、新バージョンのデータベース側で INSERT を実行すると、すでにテーブルに存在する id=1 の行と重複し、ユニーク制約違反が発生します。

postgres=# SELECT currval('users_id_seq');
ERROR: currval of sequence "users_id_seq" is not yet defined in this session
postgres=# INSERT INTO users(name) VALUES ('saburo');
ERROR: duplicate key value violates unique constraint "users_pkey"
DETAIL: Key (id)=(1) already exists.

シーケンス位置は pg_dump の出力に含まれる setval の SQL を新バージョン側の各データベースで実行して反映します。-d オプションの引数もデータベースごとに適宜変更してください。

[postgres@server1 ~]$ pg_dump -p 5432 -d postgres > dump.sql
[postgres@server1 ~]$ cat dump.sql
(省略)

--
-- Name: users_id_seq; Type: SEQUENCE SET; Schema: public; Owner: postgres
--

SELECT pg_catalog.setval('public.users_id_seq', 2, true);

[postgres@server1 ~]$ /usr/local/pgsql18/bin/psql -p 5433
psql (18.3)
Type "help" for help.
postgres=# SELECT pg_catalog.setval('public.users_id_seq', 2, true);

その他ラージオブジェクトや拡張機能など、WAL 書き出されずロジカルレプリケーションの対象外となっているものについても手動で同期を行います。これによって旧バージョンと新バージョンの同期は完了です。

同期完了後アプリケーションの接続先を新バージョンのデータベースに切り替える

すべてのデータベースの同期完了後にアプリケーションの接続先を切り替えます。

新バージョンの各データベースのサブスクリプションを無効化、マテリアライズドビューをすべて REFRESH したのちに、新バージョン側のpg_hba.conf にアプリケーションからの接続の認証情報を記述し、アプリケーションの接続先を切り替えればアップグレードは完了です。

# サブスクリプションを無効化
postgres=# ALTER SUBSCRIPTION sub_all DISABLE;

# マテリアライズドビューがあれば REFRESH
postgres=# REFRESH MATERIALIZED VIEW my_mv;

# pg_hba.conf にアプリケーションからの接続の認証情報を記載(環境に合わせて適宜記載)
host all application 0.0.0.0/0 trust

まとめ

ロジカルレプリケーションを用いた PostgreSQL のメジャーアップグレードは、適切に設計・運用することで、サービス停止時間を最小限に抑えた安全な移行を実現できます。ただし、データ以外の要素は自動的には同期されないため、スキーマ、シーケンス位置などを含めた包括的な準備が不可欠です。

事前検証と十分な計画を行うことで、本番環境においても安定したアップグレードを実施できます。

Pgpool-II 4.7 では、クライアント情報表示機能や、Watchdog と heartbeat receiver のセキュリティ強化、オンラインリカバリの機能が強化されました。また、フロントエンド/バックエンドプロトコルバージョン 3.2 サポートの追加、PostgreSQL 18 への対応も行われました。

Pgpool-II 4.7 の新機能及び変更点は Pgpool-II 公式ドキュメントの以下のページに記載されています。

Pgpool-II 4.7 リリースノート

本記事では、これらの新機能について詳しく紹介します。

クライアント情報を表示するための 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 の導入をご検討ください。

PostgreSQL には様々なバックアップの方法が提供されています。
それぞれのバックアップの方法は利点が違い、運用方法も手順も異なります。
今回はバックアップ方法の簡単なおさらいと、PostgreSQL 17 で標準機能として追加された増分バックアップについて紹介します。

PostgreSQLのバックアップの種類

PostgreSQL のバックアップは大きく論理バックアップ と 物理バックアップの 2 種類に分類できます。

論理バックアップ

SQL レベルでデータを取得する方式です。
CREATE TABLE や INSERT 文などで現在のデータベースの状態を再現できるファイルを生成します。
異なるOSアーキテクチャ間や PostgreSQL メジャーバージョン間でもリストア可能という柔軟性が大きな利点です。

物理バックアップ

データベースクラスタ全体のディレクトリを丸ごと保存する方式です。
Linux の cp コマンドや PostgreSQL 標準ツールである pg_basebackup を利用できます。
pg_basebackup では PITR（Point-In-Time Recovery）や PostgreSQL 17 で追加された 増分バックアップ を利用できる点が最大の特徴です。

今回は、この「増分バックアップ」について詳しく紹介します。

増分バックアップとメリット

増分バックアップは、ある時点で取得したフルバックアップをベースとし、その後に変更された部分だけを保存する方式です。

たとえば、10 TB のデータベースを毎日 30 日分フルバックアップで保存すると、
10 TB × 30 日 = 300 TB もの容量が必要になります。

しかし増分バックアップであれば、
初日のフル 10 TB + 毎日の変更分のみを保存すればよく、大幅なストレージ削減が可能です。
上記の図は毎日の変更分を10GBと想定した場合の比較図となります。

また、バックアップ取得時間も短縮できます。
フルバックアップではすべてのデータをコピーするため時間がかかりますが、増分バックアップは変更分だけを取得するためバックアップ時間の短縮につながります。
また結果としてサーバー負荷の軽減にも寄与します。

増分バックアップの手順

従来、PostgreSQL で増分バックアップを行いたい場合は、サードパーティツールである pg_rman の利用が一般的でした。
ただし、pg_rman は Windows 非対応という課題がありました。

PostgreSQL 17 ではこれらの問題が解消され、標準機能として増分バックアップがサポートされました。
主な追加項目は以下のとおりです。

1. pg_basebackup に増分バックアップを取得する -​-incremental オプションが追加
2. フルバックアップと増分バックアップを統合する pg_combinebackup コマンドの追加
3. 増分バックアップの制御にかかわる summarize_wal, wal_keep_summary パラメータの追加

これらによって増分バックアップの取得が可能になっています。
それぞれのコマンドやパラメータの扱い方について詳しく見ていきましょう。

動作確認環境と postgresql.conf のパラメータは以下です。

動作環境

postgresql.conf パラメータ

増分バックアップのコマンド

増分バックアップの手順は大きく分けて以下です。

1. pg_basebackup によるフルバックアップの取得
2. pg_basebackup -​-incremental による増分バックアップの取得
3. pg_combinebackup によるフルバックアップと増分バックアップの統合

コマンド実行例をもとに見ていきましょう。

フルバックアップ取得前の時点では full_backup というテーブルがあるのみです。

これから各増分バックアップ取得時点でテーブルを追加していき、各世代のバックアップの状態にリストアできるかを見ていきます。

$ psql
psql (17.6)
"help"でヘルプを表示します。
postgres=# \d
               リレーション一覧
 スキーマ |    名前     |  タイプ  |  所有者
----------+-------------+----------+----------
 public   | full_backup | テーブル | postgres
(1 行)

最初に pg_basebackup コマンドでフルバックアップを取得します。

# -P オプションでサイズや進捗を確認可能
$ pg_basebackup  -D backup/full -P
23818/23818 kB (100%), 1/1 テーブル空間

その後 inc1 テーブルを作成し、一回目の増分バックアップを取得します。

ここで pg_basebackup に新規で追加された -​-incremental オプションを用います。
引数には前回取得したバックアップ、つまりフルバックアップの backup_manifest ファイルを指定します。
backup_manifest ファイルはバックアップのトップディレクトリにあるのでそちらのパスを指定してください。

postgres=# create table inc1 (i int);
CREATE TABLE
$ pg_basebackup --incremental=backup/full/backup_manifest -D backup/inc1

二回目の増分バックアップも同様に inc2 テーブルを作成後取得します。

この時注意が必要なのが前回のバックアップを指定することです。
今回だとフルバックアップではなく一回目の増分バックアップの backup_manifest を指定します。

postgres=# create table inc2 (i int);
CREATE TABLE
$ pg_basebackup --incremental=backup/inc1/backup_manifest -D backup/inc2

最後に pg_combinebackup で各世代を統合していきます。
pg_combinebackup の -o オプションでは統合バックアップの出力先を指定し、その後の引数はフルバックアップから統合したい世代までの増分バックアップをすべて指定します。

統合後はpg_verifybackupでバックアップの整合性も忘れずチェックするようにしてください。

# フルバックアップからinc1(inc1 テーブルがある時点)まで
$ pg_combinebackup -o backup/combine_full_inc1 backup/full/ backup/inc1
# フルバックアップからinc2(inc1, inc2 テーブルがある時点)まで
$ pg_combinebackup -o backup/combine_full_inc2 backup/full/ backup/inc1 backup/inc2/
# 各統合バックアップを pg_verifybackup で検証
$ pg_verifybackup backup/combine_full_inc1
バックアップが正常に検証されました
$ pg_verifybackup backup/combine_full_inc2
バックアップが正常に検証されました

各世代増分バックアップの中身を確認

では、各世代のバックアップが正しく取得できているか確認してみましょう。

統合バックアップを、それぞれ異なる port 番号 に設定して起動すると、各世代におけるinc1、inc2テーブルの状態が、作成時点の内容として保持されていることが分かります。

この検証により、全ての世代でバックアップが正しく取得されていることを確認できました。

$ pg_ctl -o "-p 5433" start -D backup/combine_full_inc1/
$ psql –p 5433
postgres=# \d
               リレーション一覧
 スキーマ |    名前     |  タイプ  |  所有者
----------+-------------+----------+----------
 public   | full_backup | テーブル | postgres
 public   | inc1        | テーブル | postgres
$ pg_ctl -o "-p 5434" start -D backup/combine_full_inc2/
$ psql –p 5434
postgres=# \d
               リレーション一覧
 スキーマ |    名前     |  タイプ  |  所有者
----------+-------------+----------+----------
 public   | full_backup | テーブル | postgres
 public   | inc1        | テーブル | postgres
 public   | inc2        | テーブル | postgres

増分バックアップのストレージコストと取得時間

最初に挙げたメリットとして、ストレージコストとバックアップ取得時間を抑えられる点がありました。
ここでは、実際にどの程度削減できているのか確認してみます。

まずストレージ使用量を比較すると、初回に取得したフルバックアップは 888 MB と比較的大きなサイズでした。
一方、続いて取得した増分バックアップは どれも約 4 MB 程度 と非常に小さく抑えられています。

これを「すべての世代をフルバックアップで保存する場合」と比べてみると、毎回 888 MB 近く消費することになります。
それに対して増分バックアップは変更分のみを保存すればよいため、世代を重ねてもバックアップ容量を大幅に抑えられる ことが分かります。

$ du -h  --max-depth=1 backup/
888M     backup/full
6M     backup/inc1
4M     backup/inc2

また time コマンドでバックアップ取得の時間も比べてみましょう。

pg_basebackup -​-incremental と -​-incremental オプションなしのフルバックアップの取得時間を比べてみると、-​-incremental での増分バックアップは取得時間がかなり短いことが分かります。

$ time pg_basebackup -D backup/inc_3 --incremental=backup/inc2/backup_manifest -c fast -P
  4045/888986 kB (100%), 1/1 テーブル空間
real    0m4.391s
$ time pg_basebackup -D backup/full_3 -c fast -P
888986/888986 kB (100%), 1/1 テーブル空間
real    0m32.777s

pg_combinebackup のオプション

pg_combinebackup には統合のファイルコピーを高速化するオプションが用意されています。

ファイルコピーを高速化するオプション

デフォルトのオプション以外はすべて高速化できるものの、すべて入出力のディレクトリが同じファイルシステムである必要がある点には注意してください。
-​-copy-file-range, -​-clone については実行できる環境に上記表のような制限もあります。

同期のオプション

同期する範囲を指定できるオプションもあり、
同期対象を増やすほどディスクへの書き込みがより確実に行われるようになります。

デフォルトではバックアップ対象のディレクトリのみですが、-​-plain で WAL ファイルとテーブル空間全体のシンボリックリンクまで、-​-syncfs ではバックアップディレクトリを含むファイルシステム全体を同期の対象とできます。

-​-syncfs はファイルを一つ一つ開かず同期をチェックするため同期が素早く完了できるというメリットもあります。

増分バックアップ使用上の注意点

注意点は大きく分けて以下の3つです。それぞれ見ていきます。

1. パラメータの管理
2. フルバックアップ～増分バックアップの保存
3. ストレージ容量

パラメータの管理

増分バックアップで管理すべきパラメータは以下です。

1. summarize_wal
2. wal_level
3. wal_summary_keep_time

summarize_wal は pg_basebackup -​-incremental をする際に参照する wal の情報をまとめたサマリファイルを作成するか否かを制御するパラメータです。

このファイルがない状態で増分バックアップを取得しようとするとエラーとなり取得に失敗してしまいます。
デフォルトでは off となっていますので忘れずに on としてください。

# summarize_wal が off で取得したフルバックアップを対象とするとエラー
$ pg_basebackup --incremental=backup/full/backup_manifest -D backup/inc1
pg_basebackup: エラー: ベースバックアップを開始できませんでした: 
ERROR:  WAL集約が有効でなければ差分バックアップは取得できません

wal_level についても replica 以上が必要です。
これが replica 以上でないと summarize_wal のパラメータが無効となる仕様となっています。

wal_summary_keep_time はサマリファイルを保存する期間を指定するパラメータです。
例えば以下のように 1d に設定し、2 日後に増分バックアップを取得しようとすると必要なサマリファイルが削除されているため、取得に失敗してしまいます。
そのため、増分バックアップを取得する運用間隔よりも長い期間を設定する必要があります。

# postgresql.conf の wal_summary_keep_time を 1d に設定
wal_summary_keep_time = '1d'

$ ls –l  data/pg_wal/summaries/
-rw-------. 1 postgres postgres 32 11月 1 16:52 0000000100000001CF00002800000001D0000028.summary
# 2 日後に増分バックアップを取得しようとすると失敗
$ date
2025年 11月 3日 月曜日 15:37:55 JST
$ pg_basebackup -D backup/inc_1 --incremental=backup/full/backup_manifest -P -c fast
pg_basebackup: エラー: ベースバックアップを開始できませんでした:
ERROR:  WAL集計がタイムライン1上の1/CD000060から1/CF000028まで必要ですが、そのタイムライン上のそのLSN範囲での集計は不完全です
DETAIL:  この範囲で集計されていない最初のLSNは1/CD000060です

フルバックアップ～増分バックアップの保存

pg_combinebackup をする際に引数フルバックアップ～統合したい世代までのフルバックアップがすべてないと以下エラーとなります。

# 最初の引数にフルバックアップを指定せずに実行
$ pg_combinebackup -o backup/combine_test backup/inc1 backup/inc2
pg_combinebackup: エラー: "backup/inc1"のバックアップは差分バックアップですが、最初のバックアップはフルバックアップである必要があります
# backup/inc_1 を引数に渡さず実行
# LSN 位置に飛びが見られエラーとなる
$ pg_combinebackup -o backup/combine_1 backup/full/ backup/inc_2
pg_combinebackup: エラー: "backup/full/"のバックアップはLSN 1/1A000060で始まっていますが、1/1C000028を期待していました

そのため、実際の運用ではフルバックアップと、最新世代までのすべての増分バックアップを保持しておく必要があります。
削除のタイミングとしては、定期的に pg_combinebackup を実行し、統合によって 不要になった過去のフルバックアップおよび増分バックアップを削除するフローになります。

また、統合して生成されたバックアップは、次回の pg_combinebackup におけるフルバックアップとして利用可能 であるため、統合元となった古いフルバックアップは削除して問題ありません。

ストレージ容量

ストレージコストの低さがメリットの増分バックアップですが、pg_combinebackup をした直後は古いバックアップと統合バックアップが共存する状態になりますので、それらすべてを保存できるストレージサイズを確保する必要があります。

増分バックアップと
PITR と両立したリストア手順

増分バックアップ PITR と両立しての増分バックアップを利用することができます。

PITR(Point In Time Recovery) は WAL アーカイブをもとにして任意の時点までのリストアを可能にするリストア方法です。

WAL アーカイブはデータの変更履歴が記載されたもので、事前に取得しておいたフルバックアップに WAL アーカイブの変更履歴を任意の時点まで適用することで任意の時点に復旧できることが強みのリストア方法です。

この PITR と増分バックアップと両立することで以下メリットが得られます。

1. 増分バックアップによるバックアップ取得でストレージコストや取得時間を短く抑えられる
2. PITR によるリストアでより任意の時点に復旧することができる

今回はこれらを両立する設計で具体的な設定手順を紹介します。

まずパラメータの設定を行います。

#wal をアーカイブする設定
#%p は保管するWALファイルの相対パス, %f がWALのファイル名に置き換わる
archive_mode = on
archive_command = 'cp "%p" "/pg_arc/%f"'
#restore を行う設定
restore_command = 'cp "/pg_arc/%f" "%p"'

その後増分バックアップ取得を行います。
フルバックアップ、増分バックアップ取得、バックアップの統合、検証の手順で取得します。

# フルバックアップ～バックアップの取得・統合、検証まで実施
$ pg_basebackup  -D backup/full
$ pg_basebackup --incremental=backup/full/backup_manifest -D backup/inc1
$ pg_combinebackup -o backup/combine_full_inc1 backup/full/ backup/inc1
$ pg_verifybackup backup/combine_full_inc1

その後 mv コマンドで疑似的にデータベースのデータが消えてしまった状態を作ります。

そして統合したバックアップを元のデータディレクトリに mv で移動し、recovery.signal を作成して起動すると PITR のリカバリモードで起動します。
リカバリ終了後に状態を見に行くとデータが指定した時点に復旧していることが分かります。

# データを移動して障害を疑似的に起こす
$ mv data data_crash
# 統合したバックアップを元ディレクトリにコピー
$ cp –r databackup/combine_full_inc1 data
# リカバリモードで起動するよう指示するrecovery.signal を作成して起動
$ touch data/recovery.signal
# 必要に応じて postgresql.conf を設定し復旧タイミングを指定
recovery_target_time = '2025-10-20 14:05:00'
$ pg_ctl start
# ログに以下が出力されていれば復旧完了
LOG: starting archive recovery
LOG: archive recovery complete

まとめ

今回は PostgreSQL 17 で追加された増分バックアップの運用方法と注意点について紹介しました。

PostgreSQL18ではさらに機能が追加されたりと今後より便利になっていく注目の手法です。
紹介した手順を参考に増分バックアップの利用を検討いただけると幸いです。

Pgpool-II 4.6 では、ロギングコレクター、クエリキャッシュの機能強化がされました。また、バックエンドからのメッセージのログ機能の搭載、PostgreSQL 17 への対応、Watchdog の IPv6 への対応も行われました。

Pgpool-II 4.6 の新機能及び変更点は Pgpool-II 公式ドキュメントの以下のページに記載されています。

Pgpool-II 4.6 リリースノート

本記事では、これらの新機能について詳しく紹介します。

ログのローテーションを指示する新しい PCP コマンド

Pgpool-II には、PostgreSQL のロギングコレクター(logging_collector) と同様のログ収集機能が備わっています。

ロギングコレクターを使ってログを収集する場合、これまではロギングコレクターにシグナルを送ることでしかログのローテーションを行えませんでしたが、pcp_log_rotate コマンドを使用することで Pgpool-II のログファイルを簡単にローテーションできるようになりました。

動作確認のための設定例は以下の通りです。

(pgpool.conf 設定例)
log_destination = 'stderr' 
logging_collector = on 
log_directory = '/var/log/pgpool_log' 
log_filename = 'pgpool-%Y-%m-%d_%H%M%S.log'

log_directory で指定したディレクトリを確認すると、現時点でのログが出力されていることが確認できます。

[root@server1 ~]# ls -l /var/log/pgpool_log/
合計 4
-rw-------. 1 postgres postgres 193 6月 9 16:21 pgpool-2025-06-09_162145.log

その後、 pcp_log_rotate を実行することで新しいログファイルへとローテートされていることが確認できます。

[root@server1 ~]# pcp_log_rotate -h 192.168.100.50  -p 9898 -U pgpool -W
Password:
pcp_log_rotate -- Command Successful

[root@server1 ~]# ls -l /var/log/pgpool_log/
合計 8
-rw-------. 1 postgres postgres 284 6月 9 16:21 pgpool-2025-06-09_162145.log
-rw-------. 1 postgres postgres 193 6月 9 16:21 pgpool-2025-06-09_162159.log

また -s scope オプションによってコマンドの与える影響範囲を指定することができます。サポートされているコマンドスコープは以下です。(デフォルトは local)

• c, cluster : クラスタを構成するすべての Pgpool-II のログファイルをローテーションします。
• l, local : ローカル Pgpool-II のログファイルをローテーションします。

リロードによる logging_collector 関連のパラメータの変更

logging_collector 関連の以下の設定パラメータの変更が、Pgpool-II のリロードで反映されるようになりました。これにより logging_collector の設定の反映のために Pgpool-II の再起動の必要がなくなりました。

• log_truncate_on_rotation
• log_directory
• log_filename
• log_rotation_age
• log_rotation_size
• log_file_mode

リロードで設定が反映されるかの動作確認として log_filename の値を変更したうえで pcp_log_rotate コマンドを実行してログファイルの名前が変更されて出力されるかを確認します。

まず、pgpool.conf を以下の設定に変更し、 Pgpool-II をリロードします。

[root@server1 ~]# vi /etc/pgpool-II/pgpool.conf
#log_filename = 'pgpool-%Y-%m-%d_%H%M%S.log'
log_filename = 'pgpool-%a.log'

[root@server1 ~]# systemctl reload pgpool.service

その後 pcp_rotate_log コマンドを実行すると出力されるログファイルの名前が変更されていることが確認できます。

[root@server1 ~]# ls -l /var/log/pgpool_log/
合計 8
-rw-------. 1 postgres postgres 284  6月 12 09:51 pgpool-2025-06-12_095140.log
-rw-------. 1 postgres postgres 193  6月 12 09:51 pgpool-2025-06-12_095142.log

[root@server1 ~]# pcp_log_rotate -U pgpool -W -h 192.168.100.50
Password:
pcp_log_rotate -- Command Successful
[root@server1 ~]# ls -l /var/log/pgpool_log/
合計 12
-rw-------. 1 postgres postgres 284  6月 12 09:51 pgpool-2025-06-12_095140.log
-rw-------. 1 postgres postgres 411  6月 12 09:52 pgpool-2025-06-12_095142.log
-rw-------. 1 postgres postgres 361  6月 12 09:52 pgpool-Thu.log

クエリキャッシュの強制的な作成

クエリキャッシュは SELECT クエリの実行結果を共有メモリに保存し、同じクエリ(パラメータ、データベース、ユーザ含む)が実行されたら、結果を再利用する機能です。PostgreSQL にアクセスせず、ディスクアクセスもないので極めて高速に問い合わせ結果を返すことができます。

Pgpool-II では、クエリキャッシュは通常自動的に作成されますが、安全性の観点から、immutable でない関数を含むクエリ (たとえば SELECT now();) はキャッシュされない仕様になっています。

以下の実行例では、クエリを実行するたびに結果が変化していることがわかります。

postgres=> SELECT now();
now
-------------------------------
2025-06-12 17:10:27.241885+09
(1 行)

postgres=> SELECT now();
now
-------------------------------
2025-06-12 17:10:29.156295+09
(1 行)

また、ログからも毎回 PostgreSQL にアクセスしていることが確認できます。

2025-06-12 17:10:27.241: psql pid 2628: LOG: DB node id: 1 backend pid: 2644 statement: SELECT now();
2025-06-12 17:10:29.155: psql pid 2628: LOG: DB node id: 1 backend pid: 2644 statement: SELECT now();

それでも、内容を理解したうえでキャッシュを行いたいユースケースが存在することから、今回のリリースではクエリキャッシュを強制的に作成する機能が追加されました。クエリの先頭に /*FORCE QUERY CACHE*/ を付けて実行することで、クエリキャッシュを強制的に作成できるようになります。

以下のようにクエリを実行することで、キャッシュされた時点のタイムスタンプが返されていることが確認できます。このキャッシュは Pgpool-II を再起動するまで保持されます。

postgres=> /*FORCE QUERY CACHE*/SELECT now();
now
------------------------------
2025-06-12 17:14:47.297804+09
(1 行)

postgres=> /*FORCE QUERY CACHE*/SELECT now();
now
------------------------------
2025-06-12 17:14:47.297804+09
(1 行)

さらに、ログにもキャッシュが利用されていることが記録されています。

2025-06-12 17:14:47.297: psql pid 2621: LOG: DB node id: 0 backend pid: 2901 statement: /*FORCE QUERY CACHE*/SELECT now(); 
2025-06-12 17:14:50.138: psql pid 2621: LOG: fetch from memory cache 
2025-06-12 17:14:50.138: psql pid 2621: DETAIL: query result fetched from cache. statement: /*FORCE QUERY CACHE*/SELECT now();

また /*NO QUERY CACHE*/ を冒頭に付記して宣言しても、 宣言したクエリキャッシュを削除することは出来ません。 /*NO QUERY CACHE*/ はキャッシュエントリが作成されないようにするだけなためです。

Pgpool-II を再起動することなく作成したクエリを削除する場合は、後述する PGPOOL SET CACHE DELETE コマンドか、pcp_invalidate_query_cache コマンドを使用する必要があります。

新しい PGPOOL SET CACHE DELETE コマンド

登録されているクエリキャッシュを削除する PGPOOL SET CACHE DELETE コマンドが追加されました。引数としてクエリの文字列を渡すことによってクエリキャッシュを指定して削除することができます。

postgres=> /*FORCE QUERY CACHE*/SELECT now();
              now
-------------------------------
 2025-06-12 09:58:49.983346+09
(1 行)

postgres=> PGPOOL SET CACHE DELETE '/*FORCE QUERY CACHE*/SELECT now();';
NOTICE:  query cache deleted. query: "/*FORCE QUERY CACHE*/SELECT now();"
SET
postgres=> /*FORCE QUERY CACHE*/SELECT now();
              now
-------------------------------
 2025-06-12 09:59:32.998492+09
(1 行)

引数に記述するクエリキャッシュはクエリ文字列は、末尾の「;」も含めて以前のクエリと完全に一致していなければならず、一致しない場合は以下エラーとなります。

postgres=> PGPOOL SET CACHE DELETE '/*FORCE QUERY CACHE*/SELECT now()'; -- 末尾の ';' が不足
NOTICE: query cache does not exist for query: "/*FORCE QUERY CACHE*/SELECT now()" -- クエリキャッシュが存在しないエラーとなる
SET

クエリキャッシュを削除する新しい PCP コマンド

すべてのクエリキャッシュを削除する PCP コマンド、pcp_invalidate_query_cache が追加されました。

今までは、クエリキャッシュの削除は Pgpool-II の再起動が必要でしたが、このコマンドを実行することによって Pgpool-II を再起動することなくクエリキャッシュを削除することができます。

「/*FORCE QUERY CACHE*/」で 「SELECT now();」 クエリをキャッシュします。

postgres=> /*FORCE QUERY CACHE*/SELECT now();
now
-------------------------------
2025-06-09 13:50:37.066191+09
(1 行)

その後、 pcp_invalidate_query_cache を実行すると、クエリキャッシュを削除することができます。

[postgres@server1 ~]$ pcp_invalidate_query_cache -h 192.168.100.50 -p 9898 -U pgpool -W
Password:
pcp_invalidate_query_cache -- Command Successful

postgres=> /*FORCE QUERY CACHE*/SELECT now(); -- クエリキャッシュが削除されているため再作成となる
now
-------------------------------
2025-06-09 13:50:56.561619+09
(1 行)

新しい設定パラメータ log_backend_messages

バックエンドからのメッセージログを出力する log_backend_messages パラメータが追加されました。terse または verbose に設定されている場合、バックエンドからのメッセージをログ出力します。

以下が受け取るメッセージ例です。

2025-06-09 14:00:57.494: psql pid 7579: LOG: last ParameterStatus message from backend 0 repeated 13 times

terse では、同じ種類のメッセージが同じバックエンドから送られてくると、その回数を記録し、次に異なる種類のメッセージが送られてきた時に繰り返し回数を報告します。そのため、繰り返している最中にセッションに対応するプロセスが強制終了すると、その分のログが出力されません。この場合でもすべてのログを出力するには、 verbose オプションを使用します。

verbose に設定したときのログ出力例は以下です。同一内容のメッセージであっても送られてくるたびに出力するためプロセスの強制終了によるログの損失は避けられますが、大量のメッセージがバックエンドから送られてくる場合は注意が必要です。

2025-06-09 13:58:16.390: child pid 7263: LOG: ParameterStatus message from backend 0
2025-06-09 13:58:16.390: child pid 7263: LOG: ParameterStatus message from backend 0
2025-06-09 13:58:16.390: child pid 7263: LOG: ParameterStatus message from backend 0

PostgreSQL 17 の SQL パーサの導入

Pgpool-II ではメジャーリリースするたびに、PostgreSQL の最新パーサを移植しています。今回のリリースでは PostgreSQL 17 の新しいパーサを取り込みました。

Pgpool-II の負荷分散機能では、SQL を解析して参照か更新かを判別し、どのノードに振り分けるかを決めています。そのため、PostgreSQL の新バージョンでの SQL の変更に対応するには、SQL パーサを移植する必要があります。

PostgreSQL 17 での SQL のおもな変更点は以下のとおりです。

• MERGE への NOT MATCHED BY SOURCE と RETURNING 句の追加
• COPY オプションの ON_ERROR ignore と LOG_VERBOSITY の追加
• COPY FROM オプションの FORCE_NOT_NULLとFORCE_NULL で「*」 を使用した全列を指定できる機能の追加
• EXPLAIN への SERIALIZE と MEMORY オプションの追加
• ALTER TABLE で SET STATISTICS DEFAULT を用いて、デフォルトの統計上情報ターゲットとする列の指定できる機能の追加
• ALTER TABLE での列の生成式を変更する機能の追加
• ALTER TABLE で .. SET ACCESS METHOD のデフォルトを指定できる機能の追加
• イベントトリガでログインイベントと REINDEX  を扱う機能の追加

Pgpool-II 4.6 では上記の変更点に対応しています。

Watchdog の hostname と heartbeat_hostname パラメータの IPv6 対応

これまで、IPv6 に対応していたパラメータは以下の通りです。

• backend_hostnameX
• listen_addresses
• pcp_listen_addresses

一方で、以下の Watchdog 関連パラメータはこれまで IPv6 に対応していませんでした。

• hostname
• heartbeat_hostname

今回のリリースにより、hostname と heartbeat_hostname も IPv6 に対応し、すべてのネットワーク関連パラメータで IPv6 アドレスを利用できるようになりました。

おわりに

今回は、Pgpool-II 4.6 の新機能について紹介しました。

Pgpool-II 4.6 では、より実用的で便利な機能が数多く追加・改善されています。PostgreSQL の高可用性構成や負荷分散の実現を検討されている方にとって、Pgpool-II は有力な選択肢です。ぜひこの機会に Pgpool-II の導入をご検討ください。