PostgreSQL の可用性を高める手段として、ストリーミングレプリケーションを手動で組んだ構成は今も多くの現場で稼働しています。しかし、プライマリ障害時の自動フェイルオーバーや、フェイルオーバー後のレプリカ再接続を人手で行うには限界があります。Patroni はこうした運用上の課題を解決するために設計された OSS の HA マネージャーで、2024年以降は PostgreSQL 公式ドキュメントでも言及されるほど実績が定着しています。
本記事では、既存のストリーミングレプリカ構成を維持しながら Patroni クラスタへ段階的に移行し、切り替え後の検証と万一の切り戻しまでを一連の手順として解説します。
ストリーミングレプリカ単体構成の運用上の課題
手動ストリーミングレプリカ構成では、プライマリが応答停止した際に自動でスタンバイを昇格させる仕組みがありません。よくあるつまずきとして、フェイルオーバースクリプトを自前実装したものの、ネットワーク分断時にスプリットブレインが発生するケースが挙げられます。pg_rewind や pg_basebackup を使った再同期も手動で行う必要があり、深夜の障害対応で手順を誤るリスクが残ります。
Patroni はこれらを次のように解決します。
- 分散キーバリューストア(DCS)による単一リーダー選出:etcd・Consul・ZooKeeper などの DCS を使ってリーダーロックを管理し、スプリットブレインを防ぎます。
- 自動フェイルオーバーと自動再同期:プライマリ障害を検知すると候補スタンバイを自動昇格し、旧プライマリが復帰した際は pg_rewind で自動的に追従させます。
- REST API による状態確認:patronictl コマンドや curl で現在のクラスタ状態、各ノードのレプリケーション lag、フェイルオーバー履歴を即座に確認できます。
移行前の前提確認と準備
移行を始める前に、現行環境の構成を整理しておくことが重要です。想定例として、プライマリ 1 台・スタンバイ 1 台の最小構成(PostgreSQL 16 系)を前提とします。DCS には etcd を使用し、ロードバランサーには HAProxy を配置する構成です。
etcd クラスタの別途構築
Patroni が依存する etcd は DB ノードと分離して構築することが推奨されています。最低 3 ノードの etcd クラスタを用意することで、etcd 自体の単一障害点をなくします。DB ノードと同居させるパターンも存在しますが、etcd の障害が PostgreSQL の書き込み停止に直結するため、小規模構成でも分離が望ましいです。etcd のバージョンは 2026年現在、3.5 系が LTS 相当として広く使われています。
パッケージと権限の準備
Patroni 本体は pip または OS パッケージで導入します。RHEL 系では PGDG リポジトリに patroni パッケージが含まれており、dnf install patroni patroni-etcd 一発で依存関係も解決できます。Debian/Ubuntu 系は apt install patroni で同様です。
設定ファイルは /etc/patroni/patroni.yml に配置するのが標準的です。postgresql OS ユーザーが読み書きできるよう権限を設定します。
段階的な移行手順
既存のストリーミングレプリカ構成を稼働させたまま Patroni を追加するアプローチを取ります。一度にすべてを切り替えるのではなく、スタンバイ側から Patroni エージェントを有効化し、動作確認後にプライマリへ適用することでリスクを下げます。
ステップ 1:スタンバイノードへ Patroni を導入する
スタンバイノードで既存の PostgreSQL サービスを停止し、Patroni の設定ファイルを作成します。patroni.yml には DCS への接続情報、PostgreSQL のデータディレクトリ、レプリケーションユーザーの認証情報を記載します。以下は設定ファイルの骨格です(想定例)。
scope: pg-cluster
namespace: /db/
name: standby1
etcd3:
hosts: etcd1:2379,etcd2:2379,etcd3:2379
bootstrap:
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
pg_hba:
- host replication replicator 0.0.0.0/0 scram-sha-256
postgresql:
listen: 0.0.0.0:5432
connect_address: standby1:5432
data_dir: /var/lib/pgsql/16/data
authentication:
replication:
username: replicator
password: 'xxxxxxxx'
superuser:
username: postgres
password: 'xxxxxxxx'
設定後、systemctl start patroni で起動します。初回起動時、Patroni は既存のデータディレクトリを検出してスタンバイとして DCS に登録します。patronictl -c /etc/patroni/patroni.yml list でクラスタ状態を確認し、当該ノードが Replica と表示されれば正常です。
ステップ 2:プライマリノードへ Patroni を導入してリーダーを引き渡す
スタンバイの動作が安定したことを確認してから、プライマリノードでも同様の手順で Patroni を導入します。name フィールドをプライマリのホスト名に変更し、systemctl start patroni を実行します。
プライマリ側で Patroni が起動すると、DCS にリーダーロックを取得してクラスタを初期化します。patronictl list で Leader/Replica が正しく表示されることを確認します。これ以降、PostgreSQL のサービス管理は systemd の postgresql ユニットではなく patroni ユニットが担います。postgresql サービスを直接 start/stop しないよう注意してください。Patroni の管理外でプロセスを再起動すると、DCS との状態が乖離して予期しない挙動を引き起こします。
切り替え後の動作検証
Patroni クラスタへの移行が完了したら、以下の観点で動作を検証します。フェイルオーバーが本番で初めて起きる事態は避けたいため、事前に計画的なスイッチオーバーを実施してタイムラインを把握しておくことが重要です。
手動スイッチオーバーのテスト
次のコマンドで、サービス中断を最小化しながら手動でリーダーを切り替えられます。
patronictl -c /etc/patroni/patroni.yml switchover pg-cluster \
--master primary1 --candidate standby1 --scheduled now
スイッチオーバー後、旧プライマリが Replica として自動的に再接続されるまでの時間(一般的には数秒~10 秒程度)を計測しておきます。HAProxy のヘルスチェックが正しくリーダーだけを読み書きエンドポイントとして認識しているかも同時に確認します。
フェイルオーバーのシミュレーション
プライマリの PostgreSQL プロセスを強制停止(kill -9 または pg_ctl stop -m immediate)し、Patroni が自動でスタンバイを昇格させることを確認します。DCS の ttl 設定(想定例では 30 秒)が経過するとリーダーロックが失効し、候補スタンバイが昇格します。この間のアプリケーション側でのタイムアウトと再接続挙動も記録しておくと、SLA の見積もりに役立ちます。
切り戻し手順と注意点
Patroni クラスタへの移行後に問題が生じた場合、手動ストリーミングレプリカ構成へ戻す手順が必要です。ただし切り戻しには WAL の扱いに慎重な注意が求められます。
Patroni の停止と手動管理への切り替え
両ノードで systemctl stop patroni を実行し、Patroni によるプロセス管理を停止します。次に、現在のリーダーノードで systemctl start postgresql を実行してプライマリとして起動します。
スタンバイ側は、Patroni が pg_rewind 等で変更したデータディレクトリの状態を確認した上で postgresql.conf と pg_hba.conf の設定を元に戻し、standby.signal(PostgreSQL 12 以降)を配置して起動します。
切り戻し時のよくあるつまずきとして、Patroni がスイッチオーバーやフェイルオーバーを実施した結果、移行前とは異なるノードがプライマリになっているケースがあります。patronictl history でフェイルオーバー履歴を確認し、どのノードが最新の WAL を持つかを特定してから切り戻し作業を始めてください。
etcd に残ったクラスタメタデータの削除
Patroni は DCS にクラスタの状態情報を書き込むため、切り戻し後も etcd にデータが残ります。再度 Patroni を利用する予定がない場合は patronictl remove pg-cluster でクリーンアップします。残留データがある状態で再度 Patroni を起動すると、DCS の旧情報をもとに意図しない昇格が起きる可能性があるため注意が必要です。
2026年現行環境での差分と注意点
2026年時点では Patroni 3.x 系が主流です。3.0 で導入された etcd3 ネイティブサポートにより、旧 etcd: キー(etcd v2 API を使用)と etcd3: キーの書き方が変わっています。古いドキュメントや Ansible ロールを流用する場合、両キーの混在によるトラブルがよくあるつまずきとして報告されているため、設定ファイルを見直す際は必ず使用する Patroni のバージョンに合わせた公式ドキュメントを参照してください。
PostgreSQL 側では 17 系がリリースされており、論理レプリケーションスロットの改善が行われています。Patroni 3.3 以降では PostgreSQL 17 の論理レプリケーションスロットを HA 環境でフェイルオーバー時に引き継ぐ synchronize_standby_slots オプションが正式サポートされました。CDC(Change Data Capture)など論理デコードを利用するアーキテクチャでは、この設定の有無がフェイルオーバー後のデータロスに直結するため、移行前に必ず確認します。
コンテナ環境(Kubernetes)での Patroni 利用が一般化したことで、Spilo(Zalando 製の Patroni コンテナイメージ)や Postgres Operator との組み合わせが増えています。ベアメタル・VM 上の移行手順とは設定ファイルの構造や DCS 接続方法が異なるため、公式ドキュメントで該当環境向けの設定例を参照することを推奨します。
RHEL 9 / Rocky Linux 9 環境では、SELinux のポリシーにより Patroni が etcd に接続できないケースが報告されています。audit2allow でポリシーを追加するか、移行作業中は Permissive モードに切り替えて原因を切り分けることが有効です。本番適用前に Enforcing モードでの動作確認を必ず行います。
「コマンドは打てる。次は”現場で通用する型”を最短で身につけたい」——そんなあなたへ。
ネットの断片的なTipsをコピペするだけでは、体系的な運用スキルはなかなか積み上がりません。リナックスマスター.JPの無料メルマガ「リナマガ」では、現場で実際に使うLinuxサーバー運用の考え方を、順を追って実務目線でお届けしています。いま登録された方には、安全なサーバー構築の「型」をまとめた『Linuxサーバー構築入門マニュアル(図解60P)』を完全無料でプレゼント中です。
>> 図解60P『Linux入門マニュアル』を無料で受け取る
(メルマガ登録は10秒・いつでも解除OK)
※ 「独学の時間がもったいない」「プロから現場の技術を最短で学びたい」という本気の方には、2日で実務レベルが身につく初心者向けハンズオンセミナーもご用意しています。
PR・広告
コマンド操作から基本運用までを手を動かして学べる定番書。記事で触れた技術の土台固めに。
※ Amazonのアソシエイトとして、当サイトは適格販売により収入を得ています。
