本文へ移動

これはセクションの複数ページ印刷用ビューです。 .

このページの通常のビューに戻る.

Patroni 4.1.5ドキュメント

PostgreSQL向けPatroniの高可用性ドキュメントの概要。
警告

Python 3.11+を使用する、メモリー制限のあるシステムでのPatroniの実行

たとえばvm.overcommit_memory=2（PostgreSQLで推奨）を設定したような、メモリー制限が厳しいシステムでPatroniを実行し、Python 3.11以降を使用すると、予期しない動作が見られる場合があります。

  • Patroniは正常に見える
  • PostgreSQLは動作を継続する
  • PatroniのREST APIが応答しなくなる
  • オペレーティングシステムは、PatroniがREST APIポートでリッスンしていると報告する
  • Patroniのログは正常に見える。ただし、次のメッセージが一度表示される場合がある：Exception ignored in thread started by: <object repr() failed>、MemoryError
  • カーネルのログに、not enough memory for the allocationなどのメッセージが含まれる場合がある

この動作は、Python 3.11+のバグ によって発生します。メモリーの条件が厳しく、十分な空きメモリーがない場合、新しいスレッドの起動が無期限にハングする可能性があります。

推奨される解決策

最近のPatroniリリース（4.1.1+、4.0.8+）では、システムのメモリーが逼迫する前に、起動の早い段階で必要なすべてのスレッドを開始することで、この問題の影響を軽減しています。

追加の推奨事項（Linux、glibc）

vm.overcommit_memory=2（PostgreSQLで推奨）を設定して実行する場合は、次の環境変数を設定してPatroniを起動することも推奨します。

  • MALLOC_ARENA_MAX=1 - マルチスレッドアプリケーション向けにglibcが割り当てる仮想メモリーの量を削減する
  • PG_MALLOC_ARENA_MAX= - Patroniが起動するPostgreSQLプロセスのMALLOC_ARENA_MAXの値をリセットする。

さらに、次のPatroni構成パラメーターを調整できます。

  • thread_stack_size - Patroniが起動するスレッドで使用するスタックサイズ。この値を小さくすると、Patroniプロセスのメモリー使用量が減ります。Patroniが設定するデフォルト値は512kBです。Patroniでスタックに関連するクラッシュが発生する場合は、thread_stack_sizeを増やしてください。それ以外の場合はデフォルト値で十分です。
  • thread_pool_size - リーダー選出やフェイルセーフの確認中に、Patroniが非同期タスクや他のメンバーとのREST API通信に使用するスレッドプールのサイズ。デフォルト値は5で、三つのノードからなるクラスターには十分です。
  • restapi.thread_pool_size - REST APIリクエストの処理に使用するスレッドプールのサイズ。デフォルト値は5で、最大五つのREST APIリクエストを並行処理できます。ただし、データベース接続を一つだけ使用するため、SQLクエリーを伴うリクエストは実質的に直列化されます。そのため、この値を増やしても通常は効果がありません。

Patroniは、Pythonを使用した高可用性（HA）PostgreSQLソリューションのテンプレートです。できるだけ幅広い環境で利用できるように、PatroniはZooKeeper 、etcd 、Consul 、Kubernetes など、さまざまな分散構成ストアをサポートしています。データセンターをはじめ、あらゆる場所にHA PostgreSQLを迅速にデプロイしたいデータベースエンジニア、DBA、DevOpsエンジニア、SREに役立つことを期待しています。

Patroniを「テンプレート」と呼ぶのは、あらゆる状況に適合したり、導入するだけで使えたりするレプリケーションシステムとは大きく異なるためです。独自の注意点があります。十分に理解して使用してください。PostgreSQLで高可用性を実現する方法はさまざまです。一覧はPostgreSQLドキュメント を参照してください。

現在サポートしているPostgreSQLのバージョン：9.3から18。

Citusユーザーへの注意：3.0以降のPatroniは、Postgresのデータベース拡張機能であるCitus と円滑に連携します。Patroniの高可用性とCitusの分散クラスターを組み合わせて使用する方法については、PatroniドキュメントのCitusサポートページ を参照してください。

Kubernetesユーザーへの注意：PatroniはKubernetes上でネイティブに動作できます。PatroniドキュメントのKubernetes の章を参照してください。

画像

1 - はじめに

Patroniの紹介、クイックスタート、高可用性の基本概念。

Patroniは、Pythonを使用した高可用性（HA）PostgreSQLソリューションのテンプレートです。PatroniはComposeのプロジェクトであるGovernor のフォークとして誕生し、多くの新機能を備えています。

背景については、次も参照してください。

開発状況

Patroniは活発に開発されており、貢献を受け付けています。詳しくは、貢献 のセクションを参照してください。

新しいリリースの情報はこちら でお知らせしています。

技術要件とインストール

各プラットフォームでのPatroniのインストールとアップグレードについては、こちら を参照してください。

PostgreSQLノード数の計画

Patroni/PostgreSQLのノードは、Patroni自身がRAFTを実装する場合を除き、DCSノードから独立しているため、最小ノード数に関する要件はありません。プライマリー一つとスタンバイ一つからなるクラスターでも問題なく動作します。後からスタンバイノードを追加できます。

2ノードのクラスター（プライマリーとスタンバイ）は一般的な構成で、高可用性を備えた自動フェイルオーバーを提供します。ただし、フェイルオーバー中は、障害が発生したノードが再参加するまで、一時的に冗長性がなくなることに注意してください。

DCSの要件：適切なコンセンサスと耐障害性を確保するには、DCS（etcd、ZooKeeper、Consul）を3または5ノードで実行する必要があります。単一のDCSクラスターに、異なるnamespaceとscopeの組み合わせを使用して、数百から数千のPatroniクラスターの情報を保存できます。

実行と構成

以下では、Patroniリポジトリをhttps://github.com/patroni/patroni からクローンしていることを前提とします。具体的には、構成ファイルの例であるpostgres0.ymlとpostgres1.ymlが必要です。pipでPatroniをインストールした場合は、gitリポジトリからこれらのファイルを取得し、以下の./patroni.pyをpatroniコマンドに置き換えられます。

以下のコマンドはetcd v2 APIを使用し、etcd 3.5など、--enable-v2をサポートするetcdのバージョンが必要です。etcd 3.6以降では、etcd 3.6でv2 APIのサポートが削除された ため、代わりにPatroniのetcd3構成を使用してください。

開始するには、それぞれ別のターミナルで次を実行します。

> etcd --data-dir=data/etcd --enable-v2=true
> ./patroni.py postgres0.yml
> ./patroni.py postgres1.yml

これで高可用性クラスターが起動します。YAMLファイルの設定を変更して、クラスターの動作がどのように変化するか試してください。一部のコンポーネントを強制終了して、システムの動作を確認してください。

postgres*.ymlファイルを追加すると、さらに大きなクラスターを作成できます。

PatroniはHAProxy の構成を提供しており、アプリケーションからクラスターのリーダーへ接続するための単一のエンドポイントを用意できます。構成するには、次を実行します。

> haproxy -f haproxy.cfg

> psql --host 127.0.0.1 --port 5000 postgres

YAMLによる構成

etcd、Consul、ZooKeeperの設定に関する詳しい情報は、こちら を参照してください。例はpostgres0.yml を参照してください。

環境変数による構成

環境変数を使用して設定を構成、上書きする方法については、こちら を参照してください。

レプリケーションの選択肢

Patroniは、デフォルトで非同期となるPostgresのストリーミングレプリケーションを使用します。Patroniの非同期レプリケーションでは、maximum_lag_on_failoverを設定できます。この設定により、フォロワーがリーダーから設定されたバイト数を超えて遅れている場合、そのフォロワーはフェイルオーバー時に昇格できなくなります。業務要件に応じて、この設定値を増減することを推奨します。より強い永続性の保証を得るため、同期レプリケーションを使用することもできます。詳しくは、レプリケーションモードのドキュメント を参照してください。

アプリケーションでスーパーユーザーを使用しない

アプリケーションから接続するときは、常にスーパーユーザー以外を使用してください。Patroniが正しく動作するには、データベースへのアクセスが必要です。アプリケーションでスーパーユーザーを使用すると、superuser_reserved_connections設定でスーパーユーザー用に予約された接続まで含めて、コネクションプール全体を使い切る可能性があります。コネクションプールがいっぱいになってPatroniがプライマリーにアクセスできなくなると、望ましくない動作につながります。

HAソリューションのテスト

HAソリューションのテストには、多くの変数が関係し、時間がかかります。複数のプラットフォームに対応するアプリケーションでは、特にそうです。この作業には、訓練を受けたシステム管理者またはコンサルタントが必要です。ドキュメントで詳しく扱いきれるものではありません。

そのうえで、インフラストラクチャーの次の要素は、必ずテストすることを推奨します。

  • ネットワーク（システムの手前にあるネットワークと、NIC［物理または仮想］自体）
  • ディスクI/O
  • ファイルディスクリプタの制限（Linuxではnofile）
  • RAM。oomkillerを無効にしていても、RAMを利用できなくなると問題が生じる可能性があります。
  • CPU
  • 仮想化環境のリソース競合（ハイパーバイザーのオーバーコミット）
  • cgroupによるあらゆる制限（上記に関連する可能性があります）
  • postgresプロセスに対するkill -9（postmasterは除く）。これはセグメンテーションフォールトの適切なシミュレーションになります。

行うべきでないのは、postmasterプロセスに対するkill -9です。プロセスを強制終了するだけでは、リソース枯渇やその他のインフラストラクチャー障害の実際の条件を再現できないためです。インフラストラクチャーが安全でなく、攻撃者がkill -9を実行できることを懸念しているのであれば、どのようなHAの仕組みでも解決できません。攻撃者は単にプロセスを再び強制終了するか、別の方法で混乱を引き起こすだけです。

2 - インストール

サポート対象プラットフォームにおけるPatroniのインストールとアップグレードの手順。

Mac OSの前提条件

Macに必要なソフトウェアをインストールするには、次を実行します。

brew install postgresql etcd haproxy libyaml python

Psycopg

psycopg2-2.8 以降、psycopg2のバイナリー版はデフォルトではインストールされなくなりました。ソースコードからインストールするには、Cコンパイラーとpostgresおよびpythonの開発用パッケージが必要です。Pythonでは依存関係をpsycopg2 OR psycopg2-binaryとして指定できないため、インストール方法を選択する必要があります。

次の選択肢があります。

  1. ディストリビューションのパッケージマネージャーを使用する
sudo apt-get install python3-psycopg2  # install psycopg2 module on Debian/Ubuntu
sudo yum install python3-psycopg2      # install psycopg2 on RedHat/Fedora/CentOS
  1. pipでPatroniをインストールするときに、依存関係の一覧 にpsycopg3、psycopg2、psycopg2-binaryのいずれかを指定する。

pipによる一般的なインストール

Patroniはpipでインストールできます。

pip install patroni[dependencies]

ここでdependenciesは空にするか、次のうち一つ以上を指定します。

etcdまたはetcd3
DCS（分散構成ストア）としてetcdを使用するためのpython-etcdモジュール

consul
DCSとしてConsulを使用するためのpy-consulモジュール

zookeeper
DCSとしてZookeeperを使用するためのkazooモジュール

exhibitor
DCSとしてExhibitorを使用するためのkazooモジュール（Zookeeperと同じ依存関係）

kubernetes
PatroniでDCSとしてKubernetesを使用するためのkubernetes モジュール

raft
DCSとしてPythonのRaft実装を使用するためのpysyncobjモジュール

aws
AWSコールバックを使用するためのboto3

jsonlogger
JSON形式のログ出力 を有効にするためのpython-json-loggerモジュール

systemd
sd_notify連携を使用するためのsystemd-python

all
上記のすべて（psycopg系を除く）

psycopg3
psycopg[binary]>=3.0.0モジュール

psycopg2
psycopg2>=2.5.4モジュール

psycopg2-binary
psycopg2-binaryモジュール

たとえば、psycopg3、DCSとしてのetcdの依存関係、AWSコールバックとともにPatroniをインストールするコマンドは、次のとおりです。

pip install patroni[psycopg3,etcd3,aws]

レプリカ作成スクリプトや独自のブートストラップスクリプトから呼び出す外部ツール（WAL-Eなど）は、Patroniとは別にインストールすることを推奨します。

Linuxへのパッケージのインストール

使用するオペレーティングシステム向けのPatroniパッケージが提供されている場合があります。Postgresコミュニティーは、次のシステム向けにパッケージを作成しています。

  • RHEL、RockyLinux、AlmaLinux。
  • DebianとUbuntu。
  • SUSE Enterprise Linux。

オペレーティングシステムの公式リポジトリにはないPythonモジュールなど、Patroniの直接の依存関係のパッケージもあります。

詳しくは、PGDGリポジトリ のドキュメントを参照してください。

RedHat Enterprise Linux派生のオペレーティングシステムでは、EPELのパッケージも必要になる場合があります。EPELリポジトリ のドキュメントを参照してください。

OS用のPGDGリポジトリをインストールしたら、Patroniをインストールできます。

注記

PatroniパッケージはPatroni開発者ではなく、Postgresコミュニティーがメンテナンスしています。サポートが必要な場合は、まずPostgres Slack で相談してください。

Debian派生システムへのインストール

上記 のとおりPGDGリポジトリをインストールしたら、次を実行してaptでPatroniをインストールします。

apt-get install patroni

RedHat派生システムへのインストール

上記 のとおりPGDGリポジトリをインストールしたら、RHEL 9とその派生システムで次を実行し、dnfを使用してetcd DCS付きのPatroniをインストールします。

dnf install patroni patroni-etcd

使用するRedHat派生ディストリビューションがetcdパッケージを提供していない場合は、PGDGからインストールできます。DCSを配置するノードで次を実行します。

dnf install 'dnf-command(config-manager)'
dnf config-manager --enable pgdg-rhel9-extras
dnf install etcd

必要であれば、リポジトリ名のRHELのバージョンを8に置き換えて、pgdg-rhel8-extrasにできます。RockyLinux、AlmaLinux、Oracle Linuxなどでも、リポジトリ名はpgdg-rhelN-extrasのままです。

SUSE Enterprise Linuxへのインストール

一部の依存関係のために、SUSE PackageHubリポジトリを有効にする必要がある場合があります。SUSE PackageHub のドキュメントを参照してください。

SLES 15で、上記 のとおりPGDGリポジトリをインストールしている場合、次のコマンドでPatroniをインストールできます。

zypper install patroni patroni-etcd

SUSE PackageHubリポジトリを有効にすると、etcdもインストールできます。

SUSEConnect -p PackageHub/15.5/x86_64
zypper install etcd

アップグレード

Patroniのアップグレードは非常に簡単です。ソフトウェアを更新し、クラスターの各ノードでPatroniデーモンを再起動するだけです。

ただし、Patroniデーモンを再起動すると、Postgresデータベースも再起動します。状況によってはクラスターのプライマリーノードでフェイルオーバーが発生する可能性があるため、Patroniデーモンの再起動が完了するまでクラスターをメンテナンスモードにすることを推奨します。

クラスターをメンテナンスモードにするには、Patroniノードのいずれかで次のコマンドを実行します。

patronictl pause --wait

次に、クラスターの各ノードでOSに応じたパッケージのアップグレードを実行します。

apt-get update && apt-get install patroni

各ノードでPatroniデーモンのプロセスを再起動します。

systemctl restart patroni

最後に、PatroniによるPostgresの監視を再開して、メンテナンスモードを終了します。

patronictl resume --wait

これでクラスターは、新しいバージョンのPatroniで完全に稼働する状態になります。

3 - Patroni 構成

Patroni 構成モデル、優先順位ルール、および検証ツール。

Patroni 構成には 3 タイプがあります。

  • グローバル 動的構成 。 これらのオプションは DCS (分散構成ストア) に保存され、すべてのクラスター ノードに適用されます。動的構成は、patronictl_edit_config ツールまたは Patroni REST API を使用していつでも設定できます。変更されたオプションがスタートアップ コンフィギュレーションの一部ではない場合、オプションはすべてのノードに非同期的に (次のウェイクアップ サイクル時に) 適用され、その後リロードされます。構成を適用するためにノードの再起動が必要な場合 (コンテキストが postmaster で、値が変更された PostgreSQL パラメータ の場合)、これを示す特別なフラグ pending_restart が members.data JSON に設定されます。さらに、ノードのステータスは "restart_pending": true を表示することでこれを示します。

  • ローカル 設定ファイル (patroni.yml)。 これらのオプションは構成ファイルで定義され、動的構成より優先されます。 patroni.yml は、SIGHUP を Patroni プロセスに送信するか、POST /reload REST-API リクエストを実行するか、patronictl_reload を実行することで、実行時に (Patroni を再起動せずに) 変更および再ロードできます。ローカル構成は、単一の YAML ファイルまたはディレクトリのいずれかになります。ディレクトリの場合、そのディレクトリ内のすべての YAML ファイルがソートされた順序で 1 つずつロードされます。キーが複数のファイルで定義されている場合、最後のファイル内のキーが優先されます。

  • 環境構成 。 環境変数を使用して、一部の「ローカル」構成パラメータを設定/上書きすることができます。環境構成は、動的環境で実行していて、一部のパラメーターが事前にわかっていない場合に非常に役立ちます (たとえば、docker 内で実行しているときに外部 IP アドレスを知ることはできません)。

重要なルール

PostgreSQL パラメータは Patroni によって制御されます

PostgreSQL パラメーターの一部は、プライマリーとレプリカで同じ値を保持する必要があります。これらについては、ローカルの patroni 設定ファイルまたは環境変数で設定された値は効果がありません。値を変更または設定するには、DCS の共有構成を変更する必要があります。以下は、そのようなパラメータの実際のリストとデフォルト値および最小値です。

  • max_connections: デフォルト値 100、最小値 25
  • max_locks_per_transaction: デフォルト値 64、最小値 32
  • max_worker_processes: デフォルト値 8、最小値 2
  • max_prepared_transactions: デフォルト値 0、最小値 0
  • wal_level: デフォルト値 hot_standby、受け入れられる値: hot_standby、replica、logical
  • track_commit_timestamp: デフォルト値はオフです

以下のパラメータの場合、PostgreSQL はプライマリーとすべてのレプリカ間で同じ値を必要としません。ただし、レプリカがいつでもプライマリーになる可能性を考慮すると、これらのパラメーターを異なる値に設定することはあまり意味がありません。したがって、Patroni は、これらの値の設定を 動的構成 に制限しています。

  • max_wal_senders: デフォルト値 10、最小値 3
  • max_replication_slots: デフォルト値 10、最小値 4
  • wal_keep_segments: デフォルト値 8、最小値 1
  • wal_keep_size: デフォルト値 128MB、最小値 16MB
  • wal_log_hints: オン

これらのパラメーターは検証され、それらが正常であるか、最小値を満たしているかが確認されます。

Patroni によって制御される Postgres パラメーターは他にもいくつかあります。

  • listen_addresses - postgresql.listen または PATRONI_POSTGRESQL_LISTEN 環境変数から設定されます
  • port - postgresql.listen または PATRONI_POSTGRESQL_LISTEN 環境変数から設定されます
  • cluster_name - scope または PATRONI_SCOPE 環境変数から設定されます
  • hot_standby: on

安全のため、上記のリストのパラメータは postgresql.conf に書き込まれ、引数のリストとして postgres に渡され、(wal_keep_segments と wal_keep_size を除き) ALTER SYSTEM すら超える最も高い優先順位が与えられます。

postgresql.listen や postgresql.data_dir のように、ローカルでのみ設定可能なパラメーターもいくつかあります。つまり、Patroni 設定ファイル 内で、または環境構成 の変数経由で設定します。ほとんどの場合、ローカル構成は動的構成をオーバーライドします。

ローカルまたは動的構成オプションを適用すると、次のアクションが実行されます。

  • ノードはまず、postgresql.base.conf ファイルがあるかどうか、または custom_conf パラメーターが設定されているかどうかを確認します。
  • custom_conf パラメータが設定されている場合、指定されたファイルが基本構成として使用され、postgresql.base.conf と postgresql.conf は無視されます。
  • custom_conf パラメーターが設定されておらず、postgresql.base.conf が存在する場合、名前が変更された “original” 構成が含まれており、基本構成として使用されます。
  • custom_conf も postgresql.base.conf もない場合、元の postgresql.conf は postgresql.base.conf に名前変更され、基本構成として使用されます。
  • 動的オプション (上記の例外を除く) は postgresql.conf にダンプされ、インクルードは postgresql.conf で基本構成 (postgresql.base.conf または custom_conf のファイルのいずれか) に設定されます。したがって、インクルードが存在するかどうかを確認するために構成ファイルを再度読み取ることなく、新しいオプションを適用できます。
  • Patroni がクラスターを管理するために必要な一部のパラメーターは、コマンド ラインを使用してオーバーライドされます。
  • 再起動を必要とするオプションが変更された場合 (pg_settings のコンテキストとそれらのオプションの実際の値を確認する必要があります)、そのノードに pending_restart フラグが設定されます。このフラグは再起動時にリセットされます。

パラメータは次の順序で適用されます (ランタイムに最も高い優先順位が与えられます)。

  1. ファイル postgresql.base.conf (または設定されている場合は custom_conf ファイル) からパラメータをロードします
  2. ファイル postgresql.conf からパラメータをロードします
  3. ファイル postgresql.auto.conf からパラメータをロードします
  4. -o --name=value を使用した実行時パラメーター

これにより、すべてのノードの構成 (2)、ALTER SYSTEM を使用した特定のノードの構成 (3) が可能になり、Patroni の実行に不可欠なパラメーターが強制されるようになります (4)。また、Patroni (1) を介さずに postgresql.conf を直接管理する構成ツールの余地も残ります。

共有メモリに関わる PostgreSQL パラメータ

PostgreSQL には、使用される共有メモリのサイズを決定するいくつかのパラメータがあります。

  • max_connections
  • max_prepared_transactions
  • max_locks_per_transaction
  • max_wal_senders
  • max_worker_processes

これらのパラメータを変更するには、PostgreSQL の再起動が必要であり、スタンバイ ノードの共有メモリ構造をプライマリー ノードよりも小さくすることはできません。

前に説明したように、Patroni は、これらの値の変更を 動的構成 経由に限定します。通常、これは次のもので構成されます。

  1. patronictl_edit_config (または REST API /config エンドポイント経由) による変更の適用
  2. patronictl_restart (または REST API /restart エンドポイント経由) によるノードの再起動

注: PostgreSQL ノードの再起動は、patronictl_restart コマンド、または REST API /restart エンドポイントを介して実行する必要があることに留意してください。Patroni デーモンの再起動による PostgreSQL の再起動の試み (たとえば systemctl restart patroni の実行) は、プライマリー ノードを再起動している場合、クラスター内でフェイルオーバーを引き起こす可能性があります。

ただし、これらの設定は共有メモリを管理するため、ノードを再起動するときは特に注意する必要があります。

  • これらの設定のいずれかの値を増加させたい場合:

    1. 最初にすべてのスタンバイを再起動します
    2. その後プライマリーを再起動します

  • これらの設定のいずれかの値を減少させたい場合:

    1. 最初にプライマリーを再起動します
    2. その後、すべてのスタンバイを再起動します

注: これらの設定のいずれかの値を減少させた後にすべてのノードを一度に再起動しようとすると、Patroni は変更を無視し、元の設定値でスタンバイを再起動するため、後でスタンバイを再度再起動する必要があります。Patroni は、スタンバイ ノードの pg_controldata で表示される値よりも低い値にこれらのパラメーターのいずれかを設定しようとすると、PostgreSQL が FATAL メッセージで終了するため、スタンバイが無限クラッシュ ループに陥るのを防ぐためにこれを行います。言い換えれば、プライマリーでのこれらの変更に関してスタンバイの pg_controldata がプライマリーと同期している場合にのみ、スタンバイの設定を減らすことができます。

詳細については、PostgreSQL 管理者の概要 を参照してください。

Patroni 構成パラメータ

また、次の Patroni 構成オプションは動的にのみ変更可能です:

  • ttl: 30
  • loop_wait: 10
  • retry_timeout: 10
  • maximum_lag_on_failover: 1048576
  • max_timelines_history: 0
  • check_timeline: false
  • postgresql.use_slots: true

これらのオプションを変更すると、Patroni は DCS に保存されている構成の関連セクションを読み取り、その実行時の値を変更します。

Patroni ノードは、構成が変更されるたびに、DCS オプションの状態を、Postgres データ ディレクトリにあるファイル patroni.dynamic.json にダンプします。これらのオプションが DCS に完全に存在しない場合、または無効な場合、リーダーのみがオンディスク ダンプからこれらのオプションを復元できます。

構成の生成と検証

Patroni は、Patroni ローカル構成 の生成と検証のためのコマンドライン インターフェイスを提供します。 patroni 実行可能ファイルを使用すると、次のことが可能になります。

  • サンプルのローカル Patroni 構成を作成します。
  • ローカルで実行されている PostgreSQL インスタンスの Patroni 構成ファイルを作成します (例: Patroni の統合 の準備ステップとして)。
  • 指定された Patroni 構成ファイルを検証します。

Patroni 構成のサンプル 

patroni --generate-sample-config [configfile]

説明

サンプルの Patroni 構成ファイルを yaml 形式で生成します。パラメータ値は 環境構成 を使用して定義されます。設定されていない場合は、Patroni で使用されるデフォルト値、または後でユーザーが定義すべき値のための #FIXME 文字列が使用されます。

一部のデフォルト値はローカル設定に基づいて定義されます。

  • postgresql.listen: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと標準の 5432 ポート。
  • postgresql.connect_address: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと標準の 5432 ポート。
  • postgresql.authentication.rewind: PostgreSQL バージョンをバイナリから定義でき、そのバージョンが 11 以降である場合にのみ定義されます。
  • restapi.listen: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと標準の 8008 ポート。
  • restapi.connect_address: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと標準の 8008 ポート。

パラメータ

configfile - 結果を保存するために使用される構成ファイルへのフルパス。指定しない場合、結果は stdout に送信されます。

実行中のインスタンスの Patroni 構成 

patroni --generate-config [--dsn DSN] [configfile]

説明

ローカルで実行されている PostgreSQL インスタンス用に Patroni 構成を yaml 形式で生成します。提供された DSN (優先されます) または PostgreSQL 環境変数 のいずれかが PostgreSQL 接続に使用されます。パスワードが指定されていない場合は、プロンプトから入力する必要があります。

ソース Postgres インスタンスで定義されたすべての非内部 GUC は、構成ファイル、postmaster コマンドライン、または環境変数のいずれで設定されたものであるかにかかわらず、次の Patroni 構成パラメーターのソースとして使用されます:

  • scope: cluster_name GUC 値;
  • postgresql.listen: listen_addresses および port GUC 値。
  • postgresql.data_dir: data_directory GUC 値;
  • postgresql.parameters: archive_command、restore_command、archive_cleanup_command、recovery_end_command、ssl_passphrase_command、hba_file、ident_file、config_file GUC 値。
  • bootstrap.dcs: 収集された他のすべての PostgreSQL GUC。

scope、postgresql.listen、または postgresql.data_dir が Postgres GUC から設定されていない場合は、それぞれの 環境構成 値が使用されます。

値の定義に適用されるその他のルールは次のとおりです。

  • name: PATRONI_NAME 環境変数値 (設定されている場合)、そうでない場合は現在のマシンのホスト名。
  • postgresql.bin_dir: 実行中のインスタンスから収集された Postgres バイナリへのパス。
  • postgresql.connect_address: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと、インスタンス接続に使用されるポートまたは port GUC 値。
  • postgresql.authentication.superuser: インスタンス接続に使用される構成。
  • postgresql.pg_hba: ソース インスタンスの hba_file から収集された行。
  • postgresql.pg_ident: ソース インスタンスの ident_file から収集された行。
  • restapi.listen: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと標準の 8008 ポート。
  • restapi.connect_address: gethostname が返す現在のマシンのホスト名を getaddrinfo で解決した IP アドレスと標準の 8008 ポート。

環境構成 を使用して定義された他のパラメーターも構成に含まれます。

パラメータ

configfile 結果を保存するために使用される構成ファイルへのフルパス。指定しない場合、結果は stdout に送信されます。

dsn GUC 値を取得するローカル PostgreSQL インスタンスのオプションの DSN 文字列。

Patroni 構成を検証する 

patroni --validate-config [configfile] [--ignore-listen-port | -i]

説明

指定された Patroni 構成を検証し、失敗したチェックに関する情報を出力します。

パラメータ

configfile 確認する構成ファイルへのフルパス。指定されない場合、またはファイルが存在しない場合は、PATRONI_CONFIGURATION 環境変数からの読み取りを試みます。設定されていない場合は、Patroni 環境変数 からの読み取りを試みます。

--ignore-listen-port | -i configfile を検証するときに、すでに使用されている listen ポートのバインド失敗を無視するためのオプションのフラグ。

--print | -p 正常に検証された後にローカル構成 (環境構成のオーバーライドを含む) を出力するためのオプションのフラグ。

3.1 - 動的構成設定

動的な構成設定は DCS に保存され、クラスター全体に適用されます。

動的構成は DCS (分散構成ストア) に保存され、すべてのクラスター ノードに適用されます。

動的構成を変更するには、patronictl_edit_config ツールまたは Patroni REST API を使用できます。

  • loop_wait: ループがスリープする秒数。デフォルト値: 10、可能な最小値: 1
  • ttl: リーダー ロックを取得する TTL (秒単位)。これは、自動フェイルオーバー プロセスが開始されるまでの時間と考えてください。デフォルト値: 30、可能な最小値: 20
  • retry_timeout: DCS および PostgreSQL 操作の再試行のタイムアウト (秒単位)。この値より短い DCS やネットワークの問題が発生しても、Patroni はリーダーをデモートしません。デフォルト値: 10、可能な最小値: 3
警告

loop_wait、retry_timeout、ttl の値を変更する際は、次のルールに従う必要があります。

loop_wait + 2 * retry_timeout <= ttl
  • maximum_lag_on_failover: フォロワーがリーダーの選出に参加するために許容される最大遅延バイト数。
  • primary_race_backoff: プライマリーからの WAL レプリケーションがまだ進行中の場合、スタンバイでのリーダーの競争を primary_race_backoff 秒延期します。これにより、Patroni が一時的に応答しなくなることによって引き起こされる不必要なフェイルオーバーを最小限に抑えることができます。デフォルト値: 0 (無効)。
  • maximum_lag_on_syncnode: 同期フォロワーが異常な候補とみなされ、健全な非同期フォロワーによってスワップされるまでに、同期フォロワーが遅れる可能性がある最大バイト数。 Patroni は、複数のフォロワーがある場合は最大レプリカ lsn を使用します。それ以外の場合は、リーダーの現在の wal lsn を使用します。デフォルトは -1 です。値が 0 以下に設定されている場合、Patroni は同期の異常なフォロワーを交換するアクションを実行しません。トランザクション量が多いときに Patroni が同期フォロワーを頻繁にスワップしないように、十分大きな値を設定してください。
  • max_timelines_history: DCS に保持されるタイムライン履歴アイテムの最大数。デフォルト値: 0。 0 に設定すると、完全な履歴が DCS に保存されます。
  • primary_start_timeout: フェイルオーバーがトリガーされる前にプライマリーが障害から回復できる時間 (秒単位)。デフォルトは 300 秒です。 0 に設定すると、可能であればクラッシュが検出された直後にフェイルオーバーが実行されます。非同期レプリケーションを使用する場合、フェイルオーバーによりトランザクションが失われる可能性があります。プライマリー障害における最悪の場合のフェイルオーバー時間は loop_wait + primary_start_timeout + loop_wait ですが、primary_start_timeout が 0 の場合は loop_wait のみです。耐久性と可用性のトレードオフに応じて値を設定します。
  • primary_stop_timeout: Postgres を停止するときに Patroni が待機できる秒数。synchronous_mode が有効な場合にのみ有効です。 > 0 に設定され、synchronous_mode が有効になっている場合、primary_stop_timeout で設定された値を超えて停止操作が実行されている場合、Patroni は postmaster に SIGKILL を送信します。耐久性と可用性のトレードオフに応じて値を設定します。パラメーターが設定されていない場合、または <= 0 に設定されている場合、primary_stop_timeout は適用されません。
  • synchronous_mode: 同期レプリケーション モードをオンにします。可能な値: off、on、quorum。このモードでは、リーダーが synchronous_standby_names の管理を担当し、最後に知られたリーダー、または同期レプリカの 1 つだけがリーダー レースに参加できます。同期モードでは、Patroni がトランザクションの耐久性を確保できない場合、書き込みの可用性が失われるという代償として、正常にコミットされたトランザクションがフェイルオーバー時に失われることはありません。詳細については、レプリケーションモードのドキュメント を参照してください。
  • synchronous_mode_strict: 使用可能な同期レプリカがない場合に同期レプリケーションを無効にせず、プライマリーへのすべてのクライアント書き込みをブロックします。優先順位に基づく同期モード（synchronous_mode: on）では、適切な同期スタンバイがない場合、Patroni 4.1.5 は synchronous_standby_names を * に設定します。詳細については、レプリケーションモードのドキュメント を参照してください。
  • synchronous_node_count: synchronous_mode が有効な場合、このパラメーターは Patroni によって使用され、同期スタンバイ インスタンスの正確な数を管理し、メンバーの参加と脱退に応じて DCS の状態と PostgreSQL の synchronous_standby_names パラメーターを調整します。パラメーターが対象となるノードの数よりも大きい値に設定されている場合、パラメーターは自動的に調整されます。デフォルトは 1 です。
  • failsafe_mode: DCS フェールセーフ モード を有効にします。デフォルトは false です。
  • postgresql:
    • use_pg_rewind: pg_rewind を使用するかどうか。デフォルトは false です。クラスターは data page checksums (initdb の --data-checksums オプション) で初期化するか、wal_log_hints を on に設定する必要があります。そうしないと、pg_rewind は機能しないことに注意してください。
    • use_slots: レプリケーション スロットを使用するかどうか。 PostgreSQL 9.4+ ではデフォルトは true です。
    • recovery_conf: フォロワーの構成時に recovery.conf に書き込まれる追加の構成設定。 PostgreSQL 12 には recovery.conf はもうありませんが、Patroni が透過的に処理するため、このセクションを引き続き使用できます。
    • parameters: {max_connections: 100, wal_level: "replica", max_wal_senders: 10, wal_log_hints: "on"} 形式の Postgres の構成パラメーター (GUC)。これらの多くは、レプリケーションが機能するために必要です。
    • parameters_primary: (オプション) プライマリーのロール固有のパラメーターをオーバーライドします。これらの値は、ベースの parameters にマージされ、同じパラメーターのベース値を上書きします。
    • parameters_replica: (オプション) レプリカのロール固有のパラメーターをオーバーライドします。これらの値は、ベースの parameters にマージされ、同じパラメーターのベース値を上書きします。
    • parameters_standby_leader: (オプション) standby_leader のロール固有のパラメーターをオーバーライドします。これらの値は、ベースの parameters にマージされ、同じパラメーターのベース値を上書きします。
    • pg_hba: Patroni が pg_hba.conf を生成するために使用する行のリスト。 hba_file PostgreSQL パラメータがデフォルト以外の値に設定されている場合、Patroni はこのパラメータを無視します。
      • - host all all 0.0.0.0/0 md5
      • - host replication replicator 127.0.0.1/32 md5: レプリケーションにはこのような行が必要です。
    • pg_hba_primary: (オプション) プライマリーのロール固有の pg_hba エントリ。これらは pg_hba を完全に置き換えます (マージなし)。定義されていない場合は、pg_hba が使用されます。
    • pg_hba_replica: (オプション) レプリカのロール固有の pg_hba エントリ。これらは pg_hba を完全に置き換えます (マージなし)。定義されていない場合は、pg_hba が使用されます。
    • pg_hba_standby_leader: (オプション) standby_leader のロール固有の pg_hba エントリ。これらは pg_hba を完全に置き換えます (マージなし)。定義されていない場合は、pg_hba が使用されます。
    • pg_ident: Patroni が pg_ident.conf を生成するために使用する行のリスト。 ident_file PostgreSQL パラメータがデフォルト以外の値に設定されている場合、Patroni はこのパラメータを無視します。
      • - mapname1 systemname1 pguser1
      • - mapname1 systemname2 pguser2
    • pg_ident_primary: (オプション) プライマリーのロール固有の pg_ident エントリ。これらは pg_ident を完全に置き換えます (マージなし)。定義されていない場合は、pg_ident が使用されます。
    • pg_ident_replica: (オプション) レプリカのロール固有の pg_ident エントリ。これらは pg_ident を完全に置き換えます (マージなし)。定義されていない場合は、pg_ident が使用されます。
    • pg_ident_standby_leader: (オプション) standby_leader のロール固有の pg_ident エントリ。これらは pg_ident を完全に置き換えます (マージなし)。定義されていない場合は、pg_ident が使用されます。
  • standby_cluster: このセクションが定義されている場合、スタンバイ クラスターをブートストラップします。
    • host: リモートノードのアドレス
    • port: リモート ノードのポート
    • primary_slot_name: レプリケーションに使用するリモート ノードのスロット。このパラメータはオプションであり、デフォルト値はインスタンス名から導出されます (関数 slot_name_from_member_name を参照)。
    • create_replica_methods: リモート プライマリーからスタンバイ リーダーをブートストラップするために使用できるメソッドの順序付きリスト。postgresql_settings で定義されたリストとは異なる場合があります。
    • restore_command: WAL レコードをリモート プライマリーからスタンバイ クラスターのノードに復元するコマンド。postgresql_settings で定義されたリストと異なる場合があります。
    • archive_cleanup_command: スタンバイ リーダーのクリーンアップ コマンド
    • recovery_min_apply_delay: WAL レコードをスタンバイ リーダーに実際に適用するまでの待機時間
  • member_slots_ttl: レプリカのシャットダウン時の物理レプリケーション スロットの保持時間。デフォルト値: 30min。以前の動作を維持したい場合は、これを 0 に設定します (メンバー キーの有効期限が DCS から切れると、スロットはすぐに削除されます)。この機能は、PostgreSQL 11 以降でのみ動作します。
  • slots: 永続的なレプリケーション スロットを定義します。これらのスロットは、スイッチオーバー/フェイルオーバー中に保持されます。存在しない永続スロットは Patroni によって作成されます。 PostgreSQL 11 以降では、すべてのノードに永続的な物理スロットが作成され、その位置は loop_wait 秒ごとに進められます。 11 よりも古い PostgreSQL バージョンの場合、永続的な物理レプリケーション スロットは現在のプライマリーでのみ維持されます。論理スロットは再起動によってプライマリーからスタンバイにコピーされ、その後 (必要に応じて) loop_wait 秒ごとに位置が進みます。論理スロット ファイルのコピーは、libpq 接続経由で、rewind またはスーパーユーザーの資格情報を使用して実行されます (postgresql.authentication セクションを参照)。レプリカ上の論理スロットの位置が以前のプライマリーより少し遅れている可能性が常にあります。そのため、アプリケーションは、フェイルオーバー後に一部のメッセージを 2 回受信する可能性に備えておく必要があります。最も簡単な方法は、confirmed_flush_lsn を追跡することです。永久レプリケーション スロットを有効にするには、postgresql.use_slots を true に設定する必要があります。永続的な論理レプリケーション スロットが定義されている場合、Patroni は hot_standby_feedback を自動的に有効にします。論理レプリケーション スロットのフェイルオーバーは、PostgreSQL 9.6 以前では安全でなく、PostgreSQL バージョン 10 にはいくつかの重要な機能が欠けているため、この機能は PostgreSQL 11+ でのみ動作します。
    • my_slot_name: 永続レプリケーション スロットの名前。永続スロット名が現在のノードの名前と一致する場合、そのスロットはこのノードには作成されません。 Patroni メンバーの名前と一致する名前の永続的な物理レプリケーション スロットを追加すると、Patroni は、対応するメンバーが応答しなくなった場合でも、作成されたスロットが削除されないことを保証します (通常であればこの状況では Patroni によってスロットが削除されるところです)。これは、メンバーによって使用されるレプリケーション スロットを一時的な障害時に持続させたい場合や、既存のメンバーを新しい Patroni クラスターにインポートする場合 (詳細については スタンドアロンを Patroni クラスターに変換する を参照) など、状況によっては便利ですが、Patroni の通常の機能への影響を考慮し、スロットが不要になった時点でこれらの名前の衝突が DCS に残存しないよう、オペレーターは注意を払う必要があります。
      • type: スロット タイプ。 physical または logical の可能性があります。スロットが論理スロットの場合は、database と plugin を追加で定義する必要があります。スロットが物理的な場合は、オプションで cluster_type を定義できます。
      • database: 論理スロットを作成するデータベース名。
      • plugin: 論理スロットのプラグイン名。
      • cluster_type: スロットを作成するクラスターのタイプ (primary または standby)。スロットはこのタイプのクラスターでのみ作成され、それ以外のクラスターでは作成されないか、既存のスロットが削除されます。
  • ignore_slots: Patroni が一致するスロットを無視するレプリケーション スロット プロパティのセットのリスト。この構成/機能などは、一部のレプリケーション スロットが Patroni の外部で管理されている場合に役立ちます。一致するプロパティの任意のサブセットが、スロットを無視させる原因になります。
    • name: レプリケーション スロットの名前。
    • type: スロット タイプ。 physical または logical を指定できます。スロットが論理スロットの場合は、database や plugin を追加で定義できます。
    • database: データベース名 (logical スロットと一致する場合)。
    • plugin: 論理デコード プラグイン (logical スロットに一致する場合)。

注: slots はハッシュマップですが、ignore_slots は配列です。たとえば:

slots:
  permanent_logical_slot_name:
    type: logical
    database: my_db
    plugin: test_decoding
  permanent_physical_slot_name:
    type: physical
  ...
ignore_slots:
  - name: ignored_logical_slot_name
    type: logical
    database: my_db
    plugin: test_decoding
  - name: ignored_physical_slot_name
    type: physical
  ...

注: PostgreSQL v11 以降を実行すると、Patroni はリーダーになる可能性のあるすべてのノードで物理レプリケーション スロットを維持するため、レプリカ ノードは他のノードで必要になる可能性がある場合に WAL セグメントを予約したままにします。ノードが存在せず、DCS 内のメンバー キーの有効期限が切れた場合、対応するレプリケーション スロットは member_slots_ttl の後に削除されます (デフォルト値は 30min)。ニーズに応じて保持期間を増減できます。あるいは、クラスター トポロジが静的 (名前が変更されない固定数のノード) の場合は、レプリカが一時的に停止している間にスロットの削除や WAL ファイルのリサイクルを回避するために、ノードの名前に対応する名前を使用して永続的な物理レプリケーション スロットを構成できます。

slots:
  node_name1:
    type: physical
  node_name2:
    type: physical
  node_name3:
    type: physical
  ...
警告

永続レプリケーション スロットは、primary/standby_leader からレプリカ ノードにのみ同期されます。つまり、アプリケーションはリーダー ノードからのみそれらを使用することになっています。これらをレプリカ ノードで使用すると、クラスター内の他のすべてのノードで pg_wal が無制限に増加します。この規則の例外は、Patroni メンバー名 (Patroni によって作成および維持される) に一致する物理スロットです。これらはノード間のレプリケーションに使用されるため、すべてのノード間で同期されます。

警告

nostream タグをスタンバイに設定すると、ノード自体とそのすべてのカスケード レプリカ (存在する場合) 上の永続論理レプリケーション スロットのコピーと同期が無効になります。

3.2 - YAML 構成設定

Patroni YAML 構成オプションとセクションの完全なリファレンス。

グローバル/ユニバーサル

  • thread_pool_size: リーダー競合またはフェールセーフ チェック中に、非同期タスクを実行し、REST API を介して他のメンバーと通信するために Patroni によって使用されるスレッド プールのサイズ。最小値は 5、デフォルト値は 5 です。
  • thread_stack_size: Patroni によって開始されるスレッドに使用されるスタック サイズを指定します。値は 64kB によってアライメントされる必要があります。最小値は 64kB 、デフォルト値 (Patroni によって設定) は 512kB です。
  • name: ホストの名前。クラスター内で一意である必要があります。
  • namespace: Patroni がクラスターに関する情報を保持する構成ストア内のパス。デフォルト値: “/service”
  • scope: クラスター名

ログ

  • type: ログの形式を設定します。 plain または json のいずれかになります。 json 形式を使用するには、jsonlogger がインストールされている必要があります。デフォルト値は plain です。
  • level: 一般的なログ レベルを設定します。デフォルト値は INFO です (Python ロギングのドキュメント を参照)
  • traceback_level: トレースバックが表示されるレベルを設定します。デフォルト値は ERROR です。 log.level=DEBUG を有効にした場合にのみトレースバックを表示したい場合は、DEBUG に設定します。
  • format: ログのフォーマット文字列を設定します。ログ タイプが plain の場合、ログ形式は文字列で指定することを推奨します。使用可能な属性については、LogRecord 属性 を参照してください。ログ タイプが json の場合、ログ形式は文字列に加えてリストにすることもできます。各リスト項目は LogRecord 属性に対応させることを推奨します。フィールド名のみが必要であり、%( と ) は省略する必要があることに注意してください。別のキー名でログ フィールドを出力する場合は、辞書キーがログ フィールドで、値がログに出力するフィールドの名前である辞書を使用します。デフォルト値は %(asctime)s %(levelname)s: %(message)s です。
  • dateformat: 日時フォーマット文字列を設定します。 (formatTime() ドキュメント を参照)
  • static_fields: ログにフィールドを追加します。このオプションは、ログ タイプが json に設定されている場合にのみ使用できます。
  • max_queue_size: Patroni は 2 段階のロギングを使用しています。ログ レコードはメモリ内のキューに書き込まれ、キューからログ レコードを取得して stderr またはファイルに書き込む別のスレッドがあります。内部キューの最大サイズはデフォルトで 1000 レコードによって制限されており、過去 1 時間 20 分までのログを保持するには十分なサイズです。
  • dir: アプリケーション ログを書き込むディレクトリ。ディレクトリは存在し、Patroni を実行するユーザーによって書き込み可能である必要があります。この値を設定すると、アプリケーションはデフォルトで 25MB のログを 4 個保持します。これらの保持値は、file_num および file_size を使用して調整できます (以下を参照)。
  • mode: ログ ファイルのアクセス許可 (0644 など)。指定しない場合、権限は現在の umask 値に基づいて設定されます。
  • file_num: 保持するアプリケーション ログの数。
  • file_size: ログ ローリングをトリガーする patroni.log ファイルのサイズ (バイト単位)。
  • loggers: このセクションでは、Python モジュールごとにログ レベルを再定義できます。
    • patroni.postmaster: WARNING
    • urllib3: DEBUG
  • deduplicate_heartbeat_logs: true に設定すると、同一のハートビート ログが連続して出力されなくなります。デフォルト値は false です。
警告

HA ループの実行時間は、リソースの枯渇や同様の問題によるフェイルオーバーを診断する際に非常に貴重な情報となる可能性があります。 deduplicate_heartbeat_logs が true に設定されている場合、(リーダーが変更されない限り) HA ループ実行のログは生成されないため、この潜在的に役立つ情報はログから取得できません。

ここでは、JSON 形式でログを記録するように Patroni を設定する方法の例を示します。

log:
   type: json
   format:
      - message
      - module
      - asctime: '@timestamp'
      - levelname: level
   static_fields:
      app: patroni

ブートストラップ構成

注記

Patroni が初めてクラスターを初期化し、設定が DCS に保存されると、YAML 構成の bootstrap.dcs セクションに対する今後の変更はすべて反映されなくなります。変更したい場合は、patronictl_edit_config または Patroni REST API を使用してください。

  • bootstrap:

    • dcs: このセクションは、新しいクラスターの初期化後に、指定された構成ストアの /<namespace>/<scope>/config に書き込まれます。クラスターのグローバル動的構成。 動的構成設定 で説明されているパラメーターのいずれかを bootstrap.dcs の下に置くことができ、Patroni が新しいクラスターを初期化 (ブートストラップ) した後、このセクションが構成ストアの /<namespace>/<scope>/config に書き込まれます。

    • method: このクラスターのブートストラップに使用するカスタム スクリプト。

      詳細については、カスタム ブートストラップ メソッドのドキュメント を参照してください。 initdb が指定されている場合は、デフォルトの initdb コマンドに戻ります。 initdb は、構成ファイルに method パラメーターが存在しない場合にもトリガーされます。

    • initdb: (オプション) initdb に渡されるオプションをリストします。

      • - data-checksums: 9.3 で pg_rewind が必要な場合は有効にする必要があります。
      • - encoding: UTF8: 新しいデータベースのデフォルトのエンコード。
      • - locale: UTF8: 新しいデータベースのデフォルトのロケール。

    • post_bootstrap または post_init: クラスターの初期化後に実行される追加のスクリプト。スクリプトは、接続文字列 URL (ユーザー名としてクラスター スーパーユーザーを含む) を受け取ります。 PGPASSFILE 変数は、pgpass ファイルの場所に設定されます。

Citus

Patroni と Citus の統合を有効にします。構成されている場合、Patroni はコーディネーターへの Citus ワーカー ノードの登録を処理します。 Citus サポートの詳細については、こちら を参照してください。

  • group: Citus グループ ID、整数。コーディネーターには 0 を使用し、ワーカーには 1、2 などを使用します。
  • database: citus 拡張機能を作成するデータベース。コーディネーターとすべてのワーカーで同じである必要があります。現在サポートされているデータベースは 1 つだけです。

Consul

ほとんどのパラメーターはオプションですが、host または url のいずれかを指定する必要があります。

  • host: Consul ローカル エージェントのホスト:ポート。
  • url: Consul ローカル エージェントの URL (形式: http(s)://host:port)。
  • port: (オプション) Consul ポート。
  • scheme: (オプション) http または https、デフォルトは http です。
  • token: (オプション) ACL トークン。
  • verify: (オプション) HTTPS リクエストの SSL 証明書を検証するかどうか。
  • cacert: (オプション) CA 証明書。存在する場合、検証が有効になります。
  • cert: (オプション) クライアント証明書を含むファイル。
  • key: (オプション) クライアント キーを含むファイル。キーが cert の一部である場合は空にすることができます。
  • dc: (オプション) 通信するデータセンター。デフォルトでは、ホストのデータセンターが使用されます。
  • consistency: (オプション) consul 整合性モードを選択します。可能な値は default、consistent、または stale です (詳細については consul API リファレンス を参照)
  • checks: (オプション) セッションに使用される Consul ヘルス チェックのリスト。デフォルトでは、空のリストが使用されます。
  • register_service: (オプション) scope パラメーターで定義された名前と、ノードのロールに応じたタグ (master、primary、replica、または standby-leader) でサービスを登録するかどうか。デフォルトは false です。
  • service_tags: (オプション) ロール (primary/replica/standby-leader) とは別に Consul サービスに追加する追加の静的タグ。デフォルトでは、空のリストが使用されます。
  • service_check_interval: (オプション) 登録された URL に対してヘルス チェックを実行する頻度。デフォルトは ‘5s’ です。
  • service_check_tls_server_name: (オプション) TLS 経由で接続するときに SNI ホストをオーバーライドします。consul エージェントチェック API リファレンス も参照してください。

token には、次の ACL 権限が必要です。

service_prefix "${scope}" {
    policy = "write"
}
key_prefix "${namespace}/${scope}" {
    policy = "write"
}
session_prefix "" {
    policy = "write"
}

Etcd

ほとんどのパラメーターはオプションですが、host、hosts、url、proxy、または srv のいずれかを指定する必要があります。

  • host: etcd エンドポイントのホスト:ポート。
  • hosts: host1:port1、host2:port2 などの形式の etcd エンドポイントのリスト。カンマ区切りの文字列または実際の yaml リストの可能性があります。
  • use_proxies: このパラメータが true に設定されている場合、Patroni は hosts をプロキシのリストと見なし、etcd クラスターのトポロジ検出を実行しません。
  • url: etcd の URL。
  • proxy: etcd のプロキシ URL。プロキシを使用して etcd に接続している場合は、url の代わりにこのパラメーターを使用します。
  • srv: クラスター自動検出のために SRV レコードを検索するドメイン。 Patroni は、指定されたドメインの SRV サービス名 (最初に成功するまでこの順序で) のクエリーを試行します: _etcd-client-ssl、_etcd-client、_etcd-ssl、_etcd、_etcd-server-ssl、_etcd-server。 _etcd-server-ssl または _etcd-server の SRV レコードが取得された場合、ETCD ピア プロトコルが使用され、利用可能なメンバーについて ETCD がクエリーされます。それ以外の場合は、SRV レコードのホストが使用されます。
  • srv_suffix: 検出中にクエリーされる SRV 名のサフィックスを構成します。このフラグを使用して、同じドメイン内の複数の etcd クラスターを区別します。 srv と組み合わせた場合にのみ機能します。たとえば、srv_suffix: foo と srv: example.org が設定されている場合、DNS SRV クエリーが作成されます:_etcd-client-ssl-foo._tcp.example.org (考えられるすべての ETCD SRV サービス名に対して同様)。
  • protocol: (オプション) http または https (指定しない場合は http が使用されます)。 url または proxy が指定されている場合は、それらからプロトコルを取得します。
  • username: (オプション) etcd 認証用のユーザー名。
  • password: (オプション) etcd 認証用のパスワード。
  • cacert: (オプション) CA 証明書。存在する場合、検証が有効になります。
  • cert: (オプション) クライアント証明書を含むファイル。
  • key: (オプション) クライアント キーを含むファイル。キーが cert の一部である場合は空にすることができます。

etcdv3

Patroni をプロトコル バージョン 3 経由で etcd クラスターと連携させたい場合は、Patroni 構成ファイルの etcd3 セクションを使用する必要があります。すべての構成パラメータは etcd の場合と同じです。

警告

プロトコル バージョン 2 で作成された Key は、プロトコル バージョン 3 では表示されず、その逆も同様であるため、Patroni 構成ファイルを更新するだけで etcd から etcd3 に切り替えることはできません。さらに、Patroni は etcd の gRPC ゲートウェイ (プロキシ) を使用して V3 API と通信します。これは、TLS 共通名認証が不可能であることを意味します。

ZooKeeper

  • hosts: ZooKeeper クラスター メンバーのリスト (形式: ′host1:port1′,′host2:port2′,′etc...′'host1:port1', 'host2:port2', 'etc...')。
  • use_ssl: (オプション) SSL が使用されているかどうか。デフォルトは false です。 false に設定すると、SSL 固有のパラメーターはすべて無視されます。
  • cacert: (オプション) CA 証明書。存在する場合、検証が有効になります。
  • cert: (オプション) クライアント証明書を含むファイル。
  • key: (オプション) クライアント キーを含むファイル。
  • key_password: (オプション) クライアント キーのパスワード。
  • verify: (オプション) 証明書を検証するかどうか。デフォルトは true です。
  • set_acls: (オプション) 設定した場合、作成する各 ZNode にデフォルトの ACL を適用するように Kazoo を構成します。 ACL では、x509 スキーマ (デフォルト)、または digest などの他のサポートされている ZooKeeper スキーマのいずれかを使用できます。これらは、キーが完全なプリンシパル (オプションでスキームの接頭辞が付けられる) であり、値がアクセス許可のリストであるディクショナリとして指定する必要があります。権限は、CREATE、READ、WRITE、DELETE、ADMIN、または ALL の 1 つ以上です。たとえば、set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]} です。
  • auth_data: (オプション) 接続に使用する認証資格情報。 scheme がキー、credential が値という形式の辞書である必要があります。デフォルトは空の辞書です。
注記

SSL をサポートするには、kazoo>=2.6.0 をインストールする必要があります。

Exhibitor

  • hosts: Exhibitor (ZooKeeper) ノードの初期リスト (形式: 「host1、host2、etc…」)。このリストは、Exhibitor (ZooKeeper) クラスター トポロジが変更されるたびに自動的に更新されます。
  • poll_interval: ZooKeeper および Exhibitor ノードのリストを Exhibitor から更新する頻度。
  • port: Exhibitor ポート。

Kubernetes

  • bypass_api_service: (オプション) Kubernetes API と通信する場合、Patroni は通常 Kubernetes サービスに依存し、そのアドレスは KUBERNETES_SERVICE_HOST 環境変数を介してポッド内で公開されます。 bypass_api_service が true に設定されている場合、Patroni はサービスの背後にある API ノードのリストを解決し、それらのノードに直接接続します。
  • namespace: (オプション) Patroni ポッドが実行されている Kubernetes 名前空間。デフォルト値は default です。
  • labels: {label1: value1, label2: value2} 形式のラベル。これらのラベルは、現在のクラスターに関連付けられている既存のオブジェクト (ポッドとエンドポイントまたは ConfigMaps) を検索するために使用されます。また、Patroni は、作成するすべてのオブジェクト (エンドポイントまたは ConfigMap) にそれらを設定します。
  • scope_label: (オプション) クラスター名を含むラベルの名前。デフォルト値は cluster-name です。
  • bootstrap_labels: (オプション) {label1: value1, label2: value2} 形式のラベル。これらのラベルは、Patroni ポッドの状態が initializing new cluster、running custom bootstrap script、starting after custom bootstrap、または creating replica のいずれかである場合にそのポッドに割り当てられます。
  • role_label: (オプション) ロールを含むラベルの名前 (primary、replica、またはその他のカスタム値)。 Patroni は、自身が実行されているポッドにこのラベルを設定します。デフォルト値は role です。
  • leader_label_value: (オプション) Postgres ロールが primary の場合のポッド ラベルの値。デフォルト値は primary です。
  • follower_label_value: (オプション) Postgres ロールが replica の場合のポッド ラベルの値。デフォルト値は replica です。
  • standby_leader_label_value: (オプション) Postgres ロールが standby_leader の場合のポッド ラベルの値。デフォルト値は primary です。
  • tmp_role_label: (オプション) ロールを含む一時ラベルの名前 (primary または replica)。このラベルの値には、対応するロールのデフォルトが常に使用されます。必要な場合のみ設定してください。
  • use_endpoints: (オプション) true に設定すると、Patroni は ConfigMaps の代わりにエンドポイントを使用してリーダーの選出を実行し、クラスターの状態を維持します。
  • pod_ip: (オプション) Patroni が実行されているポッドの IP アドレス。 この値は use_endpoints が有効な場合に必須であり、ポッドの PostgreSQL が昇格されるときにリーダー エンドポイント サブセットを設定するために使用されます。
  • ports: (オプション) Service オブジェクトにポートの名前がある場合、同じ名前が Endpoint オブジェクトに表示される必要があります。そうでない場合、サービスは機能しません。たとえば、サービスが {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}} として定義されている場合、kubernetes.ports: [{"name": "postgresql", "port": 5432}] を設定する必要があります。これにより、Patroni はリーダー エンドポイントのサブセットの更新にそれを使用します。このパラメータは、kubernetes.use_endpoints が設定されている場合にのみ使用されます。
  • cacert: (オプション) Kubernetes API SSL 証明書の検証中に使用する、信頼できる CA の証明書を含む CA_BUNDLE ファイルを指定します。指定されない場合、Patroni は ServiceAccount シークレットによって提供される値を使用します。
  • retriable_http_codes: (オプション) 再試行する K8s API からの HTTP ステータス コードのリスト。デフォルトでは、Patroni は、500、503、および 504、または K8s API 応答に retry-after HTTP ヘッダーがある場合に再試行します。

Raft (非推奨)

  • self_addr: Raft 接続をリッスンする ip:port。 self_addr はクラスターの他のノードからアクセスできる必要があります。設定されていない場合、ノードはコンセンサスに参加しません。

  • bind_addr: (オプション) Raft 接続をリッスンする ip:port。指定しない場合は、self_addr が使用されます。

  • partner_addrs: クラスター内の他の Patroni ノードのリスト (形式:

    ′ip1:port′,′ip2:port′,′etc...′'ip1:port', 'ip2:port', 'etc...'

    )

  • data_dir: Raft ログとスナップショットを保存するディレクトリ。指定しない場合は、現在の作業ディレクトリが使用されます。

  • password: (オプション) 指定されたパスワードで Raft トラフィックを暗号化します。cryptography Python モジュールが必要です。

  • min_timeout: (オプション) 基礎となる pysyncobj Raft 実装の最小選出タイムアウト (秒単位)。 3 * append_entries_period より大きくなければなりません。デフォルト： 0.4。

  • max_timeout: (オプション) 基礎となる pysyncobj Raft 実装の最大選出タイムアウト (秒単位)。 min_timeout より大きくなければなりません。デフォルト： 1.4。

  • connection_timeout: (オプション) データを受信しなかった接続が切断されたとみなされるまでの秒数。 max_timeout 以上である必要があります。デフォルト： 3.5。

  • append_entries_period: (オプション) ハートビート (append_entries) コマンドを送信する間隔 (秒単位)。 min_timeout の 3 分の 1 未満である必要があります。デフォルト： 0.1。

  • connection_retry_time: (オプション) オフライン ノードへの再接続試行間の秒単位の間隔。デフォルト： 5.0。

  • leader_fallback_timeout: (オプション) 過半数からの応答がないリーダーがフォロワー状態に戻るまでの秒数。 append_entries_period より大きくなければなりません。デフォルト： 30.0。

注記

これらのタイムアウト パラメーターは、デフォルトの pysyncobj タイムアウトが厳しすぎる高遅延ネットワークで役立ちます。次の制約を満たす必要があります: min_timeout > 3 * append_entries_period、max_timeout > min_timeout、connection_timeout >= max_timeout、および leader_fallback_timeout > append_entries_period。 Patroni は起動時にこれらを検証し、違反している場合は起動を拒否します。これらの値は実行時に変更できないため、再起動が必要です。

[!WARNING] これらの設定は、pysyncobj の選挙と接続のタイムアウトを緩和するだけです。 Patroni が Raft 操作に適用するコマンドごとの期限は延長されません。各 Raft コマンド (リーダー ロックのリフレッシュ、クラスター状態の書き込み) は依然として retry_timeout (デフォルト 10) 内で完了する必要があります。遅延が非常に長いリンク (ラウンドトリップ時間がおよそ数秒を超える場合) では、connection_timeout が RTT を大きく上回っていても、1 つのコマンドが retry_timeout を超える可能性があるため、DCS は到達不能であるように見え、プライマリーが降格される可能性があります。このようなリンクでは、loop_wait + 2 * retry_timeout <= ttl を維持しながら、それに応じて retry_timeout と ttl も引き上げる必要があります。

Raft 実装に関する短い FAQ

  • Q: コンセンサスを提供するすべてのノードをリストするにはどうすればよいですか?

    A: syncobj_admin -conn host:port -status ここで、host:port はクラスター ノードの 1 つのアドレスです。

  • Q: コンセンサスの一部であったノードが離脱し、その IP を他のノードに再利用できません。このノードをコンセンサスから削除するにはどうすればよいですか?

    A: syncobj_admin -conn host:port -remove host2:port2 ここで、host2:port2 はコンセンサスから削除するノードのアドレスです。

  • Q: syncobj_admin ユーティリティはどこで入手できますか?

    A: Patroni 依存関係である pysyncobj モジュール (Python RAFT 実装) と一緒にインストールされます。

  • Q: コンセンサスに追加せずに Patroni ノードを実行することは可能ですか?

    A: はい、Patroni 構成から raft.self_addr をコメントアウトするか削除してください。

  • Q: Patroni と PostgreSQL は 2 つのノードでのみ実行できますか?

    A: はい、3 番目のノードでは patroni_raft_controller を実行できます (Patroni と PostgreSQL は使用しません)。このような設定では、1 つのノードが一時的に失われても、プライマリーには影響しません。

PostgreSQL

  • postgresql:

    • authentication:

      • superuser:
        • username: スーパーユーザーの名前。初期化 (initdb) 中に設定され、後で postgres に接続するために Patroni によって使用されます。
        • password: スーパーユーザーのパスワード。初期化 (initdb) 中に設定されます。
        • sslmode: (オプション) sslmode 接続パラメータにマップします。これにより、クライアントはサーバーとの TLS ネゴシエーション モードのタイプを指定できます。各モードの動作の詳細については、PostgreSQL ドキュメント を参照してください。デフォルトのモードは prefer です。
        • sslkey: (オプション) sslkey 接続パラメータにマップします。これは、クライアントの証明書で使用される秘密キーの場所を指定します。
        • sslpassword: （任意）sslpassword 接続パラメーターに対応し、sslkeyで指定した秘密鍵のパスワードを指定します。
        • sslcert: (オプション) sslcert 接続パラメータにマップされ、クライアント証明書の場所を指定します。
        • sslrootcert: （任意）sslrootcert 接続パラメーターに対応します。クライアントがサーバー証明書の検証に使用する、1つ以上の認証局（CA）の証明書を含むファイルの場所を指定します。
        • sslcrl: (オプション) sslcrl 接続パラメータにマップされ、失効証明書リストを含むファイルの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
        • sslcrldir: (オプション) sslcrldir 接続パラメータにマップされ、失効証明書リストを含むファイルのあるディレクトリの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
        • sslnegotiation: （任意）sslnegotiation 接続パラメーターに対応し、SSLを使用する場合に、サーバーとのSSL暗号化のネゴシエーション方法を制御します。
        • gssencmode: （任意）gssencmode 接続パラメーターに対応します。サーバーと安全なGSS TCP/IP接続をネゴシエートするかどうか、またその優先順位を決定します。
        • channel_binding: (オプション) channel_binding 接続パラメータにマップされ、クライアントによるチャネル バインディングの使用を制御します。
      • replication:
        • username: レプリケーション ユーザー名。ユーザーは初期化中に作成されます。レプリカはこのユーザーを使用して、ストリーミング レプリケーション経由でレプリケーション ソースにアクセスします。
        • password: レプリケーションのパスワード。ユーザーは初期化中に作成されます。
        • sslmode: (オプション) sslmode 接続パラメータにマップします。これにより、クライアントはサーバーとの TLS ネゴシエーション モードのタイプを指定できます。各モードの動作の詳細については、PostgreSQL ドキュメント を参照してください。デフォルトのモードは prefer です。
        • sslkey: (オプション) sslkey 接続パラメータにマップします。これは、クライアントの証明書で使用される秘密キーの場所を指定します。
        • sslpassword: （任意）sslpassword 接続パラメーターに対応し、sslkeyで指定した秘密鍵のパスワードを指定します。
        • sslcert: (オプション) sslcert 接続パラメータにマップされ、クライアント証明書の場所を指定します。
        • sslrootcert: （任意）sslrootcert 接続パラメーターに対応します。クライアントがサーバー証明書の検証に使用する、1つ以上の認証局（CA）の証明書を含むファイルの場所を指定します。
        • sslcrl: (オプション) sslcrl 接続パラメータにマップされ、失効証明書リストを含むファイルの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
        • sslcrldir: (オプション) sslcrldir 接続パラメータにマップされ、失効証明書リストを含むファイルのあるディレクトリの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
        • sslnegotiation: （任意）sslnegotiation 接続パラメーターに対応し、SSLを使用する場合に、サーバーとのSSL暗号化のネゴシエーション方法を制御します。
        • gssencmode: （任意）gssencmode 接続パラメーターに対応します。サーバーと安全なGSS TCP/IP接続をネゴシエートするかどうか、またその優先順位を決定します。
        • channel_binding: (オプション) channel_binding 接続パラメータにマップされ、クライアントによるチャネル バインディングの使用を制御します。
      • rewind:
        • username: (オプション) pg_rewind のユーザーの名前。ユーザーは postgres 11+ の初期化中に作成され、必要なすべての 権限 が付与されます。
        • password: (オプション) pg_rewind のユーザーのパスワード。ユーザーは初期化中に作成されます。
        • sslmode: (オプション) sslmode 接続パラメータにマップします。これにより、クライアントはサーバーとの TLS ネゴシエーション モードのタイプを指定できます。各モードの動作の詳細については、PostgreSQL ドキュメント を参照してください。デフォルトのモードは prefer です。
        • sslkey: (オプション) sslkey 接続パラメータにマップします。これは、クライアントの証明書で使用される秘密キーの場所を指定します。
        • sslpassword: （任意）sslpassword 接続パラメーターに対応し、sslkeyで指定した秘密鍵のパスワードを指定します。
        • sslcert: (オプション) sslcert 接続パラメータにマップされ、クライアント証明書の場所を指定します。
        • sslrootcert: （任意）sslrootcert 接続パラメーターに対応します。クライアントがサーバー証明書の検証に使用する、1つ以上の認証局（CA）の証明書を含むファイルの場所を指定します。
        • sslcrl: (オプション) sslcrl 接続パラメータにマップされ、失効証明書リストを含むファイルの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
        • sslcrldir: (オプション) sslcrldir 接続パラメータにマップされ、失効証明書リストを含むファイルのあるディレクトリの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
        • sslnegotiation: （任意）sslnegotiation 接続パラメーターに対応し、SSLを使用する場合に、サーバーとのSSL暗号化のネゴシエーション方法を制御します。
        • gssencmode: （任意）gssencmode 接続パラメーターに対応します。サーバーと安全なGSS TCP/IP接続をネゴシエートするかどうか、またその優先順位を決定します。
        • channel_binding: (オプション) channel_binding 接続パラメーターにマップされ、クライアントによるチャネル バインディングの使用を制御します。

    • callbacks: 特定のアクションで実行するコールバック スクリプト。 Patroni は、アクション、ロール、クラスター名を渡します。 (記述方法の例として scripts/aws.py を参照してください。)

      • on_reload: 構成のリロードがトリガーされたときにこのスクリプトを実行します。
      • on_restart: postgres の再起動時に (ロールを変更せずに) このスクリプトを実行します。
      • on_role_change: postgres が昇格または降格されるときにこのスクリプトを実行します。
      • on_start: postgres の起動時にこのスクリプトを実行します。
      • on_stop: postgres が停止したときにこのスクリプトを実行します。

    • connect_address: IP アドレス + 他のノードおよびアプリケーションから Postgres にアクセスできるポート。

    • proxy_address: IP アドレス + Postgres の隣で実行されている接続プール (pgbouncer など) にアクセスできるポート。この値は、DCS のメンバー キーに proxy_url として書き込まれ、サービス検出に使用または役立つ可能性があります。

    • create_replica_methods: Patroni ノードを新しいレプリカに変換するための作成メソッドの順序付きリスト。 “basebackup” がデフォルトのメソッドです。他のメソッドはスクリプトを参照すると想定され、それぞれが独自の構成アイテムとして構成されます。詳細については、カスタム レプリカの作成方法のドキュメント を参照してください。

    • data_dir: Postgres データ ディレクトリの場所。既存 のもの、または Patroni によって初期化されるものです。

    • config_dir: Postgres 構成ディレクトリの場所。デフォルトはデータ ディレクトリです。 Patroni によって書き込み可能である必要があります。

    • bin_dir: (オプション) PostgreSQL バイナリ (pg_ctl、initdb、pg_controldata、pg_basebackup、postgres、pg_isready、pg_rewind) へのパス。指定されない場合、または空の文字列の場合は、PATH 環境変数を使用して実行可能ファイルが検索されます。

    • bin_name: (オプション) カスタム Postgres ディストリビューションを使用している場合、Postgres バイナリ名をオーバーライドできるようにします。

      • pg_ctl: (オプション) pg_ctl バイナリのカスタム名。
      • initdb: (オプション) initdb バイナリのカスタム名。
      • pg_controldata: (オプション) pg_controldata バイナリのカスタム名。
      • pg_basebackup: (オプション) pg_basebackup バイナリのカスタム名。
      • postgres: (オプション) postgres バイナリのカスタム名。
      • pg_isready: (オプション) pg_isready バイナリのカスタム名。
      • pg_rewind: (オプション) pg_rewind バイナリのカスタム名。

    • listen: Postgres がリッスンする IP アドレス + ポート。ストリーミング レプリケーションを使用している場合は、クラスター内の他のノードからアクセスできる必要があります。ポートコンポーネントが最後のアドレスの後ろにコロンで追加されている限り、カンマで区切られた複数のアドレスが許可されます (例: listen: 127.0.0.1,127.0.0.2:5432)。 Patroni は、このリストの最初のアドレスを使用して、PostgreSQL ノードへのローカル接続を確立します。

    • use_unix_socket: Patroni がクラスターへの接続に Unix ソケットの使用を優先することを指定します。デフォルト値は false です。 unix_socket_directories が定義されている場合、Patroni はその中の最初の適切な値を使用してクラスターに接続し、適切なものがない場合は tcp にフォールバックします。 postgresql.parameters で unix_socket_directories が指定されていない場合、Patroni はデフォルト値を使用する必要があると想定し、接続パラメーターから host を省略します。

    • use_unix_socket_repl: Patroni がレプリケーション ユーザー クラスター接続に UNIX ソケットの使用を優先することを指定します。デフォルト値は false です。 unix_socket_directories が定義されている場合、Patroni はその中の最初の適切な値を使用してクラスターに接続し、適切なものがない場合は tcp にフォールバックします。 postgresql.parameters で unix_socket_directories が指定されていない場合、Patroni はデフォルト値を使用する必要があると想定し、接続パラメーターから host を省略します。

    • pgpass: .pgpass パスワード ファイルへのパス。 Patroni は、pg_basebackup、post_init スクリプトを実行する前、およびその他の状況下でこのファイルを作成します。この場所は Patroni によって書き込み可能である必要があります。

    • recovery_conf: フォロワーの構成時に recovery.conf に書き込まれる追加の構成設定。

    • custom_conf : postgresql.base.conf の代わりに使用される、オプションのカスタム postgresql.conf ファイルへのパス。ファイルはすべてのクラスター ノードに存在し、PostgreSQL によって読み取り可能であり、実際の postgresql.conf 上の場所からインクルードされる必要があります。 Patroni は、このファイルの変更を監視したり、バックアップしたりしないことに注意してください。ただし、その設定は Patroni 独自の構成機能によってオーバーライドできます。詳細については、動的構成 を参照してください。

    • parameters: {ssl: "on", ssl_cert_file: "cert_file"} 形式の Postgres の構成パラメーター (GUC)。

    • parameters_primary: (オプション) プライマリーのロール固有のパラメーターをオーバーライドします。これらの値は、ベースの parameters にマージされ、同じパラメーターのベース値を上書きします。

    • parameters_replica: (オプション) レプリカのロール固有のパラメーターをオーバーライドします。これらの値は、ベースの parameters にマージされ、同じパラメーターのベース値を上書きします。

    • parameters_standby_leader: (オプション) standby_leader のロール固有のパラメーターをオーバーライドします。これらの値は、ベースの parameters にマージされ、同じパラメーターのベース値を上書きします。

    • pg_hba: Patroni が pg_hba.conf を生成するために使用する行のリスト。 hba_file PostgreSQL パラメータがデフォルト以外の値に設定されている場合、Patroni はこのパラメータを無視します。このパラメータを 動的構成 と組み合わせると、pg_hba.conf の管理が簡素化されます。

      • - host all all 0.0.0.0/0 md5
      • - host replication replicator 127.0.0.1/32 md5: レプリケーションにはこのような行が必要です。

    • pg_hba_primary: (オプション) プライマリーのロール固有の pg_hba エントリ。これらは pg_hba を完全に置き換えます (マージなし)。定義されていない場合は、pg_hba が使用されます。

    • pg_hba_replica: (オプション) レプリカのロール固有の pg_hba エントリ。これらは pg_hba を完全に置き換えます (マージなし)。定義されていない場合は、pg_hba が使用されます。

    • pg_hba_standby_leader: (オプション) standby_leader のロール固有の pg_hba エントリ。これらは pg_hba を完全に置き換えます (マージなし)。定義されていない場合は、pg_hba が使用されます。

    • pg_ident: Patroni が pg_ident.conf を生成するために使用する行のリスト。 ident_file PostgreSQL パラメータがデフォルト以外の値に設定されている場合、Patroni はこのパラメータを無視します。このパラメータを 動的構成 と組み合わせると、pg_ident.conf の管理が簡素化されます。

      • - mapname1 systemname1 pguser1
      • - mapname1 systemname2 pguser2

    • pg_ident_primary: (オプション) プライマリーのロール固有の pg_ident エントリ。これらは pg_ident を完全に置き換えます (マージなし)。定義されていない場合は、pg_ident が使用されます。

    • pg_ident_replica: (オプション) レプリカのロール固有の pg_ident エントリ。これらは pg_ident を完全に置き換えます (マージなし)。定義されていない場合は、pg_ident が使用されます。

    • pg_ident_standby_leader: (オプション) standby_leader のロール固有の pg_ident エントリ。これらは pg_ident を完全に置き換えます (マージなし)。定義されていない場合は、pg_ident が使用されます。

    • pg_ctl_timeout: start、stop、または restart を実行するときに pg_ctl が待機する時間。デフォルト値は 60 秒です。

    • use_pg_rewind: 以前のリーダーがレプリカとしてクラスターに参加するときに、そのノードで pg_rewind の使用を試みます。クラスターは data page checksums (initdb の --data-checksums オプション) で初期化するか、wal_log_hints を on に設定する必要があります。そうしないと、pg_rewind は機能しません。

    • rewind: (オプション) pg_rewind コマンドに渡すカスタム オプション。文字列および/または単一のキーと値を持つ辞書のリストとして指定できます。許可されないオプションには、target-pgdata、source-pgdata、source-server、write-recovery-conf、dry-run、restore-target-wal、config-file、no-ensure-shutdown、version、help があります。使用例:

      postgresql:
  rewind:
    - debug
    - progress
    - sync-method: fsync

    • remove_data_directory_on_rewind_failure: このオプションが有効な場合、Patroni は PostgreSQL データ ディレクトリを削除し、レプリカを再作成します。そうでない場合、新しいリーダーに追従しようとします。デフォルト値は false です。

    • remove_data_directory_on_diverged_timelines: Patroni は、タイムラインが分岐し、以前のプライマリーが新しいプライマリーからストリーミングを開始できないことを認識した場合、PostgreSQL データ ディレクトリを削除し、レプリカを再作成します。このオプションは、pg_rewind が使用できない場合に役立ちます。 PostgreSQL v10 以前でタイムライン分岐チェックを実行する際、Patroni はレプリケーション資格情報を使用して “postgres” データベースへの接続を試みます。したがって、そのようなアクセスは pg_hba.conf で許可される必要があります。デフォルト値は false です。

    • replica_method: basebackup 以外の create_replica_methods の各メソッドについて、同じ名前の構成セクションを追加します。少なくとも、実行される実際のスクリプトへのフルパスを含む “command” を含める必要があります。他の構成パラメータは、“parameter=value"の形式でスクリプトに渡されます。

    • pre_promote: フェイルオーバー中にリーダー ロックを取得した後、レプリカを昇格する前に実行するフェンシング スクリプト。スクリプトがゼロ以外のコードで終了した場合、Patroni はレプリカを昇格させず、リーダー キーを DCS から削除します。

    • before_stop: postgres を停止する直前に実行されるスクリプト。コールバックとは対照的に、このスクリプトは同期的に実行され、完了するまでシャットダウンをブロックします。このスクリプトのリターン コードは、その後シャットダウンが続行されるかどうかには影響しません。

REST API

  • restapi:
    • thread_pool_size: REST API リクエストを処理するために Patroni によって使用されるスレッド プールのサイズ。最小値は 5、デフォルト値は 5 です。
    • connect_address: Patroni の REST API にアクセスするための IP アドレス (またはホスト名) とポート。クラスターのすべてのメンバーがこのアドレスに接続できる必要があるため、Patroni セットアップがローカルホスト内のデモを目的としている場合を除き、このアドレスには “localhost” やループバック アドレス (たとえば “127.0.0.1”) を使用してはなりません。これは、HTTP ヘルス チェック (“listen” REST API パラメーターについては以下を参照してください) のエンドポイントとして機能し、ユーザー クエリー (直接または REST API 経由) や、リーダーの選出中にクラスター メンバーによって実行されるヘルス チェック (たとえば、リーダーがまだ実行されているかどうか、クエリーを実行しているノードよりも先の WAL 位置を持つノードが存在するかどうか、などを判断するため) のエンドポイントとしても機能します。connect_address は DCS のメンバー キーに入れられ、メンバー名をその REST API に接続するためのアドレスに変換できるようになります。
    • listen: Patroni が REST API をリッスンする IP アドレス (またはホスト名) とポート - 前述のように、参加ノード間で同じヘルス チェックとクラスター メッセージングも提供します。 HAProxy (または HTTP “OPTIONS” または “GET” チェックを実行できるその他のロード バランサー) のヘルスチェック情報を提供します。
    • authentication: (オプション)
      • username: 安全でない REST API エンドポイントを保護するための Basic 認証ユーザー名。
      • password: 安全でないREST APIエンドポイントを保護するBasic認証のパスワード。
    • certfile: （任意）PEM形式の証明書ファイルを指定します。certfileが未指定または空の場合、APIサーバーはSSLを使用せずに動作します。
    • keyfile: （任意）PEM形式の秘密鍵ファイルを指定します。
    • keyfile_password: （任意）keyfileを復号するパスワードを指定します。
    • cafile: （任意）クライアント証明書の検証に使用する、信頼されたCAの証明書を含むCA_BUNDLEファイルを指定します。
    • ciphers: （任意）許可する暗号スイートを指定します（例：“ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”）。
    • verify_client: （任意）none（デフォルト）、optional、requiredのいずれか。noneの場合、REST APIはクライアント証明書を検証しません。requiredの場合、すべてのREST API呼び出しでクライアント証明書が必要です。optionalの場合、安全でないすべてのREST APIエンドポイントでクライアント証明書が必要です。requiredでは、証明書の署名検証に成功するとクライアント認証が成功します。optionalでは、PUT、POST、PATCH、DELETEの要求だけでクライアント証明書を検証します。
    • allowlist: （任意）安全でないREST APIエンドポイントを呼び出せるホストの集合を指定します。各要素にはホスト名、IPアドレス、CIDR表記のネットワークアドレスを使用できます。デフォルトはallow allです。allowlistまたはallowlist_include_membersが設定されている場合、含まれないものはすべて拒否されます。
    • allowlist_include_members: （任意）trueの場合、DCSに登録された他のクラスターメンバーから安全でないREST APIエンドポイントへのアクセスを許可します。IPアドレスまたはホスト名は、メンバーのapi_urlから取得します。OSが外向きの接続に異なるIPを使用する場合がある点に注意してください。
    • http_extra_headers: （任意）REST APIサーバーがHTTP応答に追加情報を含めるためのHTTPヘッダー。
    • https_extra_headers: （任意）TLSが有効な場合に、REST APIサーバーがHTTP応答に追加情報を含めるためのHTTPSヘッダー。http_extra_headersに設定した追加情報も含まれます。
    • request_queue_size: （任意）Patroni REST APIが使用するTCPソケットの要求キューサイズを設定します。キューが満杯になると、それ以降の要求は「Connection denied」エラーになります。デフォルトは5です。
    • server_tokens: （任意）HTTPのServerヘッダーの値を設定します。
      • Minimal: ヘッダーには Patroni バージョンのみが含まれます (例: Patroni/4.0.0)。
      • ProductOnly: ヘッダーには製品名のみが含まれます (例: Patroni)。
      • Original (デフォルト): ヘッダーは元の動作を公開し、BaseHTTP および Python のバージョンを表示します (例: BaseHTTP/0.6 Python/3.12.3)。

次に、http_extra_headers と https_extra_headers の両方の例を示します。

restapi:
  listen: <listen>
  connect_address: <connect_address>
  authentication:
    username: <username>
    password: <password>
  http_extra_headers:
    'X-Frame-Options': 'SAMEORIGIN'
    'X-XSS-Protection': '1; mode=block'
    'X-Content-Type-Options': 'nosniff'
  cafile: <ca file>
  certfile: <cert>
  keyfile: <key>
  https_extra_headers:
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'

警告

  • restapi.connect_address は、特定の Patroni クラスターのすべてのノードからアクセス可能である必要があります。内部的には、Patroni がリーダー レース中にこれを使用して、レプリケーション ラグが最小限のノードを見つけます。
  • クライアント証明書の検証を有効にした場合 (restapi.verify_client が required に設定されている場合)、ctl.certfile、ctl.keyfile、ctl.keyfile_password で有効なクライアント証明書を提供することが必須です。指定しない場合、Patroni は正しく動作しません。

CTL

  • ctl: (オプション)
    • authentication:
      • username: 保護された REST API エンドポイントにアクセスするための基本認証ユーザー名。指定されない場合、patronictl は REST API “username” パラメーターに指定された値を使用します。
      • password: 保護された REST API エンドポイントにアクセスするための基本認証パスワード。指定されない場合、patronictl は REST API “password” パラメーターに指定された値を使用します。
    • insecure: SSL 証明書を検証せずに、REST API への接続を許可します。
    • cacert: REST API SSL 証明書の検証中に使用する、信頼できる CA の証明書を含む CA_BUNDLE ファイルまたはディレクトリを指定します。指定されない場合、patronictl は REST API “cafile” パラメーターに指定された値を使用します。
    • certfile: クライアント証明書を含むファイルを PEM 形式で指定します。
    • keyfile: クライアント秘密鍵を含むファイルを PEM 形式で指定します。
    • keyfile_password: クライアントのキーファイルを復号化するためのパスワードを指定します。

ウォッチドッグ

  • mode: off、automatic、または required。 off の場合、ウォッチドッグは無効になります。 automatic の場合、ウォッチドッグが使用可能な場合は使用されますが、使用できない場合は無視されます。 required の場合、ウォッチドッグを正常に有効にできない限り、ノードはリーダーになりません。
  • device: ウォッチドッグ デバイスへのパス。デフォルトは /dev/watchdog です。
  • safety_margin: ウォッチドッグのトリガーとリーダー キーの有効期限の間の安全マージンの秒数。

タグ

  • clonefrom: true または false。 true に設定すると、他のノードはブートストラップにこのノードの使用を優先する可能性があります (このノードから pg_basebackup で取得します)。 clonefrom タグが true に設定されているノードが複数ある場合、ブートストラップ元のノードがランダムに選択されます。デフォルト値は false です。
  • noloadbalance: true または false。 true に設定すると、ノードは GET /replica REST API ヘルスチェックに対して HTTP ステータス コード 503 を返すため、ロード バランシングから除外されます。デフォルトは false です。
  • replicatefrom: 複製元の別のレプリカの名前。カスケード レプリケーションをサポートするために使用されます。
  • nosync: true または false。 true に設定すると、ノードは同期レプリカとして選択されなくなります。
  • sync_priority: 整数。synchronous_mode が on に設定されている場合に、同期レプリカの選択中にこのノードが持つべき優先順位を制御します。優先順位の高いノードは、優先順位の低いノードよりも優先されます。 sync_priority が 0 または負の場合、そのようなノードは synchronous_standby_names PostgreSQL パラメーターに書き込むことができません (nosync: true と同様)。このパラメータは、pg_stat_replication ビューで報告される sync_priority 値とは逆の意味をもつことに注意してください。
  • nofailover: true または false は、このノードがリーダー レースに参加してリーダーになることを許可するかどうかを制御します。デフォルトは false で、このノード はリーダー レースに参加できることを意味します。
  • failover_priority: 整数。フェイルオーバー中にこのノードが持つべき優先順位を制御します。同じ量の WAL を受信/再生した場合、優先順位の高いノードが優先順位の低いノードよりも優先されます。ただし、優先度に関係なく、受信/再生 LSN の値が高いノードが優先されます。 failover_priority が 0 または負の場合、そのようなノードはリーダー レースに参加したり、リーダーになることは許可されません (nofailover: true と同様)。既知の制限: failover_priority は現在、クォーラムベースの同期レプリケーション では動作しません。
  • nostream: true または false。 true に設定すると、ノードは WAL をストリーミングするためにレプリケーション プロトコルを使用しません。代わりに、アーカイブのリカバリ (restore_command が構成されている場合) と pg_wal/pg_xlog ポーリングに依存します。また、ノード自体とそのすべてのカスケード レプリカ上の永続的な論理レプリケーション スロットのコピーと同期も無効になります。このタグをプライマリー ノードに設定しても効果はありません。
警告

nofailover または failover_priority のいずれか 1 つだけを指定します。 nofailover: true を指定することは failover_priority: 0 と同じであり、nofailover: false を指定するとノードの優先順位 1 が与えられます。

これらの定義済みタグに加えて、独自のタグを追加することもできます。

  • key1: true
  • key2: false
  • key3: 1.4
  • key4: "RandomString"

タグは REST API および patronictl_list で表示されます。これらのタグを使用してインスタンスの健全性を確認することもできます。タグがインスタンスに定義されていない場合、またはそれぞれの値がクエリー値と一致しない場合は、HTTP ステータス コード 503 が返されます。

3.3 - 環境構成の設定

Patroni 構成パラメーターをオーバーライドするための環境変数。

システム環境変数を使用して、Patroni 構成ファイルで定義されている構成パラメーターの一部をオーバーライドすることができます。このドキュメントには、Patroni によって処理されるすべての環境変数がリストされています。これらの変数を介して設定された値は、Patroni 構成ファイルで設定された値よりも常に優先されます。

グローバル/ユニバーサル

  • PATRONI_CONFIGURATION: PATRONI_CONFIGURATION 環境変数を介して Patroni の構成全体を設定できます。この場合、他の環境変数は一切考慮されません!
  • PATRONI_THREAD_POOL_SIZE: リーダー競合またはフェールセーフ チェック中に、非同期タスクを実行し、REST API を介して他のメンバーと通信するために Patroni によって使用されるスレッド プールのサイズ。最小値は 5、デフォルト値は 5 です。
  • PATRONI_THREAD_STACK_SIZE: Patroni によって開始されるスレッドに使用されるスタック サイズを指定します。値は 64kB によってアライメントされる必要があります。最小値は 64kB 、デフォルト値 (Patroni によって設定) は 512kB です。
  • PATRONI_NAME: Patroni の現在のインスタンスが実行されているノードの名前。クラスター内で一意である必要があります。
  • PATRONI_NAMESPACE: Patroni がクラスターに関する情報を保持する構成ストア内のパス。デフォルト値: 「/service」
  • PATRONI_SCOPE: クラスター名
  • PG_MALLOC_ARENA_MAX: postmaster プロセスの MALLOC_ARENA_MAX 環境変数のカスタム値。設定されていない場合、postmaster は MALLOC_ARENA_MAX 値を継承します。

ログ

  • PATRONI_LOG_TYPE: ログの形式を設定します。 plain または json のいずれかになります。 json 形式を使用するには、jsonlogger がインストールされている必要があります。デフォルト値は plain です。
  • PATRONI_LOG_LEVEL: 一般的なログ レベルを設定します。デフォルト値は INFO です (Python ロギングのドキュメント を参照)
  • PATRONI_LOG_TRACEBACK_LEVEL: トレースバックが表示されるレベルを設定します。デフォルト値は ERROR です。PATRONI_LOG_LEVEL=DEBUG を有効にした場合にのみトレースバックを表示したい場合は、DEBUG に設定します。
  • PATRONI_LOG_FORMAT: ログのフォーマット文字列を設定します。ログ タイプが plain の場合、ログ形式は文字列で指定することを推奨します。使用可能な属性については、LogRecord 属性 を参照してください。ログ タイプが json の場合、ログ形式は文字列に加えてリストにすることもできます。各リスト項目は LogRecord 属性に対応させることを推奨します。フィールド名のみが必要であり、%( と ) は省略する必要があることに注意してください。別のキー名でログ フィールドを出力する場合は、辞書キーがログ フィールドで、値がログに出力するフィールドの名前である辞書を使用します。デフォルト値は %(asctime)s %(levelname)s: %(message)s です。
  • PATRONI_LOG_DATEFORMAT: 日時フォーマット文字列を設定します。 (formatTime() ドキュメント を参照)
  • PATRONI_LOG_STATIC_FIELDS: ログに追加のフィールドを付加します。このオプションは、ログタイプが json に設定されている場合にのみ使用できます。例 PATRONI_LOG_STATIC_FIELDS="{app: patroni}"
  • PATRONI_LOG_MAX_QUEUE_SIZE: Patroni は 2 段階のロギングを使用しています。ログ レコードはメモリ内のキューに書き込まれ、キューからログ レコードを取得して stderr またはファイルに書き込む別のスレッドがあります。内部キューの最大サイズはデフォルトで 1000 レコードによって制限されており、過去 1 時間 20 分までのログを保持するには十分なサイズです。
  • PATRONI_LOG_DIR: アプリケーションログを書き込むディレクトリ。ディレクトリは存在し、Patroni を実行するユーザーによる書き込みが可能である必要があります。この環境変数を設定すると、アプリケーションはデフォルトで 25MB のログを 4 つ保持します。これらの保持値は、PATRONI_LOG_FILE_NUM と PATRONI_LOG_FILE_SIZE で調整できます (以下を参照)。
  • PATRONI_LOG_MODE: ログ ファイルのアクセス許可 (0644 など)。指定しない場合、権限は現在の umask 値に基づいて設定されます。
  • PATRONI_LOG_FILE_NUM: 保持するアプリケーション ログの数。
  • PATRONI_LOG_FILE_SIZE: ログ ローリングをトリガーする patroni.log ファイルのサイズ (バイト単位)。
  • PATRONI_LOG_LOGGERS: Python モジュールごとにログ レベルを再定義します。例 PATRONI_LOG_LOGGERS="{patroni.postmaster: WARNING, urllib3: DEBUG}"
  • PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS: true に設定すると、同一のハートビートログが連続して出力されなくなります。デフォルト値は false です。
警告

HA ループの実行時間は、リソースの枯渇や同様の問題によるフェイルオーバーを診断する際に非常に貴重な情報となる可能性があります。 PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS が true に設定されている場合、(リーダーが変更されない限り) HA ループ実行のログは生成されないため、この潜在的に役立つ情報はログから取得できません。

Citus

Patroni と Citus の統合を有効にします。構成されている場合、Patroni はコーディネーター上での Citus ワーカーノードの登録を管理します。Citus サポートの詳細については、こちら を参照してください。

  • PATRONI_CITUS_GROUP: Citus グループ ID、整数。コーディネーターには 0 を使用し、ワーカーには 1、2 などを使用します。
  • PATRONI_CITUS_DATABASE: citus 拡張を作成するデータベース。コーディネーターとすべてのワーカーで同じである必要があります。現在サポートされているデータベースは 1 つだけです。

Consul

  • PATRONI_CONSUL_HOST: Consul ローカル エージェントのホスト:ポート。
  • PATRONI_CONSUL_URL: Consul ローカル エージェントの URL (形式: http(s)://host:port)
  • PATRONI_CONSUL_PORT: (オプション) Consul ポート
  • PATRONI_CONSUL_SCHEME: (オプション) http または https、デフォルトは http
  • PATRONI_CONSUL_TOKEN: (オプション) ACL トークン
  • PATRONI_CONSUL_VERIFY: (オプション) HTTPS リクエストの SSL 証明書を検証するかどうか
  • PATRONI_CONSUL_CACERT: (オプション) CA 証明書。存在する場合、検証が有効になります。
  • PATRONI_CONSUL_CERT: (オプション) クライアント証明書を含むファイル
  • PATRONI_CONSUL_KEY: (オプション) クライアント キーを含むファイル。キーが証明書の一部である場合は空にすることができます。
  • PATRONI_CONSUL_DC: (オプション) 通信するデータセンター。デフォルトでは、ホストのデータセンターが使用されます。
  • PATRONI_CONSUL_CONSISTENCY: (オプション) Consul の整合性モードを選択します。可能な値は default、consistent、または stale です (詳細については Consul API リファレンス を参照)
  • PATRONI_CONSUL_CHECKS: (オプション) セッションに使用される Consul ヘルス チェックのリスト。デフォルトでは、空のリストが使用されます。
  • PATRONI_CONSUL_REGISTER_SERVICE: (オプション) スコープパラメーターで定義された名前と、ノードのロールに応じた master、primary、replica、standby-leader のタグを持つサービスを登録するかどうか。デフォルトは false です
  • PATRONI_CONSUL_SERVICE_TAGS: (オプション) ロール (primary/replica/standby-leader) とは別に Consul サービスに追加する追加の静的タグ。デフォルトでは、空のリストが使用されます。
  • PATRONI_CONSUL_SERVICE_CHECK_INTERVAL: (オプション) 登録された URL に対してヘルスチェックを実行する頻度
  • PATRONI_CONSUL_SERVICE_CHECK_TLS_SERVER_NAME: (オプション) TLS 経由で接続するときに SNI ホストをオーバーライドします。Consul エージェントチェック API リファレンス も参照してください。

Etcd

  • PATRONI_ETCD_PROXY: etcd のプロキシ URL。プロキシを使用して etcd に接続している場合は、PATRONI_ETCD_URL の代わりにこのパラメータを使用します。
  • PATRONI_ETCD_URL: etcd の URL、形式: http(s)://(username:password@)host:port
  • PATRONI_ETCD_HOSTS: ‘host1:port1’、‘host2:port2’ などの形式の etcd エンドポイントのリスト
  • PATRONI_ETCD_USE_PROXIES: このパラメーターが true に設定されている場合、Patroni は hosts をプロキシのリストとして考慮し、etcd クラスターのトポロジ検出を実行せず、hosts の固定リストに固執します。
  • PATRONI_ETCD_PROTOCOL: http または https (指定しない場合は http が使用されます)。 url または proxy が指定されている場合は、それらからプロトコルを取得します。
  • PATRONI_ETCD_HOST: etcd エンドポイントのホスト:ポート。
  • PATRONI_ETCD_SRV: クラスター自動検出のために SRV レコードを検索するドメイン。 Patroni は、指定されたドメインの SRV サービス名 (最初に成功するまでこの順序で) のクエリーを試行します: _etcd-client-ssl、_etcd-client、_etcd-ssl、_etcd、_etcd-server-ssl、_etcd-server。 _etcd-server-ssl または _etcd-server の SRV レコードが取得された場合、ETCD ピア プロトコルが使用され、利用可能なメンバーについて ETCD がクエリーされます。それ以外の場合は、SRV レコードのホストが使用されます。
  • PATRONI_ETCD_SRV_SUFFIX: 検出中にクエリーされる SRV 名のサフィックスを構成します。このフラグを使用して、同じドメイン内の複数の etcd クラスターを区別します。 PATRONI_ETCD_SRV と組み合わせた場合にのみ機能します。たとえば、PATRONI_ETCD_SRV_SUFFIX=foo と PATRONI_ETCD_SRV=example.org が設定されている場合、DNS SRV クエリーが作成されます:_etcd-client-ssl-foo._tcp.example.org (考えられるすべての ETCD SRV サービス名に対して同様)。
  • PATRONI_ETCD_USERNAME: etcd 認証用のユーザー名。
  • PATRONI_ETCD_PASSWORD: etcd 認証用のパスワード。
  • PATRONI_ETCD_CACERT: CA 証明書。存在する場合、検証が有効になります。
  • PATRONI_ETCD_CERT: クライアント証明書を含むファイル。
  • PATRONI_ETCD_KEY: クライアント キーを含むファイル。キーが証明書の一部である場合は空にすることができます。

Etcdv3

Etcdv3 の環境名は etcd の場合と似ており、変数名に ETCD の代わりに ETCD3 を使用する必要があるだけです。例: PATRONI_ETCD3_HOST、PATRONI_ETCD3_CACERT など。

警告

プロトコル バージョン 2 で作成されたキーは、プロトコル バージョン 3 では表示されず、その逆も同様であるため、Patroni 構成を更新するだけでは etcd から Etcdv3 に切り替えることはできません。さらに、Patroni は etcd の gRPC ゲートウェイ (プロキシ) を使用して V3 API と通信します。これは、TLS 共通名認証が不可能であることを意味します。

ZooKeeper

  • PATRONI_ZOOKEEPER_HOSTS: ZooKeeper クラスター メンバーのカンマ区切りリスト: “‘host1:port1’,‘host2:port2’,’etc…’"。各要素を引用符で囲むことが重要です。
  • PATRONI_ZOOKEEPER_USE_SSL: (オプション) SSL が使用されているかどうか。デフォルトは false です。 false に設定すると、SSL 固有のパラメーターはすべて無視されます。
  • PATRONI_ZOOKEEPER_CACERT: (オプション) CA 証明書。存在する場合、検証が有効になります。
  • PATRONI_ZOOKEEPER_CERT: (オプション) クライアント証明書を含むファイル。
  • PATRONI_ZOOKEEPER_KEY: (オプション) クライアント キーを含むファイル。
  • PATRONI_ZOOKEEPER_KEY_PASSWORD: (オプション) クライアント キーのパスワード。
  • PATRONI_ZOOKEEPER_VERIFY: (オプション) 証明書を検証するかどうか。デフォルトは true です。
  • PATRONI_ZOOKEEPER_SET_ACLS: (オプション) 設定した場合、作成する各 ZNode にデフォルトの ACL を適用するように Kazoo を構成します。 ACL では、x509 スキーマ (デフォルト)、または digest などの他のサポートされている ZooKeeper スキーマのいずれかを使用できます。これらは、キーが完全なプリンシパル (オプションでスキームの接頭辞が付けられる) であり、値がアクセス許可のリストであるディクショナリとして指定する必要があります。権限は、CREATE、READ、WRITE、DELETE、ADMIN、または ALL の 1 つ以上です。たとえば、set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]} です。
  • PATRONI_ZOOKEEPER_AUTH_DATA: (オプション) 接続に使用する認証資格情報。 scheme がキー、credential が値という形式の辞書である必要があります。デフォルトは空の辞書です。
注記

SSL をサポートするには、kazoo>=2.6.0 をインストールする必要があります。

Exhibitor

  • PATRONI_EXHIBITOR_HOSTS: Exhibitor (ZooKeeper) ノードの初期リスト (形式: ‘host1,host2,etc…’)。このリストは、Exhibitor (ZooKeeper) クラスターのトポロジーが変更されるたびに自動的に更新されます。
  • PATRONI_EXHIBITOR_PORT: Exhibitor ポート。

Kubernetes

  • PATRONI_KUBERNETES_BYPASS_API_SERVICE: (オプション) Kubernetes API と通信する場合、Patroni は通常 Kubernetes サービスに依存し、そのアドレスは KUBERNETES_SERVICE_HOST 環境変数を介してポッド内で公開されます。 PATRONI_KUBERNETES_BYPASS_API_SERVICE が true に設定されている場合、Patroni はサービスの背後にある API ノードのリストを解決し、それらのノードに直接接続します。
  • PATRONI_KUBERNETES_NAMESPACE: (オプション) Patroni ポッドが実行されている Kubernetes 名前空間。デフォルト値は default です。
  • PATRONI_KUBERNETES_LABELS: {label1: value1, label2: value2} 形式のラベル。これらのラベルは、現在のクラスターに関連付けられている既存のオブジェクト (ポッドとエンドポイントまたは ConfigMaps) を検索するために使用されます。また、Patroni は、作成するすべてのオブジェクト (エンドポイントまたは ConfigMap) にそれらを設定します。
  • PATRONI_KUBERNETES_SCOPE_LABEL: (オプション) クラスター名を含むラベルの名前。デフォルト値は cluster-name です。
  • PATRONI_KUBERNETES_BOOTSTRAP_LABELS: (オプション) {label1: value1, label2: value2} 形式のラベル。これらのラベルは、Patroni ポッドの状態が initializing new cluster、running custom bootstrap script、starting after custom bootstrap、または creating replica のいずれかである場合にそのポッドに割り当てられます。
  • PATRONI_KUBERNETES_ROLE_LABEL: (オプション) ロールを含むラベルの名前 (primary、replica、またはその他のカスタム値)。 Patroni は、実行されるポッドにこのラベルを設定します。デフォルト値は role です。
  • PATRONI_KUBERNETES_LEADER_LABEL_VALUE: (オプション) Postgres ロールが primary の場合のポッド ラベルの値。デフォルト値は primary です。
  • PATRONI_KUBERNETES_FOLLOWER_LABEL_VALUE: (オプション) Postgres ロールが replica の場合のポッド ラベルの値。デフォルト値は replica です。
  • PATRONI_KUBERNETES_STANDBY_LEADER_LABEL_VALUE: (オプション) Postgres ロールが standby_leader の場合のポッド ラベルの値。デフォルト値は primary です。
  • PATRONI_KUBERNETES_TMP_ROLE_LABEL: (オプション) ロールを含む一時ラベルの名前 (primary または replica)。このラベルの値には、対応するロールのデフォルトが常に使用されます。必要な場合のみ設定してください。
  • PATRONI_KUBERNETES_USE_ENDPOINTS: (オプション) true に設定すると、Patroni は ConfigMaps の代わりにエンドポイントを使用してリーダーの選出を実行し、クラスターの状態を維持します。
  • PATRONI_KUBERNETES_POD_IP: (オプション) Patroni が実行されているポッドの IP アドレス。 この値は PATRONI_KUBERNETES_USE_ENDPOINTS が有効な場合に必須であり、ポッドの PostgreSQL が昇格されるときにリーダー エンドポイント サブセットを設定するために使用されます。
  • PATRONI_KUBERNETES_PORTS: (オプション) Service オブジェクトにポートの名前がある場合、同じ名前が Endpoint オブジェクトに表示される必要があります。そうでない場合、サービスは機能しません。たとえば、サービスが {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}} として定義されている場合、PATRONI_KUBERNETES_PORTS='[{"name": "postgresql", "port": 5432}]' を設定する必要があります。これにより、Patroni はリーダー エンドポイントのサブセットの更新にそれを使用します。このパラメータは、PATRONI_KUBERNETES_USE_ENDPOINTS が設定されている場合にのみ使用されます。
  • PATRONI_KUBERNETES_CACERT: (オプション) Kubernetes API SSL 証明書の検証中に使用する、信頼できる CA の証明書を含む CA_BUNDLE ファイルを指定します。指定されない場合、Patroni は ServiceAccount シークレットによって提供される値を使用します。
  • PATRONI_RETRIABLE_HTTP_CODES: (オプション) 再試行する K8s API からの HTTP ステータス コードのリスト。デフォルトでは、Patroni は、500、503、および 504、または K8s API 応答に retry-after HTTP ヘッダーがある場合に再試行します。

Raft (非推奨)

  • PATRONI_RAFT_SELF_ADDR: Raft 接続をリッスンする ip:port。 self_addr はクラスターの他のノードからアクセスできる必要があります。設定されていない場合、ノードはコンセンサスに参加しません。
  • PATRONI_RAFT_BIND_ADDR: (オプション) Raft 接続をリッスンする ip:port。指定しない場合は、self_addr が使用されます。
  • PATRONI_RAFT_PARTNER_ADDRS: "'ip1:port1','ip2:port2'" 形式のクラスター内の他の Patroni ノードのリスト。各要素を引用符で囲むことが重要です。
  • PATRONI_RAFT_DATA_DIR: Raft ログとスナップショットを保存するディレクトリ。指定しない場合は、現在の作業ディレクトリが使用されます。
  • PATRONI_RAFT_PASSWORD: (オプション) 指定されたパスワードで Raft トラフィックを暗号化します。cryptography Python モジュールが必要です。
  • PATRONI_RAFT_MIN_TIMEOUT: (オプション) 基礎となる pysyncobj Raft 実装の最小選出タイムアウト (秒単位)。 3 * PATRONI_RAFT_APPEND_ENTRIES_PERIOD より大きくなければなりません。デフォルト： 0.4。
  • PATRONI_RAFT_MAX_TIMEOUT: (オプション) 基礎となる pysyncobj Raft 実装の最大選出タイムアウト (秒単位)。 PATRONI_RAFT_MIN_TIMEOUT より大きくなければなりません。デフォルト： 1.4。
  • PATRONI_RAFT_CONNECTION_TIMEOUT: (オプション) データを受信しなかった接続が切断されたとみなされるまでの秒数。 PATRONI_RAFT_MAX_TIMEOUT 以上である必要があります。デフォルト： 3.5。
  • PATRONI_RAFT_APPEND_ENTRIES_PERIOD: (オプション) ハートビート コマンドを送信する間隔 (秒単位)。 PATRONI_RAFT_MIN_TIMEOUT の 3 分の 1 未満である必要があります。デフォルト： 0.1。
  • PATRONI_RAFT_CONNECTION_RETRY_TIME: (オプション) オフライン ノードへの再接続試行間の秒単位の間隔。デフォルト： 5.0。
  • PATRONI_RAFT_LEADER_FALLBACK_TIMEOUT: (オプション) 過半数からの応答がないリーダーがフォロワー状態に戻るまでの秒数。 PATRONI_RAFT_APPEND_ENTRIES_PERIOD より大きくなければなりません。デフォルト： 30.0。
注記

Patroni は起動時にこれらの制約を検証し、違反している場合は起動を拒否します。これらの値は実行時に変更できないため、再起動が必要です。高遅延の制限などの詳細については、Raft 設定 を参照してください。

PostgreSQL

  • PATRONI_POSTGRESQL_LISTEN: Postgres がリッスンする IP アドレス + ポート。ポートコンポーネントが最後のアドレスの後ろにコロンで追加されている限り、カンマで区切られた複数のアドレスが許可されます (例: listen: 127.0.0.1,127.0.0.2:5432)。 Patroni は、このリストの最初のアドレスを使用して、PostgreSQL ノードへのローカル接続を確立します。
  • PATRONI_POSTGRESQL_CONNECT_ADDRESS: IP アドレス + 他のノードおよびアプリケーションから Postgres にアクセスできるポート。
  • PATRONI_POSTGRESQL_PROXY_ADDRESS: IP アドレス + Postgres の隣で実行されている接続プール (pgbouncer など) にアクセスできるポート。この値は、DCS のメンバー キーに proxy_url として書き込まれ、サービス検出に使用または役立つ可能性があります。
  • PATRONI_POSTGRESQL_DATA_DIR: Postgres データ ディレクトリの場所。既存であるか、Patroni によって初期化されます。
  • PATRONI_POSTGRESQL_CONFIG_DIR: Postgres 構成ディレクトリの場所。デフォルトはデータ ディレクトリです。 Patroni によって書き込み可能である必要があります。
  • PATRONI_POSTGRESQL_BIN_DIR: PostgreSQL バイナリへのパス。 (pg_ctl、initdb、pg_controldata、pg_basebackup、postgres、pg_isready、pg_rewind) デフォルト値は空の文字列で、PATH 環境変数が実行可能ファイルの検索に使用されることを意味します。
  • PATRONI_POSTGRESQL_BIN_PG_CTL: (オプション) pg_ctl バイナリのカスタム名。
  • PATRONI_POSTGRESQL_BIN_INITDB: (オプション) initdb バイナリのカスタム名。
  • PATRONI_POSTGRESQL_BIN_PG_CONTROLDATA: (オプション) pg_controldata バイナリのカスタム名。
  • PATRONI_POSTGRESQL_BIN_PG_BASEBACKUP: (オプション) pg_basebackup バイナリのカスタム名。
  • PATRONI_POSTGRESQL_BIN_POSTGRES: (オプション) postgres バイナリのカスタム名。
  • PATRONI_POSTGRESQL_BIN_IS_READY: (オプション) pg_isready バイナリのカスタム名。
  • PATRONI_POSTGRESQL_BIN_PG_REWIND: (オプション) pg_rewind バイナリのカスタム名。
  • PATRONI_POSTGRESQL_PGPASS: .pgpass パスワード ファイルへのパス。 Patroni は、pg_basebackup を実行する前および他の状況下でこのファイルを作成します。この場所は Patroni によって書き込み可能である必要があります。
  • PATRONI_REPLICATION_USERNAME: レプリケーション ユーザー名。ユーザーは初期化中に作成されます。レプリカはこのユーザーを使用して、ストリーミング レプリケーション経由でレプリケーション ソースにアクセスします。
  • PATRONI_REPLICATION_PASSWORD: レプリケーションのパスワード。ユーザーは初期化中に作成されます。
  • PATRONI_REPLICATION_SSLMODE: (オプション) sslmode 接続パラメータにマップします。これにより、クライアントはサーバーとの TLS ネゴシエーション モードのタイプを指定できます。各モードの動作の詳細については、PostgreSQL ドキュメント を参照してください。デフォルトのモードは prefer です。
  • PATRONI_REPLICATION_SSLKEY: (オプション) sslkey 接続パラメータにマップします。これは、クライアントの証明書で使用される秘密キーの場所を指定します。
  • PATRONI_REPLICATION_SSLPASSWORD: （任意）sslpassword 接続パラメーターに対応し、PATRONI_REPLICATION_SSLKEYで指定した秘密鍵のパスワードを指定します。
  • PATRONI_REPLICATION_SSLCERT: (オプション) sslcert 接続パラメータにマップされ、クライアント証明書の場所を指定します。
  • PATRONI_REPLICATION_SSLROOTCERT: （任意）sslrootcert 接続パラメーターに対応します。クライアントがサーバー証明書の検証に使用する、1つ以上の認証局（CA）の証明書を含むファイルの場所を指定します。
  • PATRONI_REPLICATION_SSLCRL: (オプション) sslcrl 接続パラメーターにマップされ、証明書失効リストを含むファイルの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
  • PATRONI_REPLICATION_SSLCRLDIR: (オプション) sslcrldir 接続パラメーターにマップされ、証明書失効リストを含むファイルが格納されたディレクトリの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
  • PATRONI_REPLICATION_SSLNEGOTIATION: （任意）sslnegotiation 接続パラメーターに対応し、SSLを使用する場合に、サーバーとのSSL暗号化のネゴシエーション方法を制御します。
  • PATRONI_REPLICATION_GSSENCMODE: （任意）gssencmode 接続パラメーターに対応します。サーバーと安全なGSS TCP/IP接続をネゴシエートするかどうか、またその優先順位を決定します。
  • PATRONI_REPLICATION_CHANNEL_BINDING: (オプション) channel_binding 接続パラメーターにマップされ、クライアントによるチャネル バインディングの使用を制御します。
  • PATRONI_SUPERUSER_USERNAME: スーパーユーザーの名前。初期化 (initdb) 中に設定され、後で postgres に接続するために Patroni によって使用されます。また、このユーザーは pg_rewind によって使用されます。
  • PATRONI_SUPERUSER_PASSWORD: スーパーユーザーのパスワード。初期化 (initdb) 中に設定されます。
  • PATRONI_SUPERUSER_SSLMODE: (オプション) sslmode 接続パラメータにマップします。これにより、クライアントはサーバーとの TLS ネゴシエーション モードのタイプを指定できます。各モードの動作の詳細については、PostgreSQL ドキュメント を参照してください。デフォルトのモードは prefer です。
  • PATRONI_SUPERUSER_SSLKEY: (オプション) sslkey 接続パラメータにマップします。これは、クライアントの証明書で使用される秘密キーの場所を指定します。
  • PATRONI_SUPERUSER_SSLPASSWORD: （任意）sslpassword 接続パラメーターに対応し、PATRONI_SUPERUSER_SSLKEYで指定した秘密鍵のパスワードを指定します。
  • PATRONI_SUPERUSER_SSLCERT: (オプション) sslcert 接続パラメータにマップされ、クライアント証明書の場所を指定します。
  • PATRONI_SUPERUSER_SSLROOTCERT: （任意）sslrootcert 接続パラメーターに対応します。クライアントがサーバー証明書の検証に使用する、1つ以上の認証局（CA）の証明書を含むファイルの場所を指定します。
  • PATRONI_SUPERUSER_SSLCRL: (オプション) sslcrl 接続パラメーターにマップされ、証明書失効リストを含むファイルの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
  • PATRONI_SUPERUSER_SSLCRLDIR: (オプション) sslcrldir 接続パラメーターにマップされ、証明書失効リストを含むファイルが格納されたディレクトリの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
  • PATRONI_SUPERUSER_SSLNEGOTIATION: （任意）sslnegotiation 接続パラメーターに対応し、SSLを使用する場合に、サーバーとのSSL暗号化のネゴシエーション方法を制御します。
  • PATRONI_SUPERUSER_GSSENCMODE: （任意）gssencmode 接続パラメーターに対応します。サーバーと安全なGSS TCP/IP接続をネゴシエートするかどうか、またその優先順位を決定します。
  • PATRONI_SUPERUSER_CHANNEL_BINDING: (オプション) channel_binding 接続パラメーターにマップされ、クライアントによるチャネル バインディングの使用を制御します。
  • PATRONI_REWIND_USERNAME: (オプション) pg_rewind のユーザーの名前。ユーザーは postgres 11+ の初期化中に作成され、必要なすべての 権限 が付与されます。
  • PATRONI_REWIND_PASSWORD: (オプション) pg_rewind のユーザーのパスワード。ユーザーは初期化中に作成されます。
  • PATRONI_REWIND_SSLMODE: (オプション) sslmode 接続パラメータにマップします。これにより、クライアントはサーバーとの TLS ネゴシエーション モードのタイプを指定できます。各モードの動作の詳細については、PostgreSQL ドキュメント を参照してください。デフォルトのモードは prefer です。
  • PATRONI_REWIND_SSLKEY: (オプション) sslkey 接続パラメータにマップします。これは、クライアントの証明書で使用される秘密キーの場所を指定します。
  • PATRONI_REWIND_SSLPASSWORD: （任意）sslpassword 接続パラメーターに対応し、PATRONI_REWIND_SSLKEYで指定した秘密鍵のパスワードを指定します。
  • PATRONI_REWIND_SSLCERT: (オプション) sslcert 接続パラメータにマップされ、クライアント証明書の場所を指定します。
  • PATRONI_REWIND_SSLROOTCERT: （任意）sslrootcert 接続パラメーターに対応します。クライアントがサーバー証明書の検証に使用する、1つ以上の認証局（CA）の証明書を含むファイルの場所を指定します。
  • PATRONI_REWIND_SSLCRL: (オプション) sslcrl 接続パラメーターにマップされ、証明書失効リストを含むファイルの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
  • PATRONI_REWIND_SSLCRLDIR: (オプション) sslcrldir 接続パラメーターにマップされ、証明書失効リストを含むファイルが格納されたディレクトリの場所を指定します。クライアントは、このリストに存在する証明書を持つサーバーへの接続を拒否します。
  • PATRONI_REWIND_SSLNEGOTIATION: （任意）sslnegotiation 接続パラメーターに対応し、SSLを使用する場合に、サーバーとのSSL暗号化のネゴシエーション方法を制御します。
  • PATRONI_REWIND_GSSENCMODE: （任意）gssencmode 接続パラメーターに対応します。サーバーと安全なGSS TCP/IP接続をネゴシエートするかどうか、またその優先順位を決定します。
  • PATRONI_REWIND_CHANNEL_BINDING: (オプション) channel_binding 接続パラメーターにマップされ、クライアントによるチャネル バインディングの使用を制御します。

REST API

  • PATRONI_RESTAPI_THREAD_POOL_SIZE: REST API リクエストを処理するために Patroni によって使用されるスレッド プールのサイズ。最小値は 5、デフォルト値は 5 です。
  • PATRONI_RESTAPI_CONNECT_ADDRESS: REST API にアクセスするための IP アドレスとポート。
  • PATRONI_RESTAPI_LISTEN: HAProxy のヘルスチェック情報を提供するために、Patroni がリッスンする IP アドレスとポート。
  • PATRONI_RESTAPI_USERNAME: 安全でない REST API エンドポイントを保護するための Basic 認証ユーザー名。
  • PATRONI_RESTAPI_PASSWORD: 安全でない REST API エンドポイントを保護するための Basic 認証パスワード。
  • PATRONI_RESTAPI_CERTFILE: PEM 形式の証明書を含むファイルを指定します。 certfile が指定されていないか空のままの場合、API サーバーは SSL を使用せずに動作します。
  • PATRONI_RESTAPI_KEYFILE: 秘密鍵を含むファイルを PEM 形式で指定します。
  • PATRONI_RESTAPI_KEYFILE_PASSWORD: キーファイルを復号化するためのパスワードを指定します。
  • PATRONI_RESTAPI_CAFILE: クライアント証明書の検証中に使用する、信頼できる CA の証明書を含むファイルを CA_BUNDLE で指定します。
  • PATRONI_RESTAPI_CIPHERS: （任意）許可する暗号スイートを指定します（例：“ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”）。
  • PATRONI_RESTAPI_VERIFY_CLIENT: none (デフォルト)、optional、または required。none の場合、REST API はクライアント証明書をチェックしません。required の場合、すべての REST API 呼び出しにクライアント証明書が必要です。optional の場合、すべての安全でない REST API エンドポイントにクライアント証明書が必要です。required が使用されている場合、証明書の署名の検証が成功するとクライアント認証は成功します。optional の場合、クライアント証明書がチェックされるのは PUT、POST、PATCH、および DELETE リクエストに対してのみです。
  • PATRONI_RESTAPI_ALLOWLIST: (オプション): 安全でない REST API エンドポイントの呼び出しを許可するホストのセットを指定します。単一の要素は、ホスト名、IP アドレス、または CIDR 表記を使用したネットワーク アドレスです。デフォルトでは allow all が使用されます。 allowlist または allowlist_include_members が設定されている場合、含まれていないものはすべて拒否されます。
  • PATRONI_RESTAPI_ALLOWLIST_INCLUDE_MEMBERS: (オプション): true に設定すると、DCS に登録されている他のクラスターメンバーから安全でない REST API エンドポイントへのアクセスが許可されます (IP アドレスまたはホスト名はメンバーの api_url から取得されます)。OS が送信接続に別の IP を使用する可能性があることに注意してください。
  • PATRONI_RESTAPI_HTTP_EXTRA_HEADERS: （任意）REST APIサーバーがHTTP応答に追加情報を含めるためのHTTPヘッダー。
  • PATRONI_RESTAPI_HTTPS_EXTRA_HEADERS: (オプション) HTTPS ヘッダーは、TLS が有効な場合に REST API サーバーが HTTP 応答とともに追加情報を渡せるようにします。これにより、http_extra_headers で設定された追加情報も渡されます。
  • PATRONI_RESTAPI_REQUEST_QUEUE_SIZE: (オプション): Patroni REST API が使用する TCP ソケットのリクエストキューサイズを設定します。キューがいっぱいになると、それ以降のリクエストでは “Connection denied” エラーが発生します。デフォルト値は 5 です。
  • PATRONI_RESTAPI_SERVER_TOKENS: (オプション) Server HTTP ヘッダーの値を構成します。Original (デフォルト) は元の動作を公開し、BaseHTTP および Python のバージョンを表示します (例: BaseHTTP/0.6 Python/3.12.3)。Minimal: ヘッダーには Patroni のバージョンのみが含まれます (例: Patroni/4.0.0)。ProductOnly: ヘッダーには製品名のみが含まれます (例: Patroni)。

警告

  • PATRONI_RESTAPI_CONNECT_ADDRESS は、特定の Patroni クラスターのすべてのノードからアクセス可能である必要があります。内部的には、Patroni がリーダー レース中にこれを使用して、レプリケーション ラグが最小限のノードを見つけます。
  • クライアント証明書の検証を有効にした場合 (PATRONI_RESTAPI_VERIFY_CLIENT が required に設定されている場合)、PATRONI_CTL_CERTFILE、PATRONI_CTL_KEYFILE、PATRONI_CTL_KEYFILE_PASSWORD で 有効なクライアント証明書 を提供することが必須です。提供しない場合、Patroni は正しく動作しません。

CTL

  • PATRONICTL_CONFIG_FILE: (オプション) 構成ファイルの場所。
  • PATRONI_CTL_USERNAME: (オプション) 保護された REST API エンドポイントにアクセスするための Basic 認証ユーザー名。指定されない場合、patronictl は REST API “username” パラメーターに指定された値を使用します。
  • PATRONI_CTL_PASSWORD: (オプション) 保護された REST API エンドポイントにアクセスするための Basic 認証パスワード。指定されない場合、patronictl は REST API “password” パラメーターに指定された値を使用します。
  • PATRONI_CTL_INSECURE: (オプション) SSL 証明書を検証せずに、REST API への接続を許可します。
  • PATRONI_CTL_CACERT: (オプション) REST API SSL 証明書の検証中に使用する、CA_BUNDLE ファイルまたは信頼できる CA の証明書が含まれるディレクトリを指定します。指定されない場合、patronictl は REST API “cafile” パラメーターに指定された値を使用します。
  • PATRONI_CTL_CERTFILE: (オプション) PEM 形式のクライアント証明書を含むファイルを指定します。
  • PATRONI_CTL_KEYFILE: (オプション) クライアント秘密鍵を含むファイルを PEM 形式で指定します。
  • PATRONI_CTL_KEYFILE_PASSWORD: (オプション) クライアントのキーファイルを復号化するためのパスワードを指定します。

4 - Patroni REST API

Patroni REST API エンドポイントと操作動作のリファレンス。

Patroni には豊富な REST API があり、リーダー競合中に Patroni 自身によって使用されたり、フェイルオーバー/スイッチオーバー/再初期化/再起動/リロードを実行するために patronictl ツールによって使用されたり、HTTP ヘルスチェックを実行するために HAProxy またはその他の種類のロードバランサーによって使用されたり、もちろん監視にも使用できます。以下に、Patroni REST API エンドポイントのリストを示します。

ヘルスチェックエンドポイント

すべてのヘルスチェック GET リクエストに対して、Patroni はノードのステータスを含む JSON ドキュメントを、HTTP ステータスコードとともに返します。JSON ドキュメントを望まない場合や必要がない場合は、GET の代わりに HEAD メソッドまたは OPTIONS メソッドの使用を検討してください。

  • Patroni REST API に対する次のリクエストは、Patroni ノードがリーダー ロック付きのプライマリーとして実行されている場合にのみ、HTTP ステータス コード 200 を返します。

    • GET /
    • GET /primary
    • GET /read-write

  • GET /standby-leader: Patroni ノードが スタンバイクラスタ のリーダーとして実行されている場合にのみ、HTTP ステータス コード 200 を返します。

  • GET /leader: Patroni ノードがリーダーロックを保持している場合、HTTP ステータスコード 200 を返します。GET /primary や GET /standby-leader とは異なり、PostgreSQL が primary または standby_leader として実行されているかどうかは判定条件に含まれません。

  • GET /replica: レプリカのヘルスチェックエンドポイント。 Patroni ノードが running 状態にあり、ロールが replica で、noloadbalance タグが設定されていない場合にのみ、HTTP ステータス コード 200 を返します。

  • GET /replica?replication_state=<required state>: レプリカ チェック エンドポイント。 replica からのチェックに加えて、レプリケーションの状態が必要な状態と一致するかどうかもチェックします。主に replication_state=streaming で使用し、アーカイブ リカバリでまだ追いついていないレプリカを除外するのに役立ちます。

  • GET /replica?lag=<max-lag>: レプリカ チェック エンドポイント。 replica からのチェックに加えて、レプリケーションの遅延もチェックし、指定された値を下回っている場合にのみステータス コード 200 を返します。 DCS のキー cluster.last_leader_operation は、パフォーマンス上の理由から、リーダー wal の位置とレプリカのレイテンシの計算に使用されます。 max-lag はバイト (整数) または人間が読み取り可能な値 (例: 16kB、64MB、1GB) で指定できます。

    • GET /replica?lag=1048576
    • GET /replica?lag=1024kB
    • GET /replica?lag=10MB
    • GET /replica?lag=1GB

  • GET /replica?tag_key1=value1&tag_key2=value2: レプリカ チェック エンドポイント。さらに、ユーザー定義タグ key1 および key2 と、yaml 構成管理の tags セクション内のそれぞれの値もチェックされます。タグがインスタンスに対して定義されていない場合、または yaml 設定内の値がクエリー値と一致しない場合は、HTTP ステータス コード 503 が返されます。

    次のリクエストでは、リーダーまたはスタンバイリーダーのステータスをチェックしているため、Patroni はユーザー定義のタグを一切適用せず、それらは無視されます。

    • GET /?tag_key1=value1&tag_key2=value2
    • GET /leader?tag_key1=value1&tag_key2=value2
    • GET /primary?tag_key1=value1&tag_key2=value2
    • GET /read-write?tag_key1=value1&tag_key2=value2
    • GET /standby_leader?tag_key1=value1&tag_key2=value2
    • GET /standby-leader?tag_key1=value1&tag_key2=value2

  • GET /read-only: 上記のエンドポイントと似ていますが、プライマリーも含まれます。

  • GET /synchronous または GET /sync: Patroni ノードが同期スタンバイとして実行されている場合にのみ、HTTP ステータス コード 200 を返します。

  • GET /read-only-sync: 上記のエンドポイントと似ていますが、プライマリーも含まれます。

  • GET /quorum: この Patroni ノードがプライマリーの synchronous_standby_names にクォーラム ノードとしてリストされている場合にのみ、HTTP ステータス コード 200 を返します。

  • GET /read-only-quorum: 上記のエンドポイントと似ていますが、プライマリーも含まれます。

  • GET /asynchronous または GET /async: Patroni ノードが非同期スタンバイとして実行されている場合にのみ、HTTP ステータス コード 200 を返します。

  • GET /asynchronous?lag=<max-lag> または GET /async?lag=<max-lag>: 非同期スタンバイ チェック エンドポイント。 asynchronous または async からのチェックに加えて、レプリケーションの遅延もチェックし、指定された値を下回っている場合にのみステータス コード 200 を返します。 DCS のキー cluster.last_leader_operation は、パフォーマンス上の理由から、リーダー wal の位置とレプリカのレイテンシの計算に使用されます。 max-lag はバイト (整数) または人間が読み取り可能な値 (例: 16kB、64MB、1GB) で指定できます。

    • GET /async?lag=1048576
    • GET /async?lag=1024kB
    • GET /async?lag=10MB
    • GET /async?lag=1GB

  • GET /health: PostgreSQL が稼働している場合にのみ、HTTP ステータス コード 200 を返します。

  • GET /liveness: Patroni ハートビートループが適切に実行されている場合は HTTP ステータスコード 200 を返し、最後の実行が、プライマリーでは ttl 秒より前、レプリカでは 2*ttl 秒より前である場合は 503 を返します。livenessProbe に使用できます。

  • GET /readiness?lag=<max-lag>&mode=apply|write: Patroni ノードがリーダーとして実行されている場合、または PostgreSQL が稼働中でレプリケートしており、リーダーからそれほど離れていない場合は、HTTP ステータス コード 200 を返します。 lag パラメーターは、スタンバイがどれだけ遅れを許容できるかを設定します。デフォルトは maximum_lag_on_failover です。ラグはバイト単位、または人間が判読できる値 (16kB、64MB、1GB など) で指定できます。 mode は、WAL を再生する必要があるか (apply)、受信するだけでよいか (write) を設定します。デフォルトは apply です。

Kubernetes readinessProbe として使用すると、新しく開始されたポッドがリーダーに追いついた場合にのみ準備が完了するようになります。これを PodDisruptionBudget と組み合わせると、ノードのローリング再起動中にリーダーが早期に終了するのを防ぐことができます。また、レプリケーションに対応できないレプリカが読み取り専用トラフィックを処理しないようにします。Kubernetes のエンドポイントをリーダー選出に使用できない場合 (OpenShift) は、このエンドポイントを readinessProbe に使用できます。

liveness エンドポイントは非常に軽量であり、SQL は実行されません。プローブは、リーダー キーの有効期限が切れる頃に失敗し始めるように構成することを推奨します。デフォルト値 ttl (30s) を使用すると、プローブの例は次のようになります。

readinessProbe:
  httpGet:
    scheme: HTTP
    path: /readiness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
livenessProbe:
  httpGet:
    scheme: HTTP
    path: /liveness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3

監視エンドポイント

GET /patroni は、リーダー レース中に Patroni によって使用されます。監視システムでも使用できます。このエンドポイントによって生成される JSON ドキュメントは、ヘルス チェック エンドポイントによって生成される JSON と同じ構造を持っています。

例: 正常なクラスター

$ curl -s http://localhost:8008/patroni | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "primary",
  "server_version": 160004,
  "xlog": {
    "location": 67395656
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "dcs_last_seen": 1692356718,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

例: ロック解除されたクラスター

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "received_location": 67419744,
    "replayed_location": 67419744,
    "replayed_timestamp": null,
    "paused": false
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "cluster_unlocked": true,
  "dcs_last_seen": 1692356928,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

例: DCS フェイルセーフ モード が有効になっているロック解除されたクラスター

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "location": 67420024
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "cluster_unlocked": true,
  "failsafe_mode_is_active": true,
  "dcs_last_seen": 1692356928,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

例: 一時停止モード が有効になっているクラスター

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "location": 67420024
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "pause": true,
  "dcs_last_seen": 1724874295,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

GET /metrics エンドポイントを通じて、Patroni メトリクスを Prometheus 形式で取得します。

$ curl http://localhost:8008/metrics

# HELP patroni_version Patroni semver without periods. \
# TYPE patroni_version gauge
patroni_version{scope="batman",name="patroni1"} 040000
# HELP patroni_postgres_running Value is 1 if Postgres is running, 0 otherwise.
# TYPE patroni_postgres_running gauge
patroni_postgres_running{scope="batman",name="patroni1"} 1
# HELP patroni_postmaster_start_time Epoch seconds since Postgres started.
# TYPE patroni_postmaster_start_time gauge
patroni_postmaster_start_time{scope="batman",name="patroni1"} 1724873966.352526
# HELP patroni_primary Value is 1 if this node is the leader, 0 otherwise.
# TYPE patroni_primary gauge
patroni_primary{scope="batman",name="patroni1"} 1
# HELP patroni_xlog_location Current location of the Postgres transaction log, 0 if this node is not the leader.
# TYPE patroni_xlog_location counter
patroni_xlog_location{scope="batman",name="patroni1"} 22320573386952
# HELP patroni_standby_leader Value is 1 if this node is the standby_leader, 0 otherwise.
# TYPE patroni_standby_leader gauge
patroni_standby_leader{scope="batman",name="patroni1"} 0
# HELP patroni_replica Value is 1 if this node is a replica, 0 otherwise.
# TYPE patroni_replica gauge
patroni_replica{scope="batman",name="patroni1"} 0
# HELP patroni_sync_standby Value is 1 if this node is a sync standby replica, 0 otherwise.
# TYPE patroni_sync_standby gauge
patroni_sync_standby{scope="batman",name="patroni1"} 0
# HELP patroni_quorum_standby Value is 1 if this node is a quorum standby replica, 0 otherwise.
# TYPE patroni_quorum_standby gauge
patroni_quorum_standby{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_received_location Current location of the received Postgres transaction log, 0 if this node is not a replica.
# TYPE patroni_xlog_received_location counter
patroni_xlog_received_location{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_replayed_location Current location of the replayed Postgres transaction log, 0 if this node is not a replica.
# TYPE patroni_xlog_replayed_location counter
patroni_xlog_replayed_location{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_replayed_timestamp Current timestamp of the replayed Postgres transaction log, 0 if null.
# TYPE patroni_xlog_replayed_timestamp gauge
patroni_xlog_replayed_timestamp{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_paused Value is 1 if the Postgres xlog is paused, 0 otherwise.
# TYPE patroni_xlog_paused gauge
patroni_xlog_paused{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_streaming Value is 1 if Postgres is streaming, 0 otherwise.
# TYPE patroni_postgres_streaming gauge
patroni_postgres_streaming{scope="batman",name="patroni1"} 1
# HELP patroni_postgres_in_archive_recovery Value is 1 if Postgres is replicating from archive, 0 otherwise.
# TYPE patroni_postgres_in_archive_recovery gauge
patroni_postgres_in_archive_recovery{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_server_version Version of Postgres (if running), 0 otherwise.
# TYPE patroni_postgres_server_version gauge
patroni_postgres_server_version{scope="batman",name="patroni1"} 160004
# HELP patroni_cluster_unlocked Value is 1 if the cluster is unlocked, 0 if locked.
# TYPE patroni_cluster_unlocked gauge
patroni_cluster_unlocked{scope="batman",name="patroni1"} 0
# HELP patroni_failsafe_mode_is_active Value is 1 if failsafe mode is active, 0 otherwise.
# TYPE patroni_failsafe_mode_is_active gauge
patroni_failsafe_mode_is_active{scope="batman",name="patroni1"} 0
# HELP patroni_failsafe_mode_enabled Value is 1 if failsafe_mode is enabled, 0 otherwise.
# TYPE patroni_failsafe_mode_enabled gauge
patroni_failsafe_mode_enabled{scope="batman",name="patroni1"} 0
# HELP patroni_failsafe_member Value is 1 if this node is a member of failsafe, 0 otherwise.
# TYPE patroni_failsafe_member gauge
patroni_failsafe_member{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_timeline Postgres timeline of this node (if running), 0 otherwise.
# TYPE patroni_postgres_timeline gauge
patroni_postgres_timeline{scope="batman",name="patroni1"} 24
# HELP patroni_dcs_last_seen Epoch timestamp when DCS was last contacted successfully by Patroni.
# TYPE patroni_dcs_last_seen gauge
patroni_dcs_last_seen{scope="batman",name="patroni1"} 1724874235
# HELP patroni_pending_restart Value is 1 if the node needs a restart, 0 otherwise.
# TYPE patroni_pending_restart gauge
patroni_pending_restart{scope="batman",name="patroni1"} 1
# HELP patroni_is_paused Value is 1 if auto failover is disabled, 0 otherwise.
# TYPE patroni_is_paused gauge
patroni_is_paused{scope="batman",name="patroni1"} 1
# HELP patroni_postgres_state Numeric representation of Postgres state.
# Values: 0=initdb, 1=initdb_failed, 2=custom_bootstrap, 3=custom_bootstrap_failed, 4=creating_replica, 5=running, 6=starting, 7=bootstrap_starting, 8=start_failed, 9=restarting, 10=restart_failed, 11=stopping, 12=stopped, 13=stop_failed, 14=crashed
# TYPE patroni_postgres_state gauge
patroni_postgres_state{scope="batman",name="patroni1"} 5
# HELP patroni_failover_priority Failover priority of this node.
# TYPE patroni_failover_priority gauge
patroni_failover_priority{scope="batman",name="patroni1"} 1

PostgreSQL 状態値

patroni_postgres_state メトリックは、現在の PostgreSQL インスタンスの状態を数値で表します。これは、時間の経過に伴う状態変化を追跡する必要があるシステムの監視と警告に役立ちます。数値は、PostgresqlState.get_metrics_description() 静的メソッドを使用して生成されます。

値 状態名 説明
0 initdb 新しいクラスターを初期化しています
1 initdb_failed 新しいクラスターの初期化に失敗しました
2 custom_bootstrap カスタムブートストラップスクリプトを実行中
3 custom_bootstrap_failed カスタムブートストラップスクリプトが失敗しました
4 creating_replica プライマリーからレプリカを作成中
5 running PostgreSQL は正常に実行されています
6 starting PostgreSQL が起動中です
7 bootstrap_starting カスタムブートストラップ後の起動中
8 start_failed PostgreSQL の起動に失敗しました
9 restarting PostgreSQL が再起動中です
10 restart_failed PostgreSQL の再起動に失敗しました
11 stopping PostgreSQL が停止処理中です
12 stopped PostgreSQL は停止しています
13 stop_failed PostgreSQL の停止に失敗しました
14 crashed PostgreSQL がクラッシュしました

PostgreSQL 状態値

注記

これらの数値は固定されており、既存の監視システムとの下位互換性を維持するために変更されることはありません。将来的に新しい状態が追加された場合、既存の数値を変更することなく、新しい数値が割り当てられます。

クラスターステータスエンドポイント

  • GET /cluster エンドポイントは、現在のクラスター トポロジと状態を説明する JSON ドキュメントを生成します。
$ curl -s http://localhost:8008/cluster | jq .
{
  "members": [
    {
      "name": "patroni1",
      "role": "leader",
      "state": "running",
      "api_url": "http://10.89.0.4:8008/patroni",
      "host": "10.89.0.4",
      "port": 5432,
      "timeline": 5,
      "tags": {
        "clonefrom": true
      }
    },
    {
      "name": "patroni2",
      "role": "replica",
      "state": "streaming",
      "api_url": "http://10.89.0.6:8008/patroni",
      "host": "10.89.0.6",
      "port": 5433,
      "timeline": 5,
      "tags": {
        "clonefrom": true
      },
      "receive_lag": 0,
      "receive_lsn": "0/4000060",
      "replay_lag": 0,
      "replay_lsn": "0/4000060",
      "lag": 0,
      "lsn": "0/4000060"
    }
  ],
  "scope": "demo",
  "scheduled_switchover": {
    "at": "2023-09-24T10:36:00+02:00",
    "from": "patroni1",
    "to": "patroni3"
  }
}
  • GET /history エンドポイントは、クラスターのスイッチオーバー/フェイルオーバーの履歴を表示します。この形式は、pg_wal ディレクトリ内の履歴ファイルの内容とよく似ています。唯一の違いは、新しいタイムラインがいつ作成されたかを示すタイムスタンプ フィールドです。
$ curl -s http://localhost:8008/history | jq .
[
  [
    1,
    25623960,
    "no recovery target specified",
    "2019-09-23T16:57:57+02:00"
  ],
  [
    2,
    25624344,
    "no recovery target specified",
    "2019-09-24T09:22:33+02:00"
  ],
  [
    3,
    25624752,
    "no recovery target specified",
    "2019-09-24T09:26:15+02:00"
  ],
  [
    4,
    50331856,
    "no recovery target specified",
    "2019-09-24T09:35:52+02:00"
  ]
]

構成エンドポイント

GET /config: 動的構成の現在のバージョンを取得します。

$ curl -s http://localhost:8008/config | jq .
{
  "ttl": 30,
  "loop_wait": 10,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5,
      "max_connections": "100"
    }
  }
}

PATCH /config: 既存の構成を変更します。

$ curl -s -XPATCH -d \
    '{"loop_wait":5,"ttl":20,"postgresql":{"parameters":{"max_connections":"101"}}}' \
    http://localhost:8008/config | jq .
{
  "ttl": 20,
  "loop_wait": 5,
  "maximum_lag_on_failover": 1048576,
  "retry_timeout": 10,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5,
      "max_connections": "101"
    }
  }
}

上記の REST API 呼び出しは、既存の構成にパッチを適用し、新しい構成を返します。

ノードがこの構成を処理したことを確認してみましょう。まず、5 秒ごとにログ行の出力を開始するはずです (loop_wait=5)。 “max_connections” の変更には再起動が必要なため、“pending_restart” フラグが表示されるはずです。

$ curl -s http://localhost:8008/patroni | jq .
{
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "xlog": {
    "location": 2197818976
  },
  "timeline": 1,
  "dcs_last_seen": 1724874545,
  "database_system_identifier": "7408277255830290455",
  "pending_restart": true,
  "pending_restart_reason": {
    "max_connections": {
      "old_value": "100",
      "new_value": "101"
    }
  },
  "patroni": {
    "version": "4.0.0",
    "scope": "batman",
    "name": "patroni1"
  },
  "state": "running",
  "role": "primary",
  "server_version": 160004
}

パラメータの削除:

一部の設定を削除 (リセット) したい場合は、null を使用してパッチを適用するだけです。

$ curl -s -XPATCH -d \
    '{"postgresql":{"parameters":{"max_connections":null}}}' \
    http://localhost:8008/config | jq .
{
  "ttl": 20,
  "loop_wait": 5,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "unix_socket_directories": ".",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5
    }
  }
}

上記の呼び出しにより、動的構成から postgresql.parameters.max_connections が削除されます。

PUT /config: 既存の動的構成の完全な書き換えを無条件に実行することも可能です。

$ curl -s -XPUT -d \
    '{"maximum_lag_on_failover":1048576,"retry_timeout":10,"postgresql":{"use_slots":true,"use_pg_rewind":true,"parameters":{"hot_standby":"on","wal_level":"hot_standby","unix_socket_directories":".","max_wal_senders":5}},"loop_wait":3,"ttl":20}' \
    http://localhost:8008/config | jq .
{
  "ttl": 20,
  "maximum_lag_on_failover": 1048576,
  "retry_timeout": 10,
  "postgresql": {
    "use_slots": true,
    "parameters": {
      "hot_standby": "on",
      "unix_socket_directories": ".",
      "wal_level": "hot_standby",
      "max_wal_senders": 5
    },
    "use_pg_rewind": true
  },
  "loop_wait": 3
}

スイッチオーバーおよびフェイルオーバーのエンドポイント

スイッチオーバー

/switchover エンドポイントは、クラスターが正常な場合 (リーダーがある場合) にのみ機能します。また、特定の時間にスイッチオーバーをスケジュールすることもできます。

/switchover エンドポイントを呼び出す場合、/failover エンドポイントとは異なり、候補を指定できますが、必須ではありません。候補が指定されていない場合、リーダーが退任した後、クラスターの適格なすべてのノードがリーダー競合に参加します。

POST リクエストの JSON 本文で、leader フィールドを指定する必要があります。 candidate フィールドと scheduled_at フィールドはオプションであり、特定の時間にスイッチオーバーをスケジュールするために使用できます。

状況に応じて、リクエストは異なる HTTP ステータス コードと本文を返す場合があります。スイッチオーバーまたはフェイルオーバーが正常に完了すると、ステータス コード 200 が返されます。スイッチオーバーが正常にスケジュールされた場合、Patroni は HTTP ステータス コード 202 を返します。何か問題が発生した場合、エラー ステータス コード (400、412、または 503 のいずれか) が応答本文の詳細とともに返されます。

DELETE /switchover を使用して、現在スケジュールされているスイッチオーバーを削除できます。

例: 任意の正常なスタンバイへのスイッチオーバーを実行します

$ curl -s http://localhost:8008/switchover -XPOST -d '{"leader":"postgresql1"}'
Successfully switched over to "postgresql2"

例: 特定のノードへのスイッチオーバーを実行します

$ curl -s http://localhost:8008/switchover -XPOST -d \
    '{"leader":"postgresql1","candidate":"postgresql2"}'
Successfully switched over to "postgresql2"

例: 特定の時刻に、リーダーからクラスター内の他の任意の正常なスタンバイへのスイッチオーバーをスケジュールします。

$ curl -s http://localhost:8008/switchover -XPOST -d \
    '{"leader":"postgresql0","scheduled_at":"2019-09-24T12:00+00"}'
Switchover scheduled

フェイルオーバー

/failover エンドポイントは、正常なノードがない場合に手動フェイルオーバーを実行するために使用できます (たとえば、すべての同期スタンバイが昇格できるほど正常でない場合は非同期スタンバイに)。ただし、クラスターにリーダーがない必要はありません。正常なクラスターでもフェイルオーバーを実行できます。

POST リクエストの JSON 本文で、candidate フィールドを指定する必要があります。 leader フィールドが指定されている場合、代わりにスイッチオーバーがトリガーされます。

例:

$ curl -s http://localhost:8008/failover -XPOST -d '{"candidate":"postgresql1"}'
Successfully failed over to "postgresql1"
警告

このエンドポイントの使用には十分な注意 を払ってください。状況によってはデータ損失が発生する可能性があります。ほとんどの場合、スイッチオーバーエンドポイント で管理者のニーズが満たされます。

POST /switchover エンドポイントと POST /failover エンドポイントは、それぞれ patronictl_switchover と patronictl_failover によって使用されます。

DELETE /switchover は patronictl flush cluster-name switchover によって使用されます。

フェイルオーバー スイッチオーバー
リーダーの指定が必要 いいえ はい
候補の指定が必要 はい いいえ
一時停止中でも実行可能 はい はい (特定の候補のみ)
スケジュール可能 いいえ はい (一時停止中でない場合)

フェイルオーバー/スイッチオーバーの比較

健全なスタンバイ

スイッチオーバー時にリーダー競合に参加するため、またはフェイルオーバー/スイッチオーバーの候補としてリーダーになるために、クラスターのメンバーが満たす必要があるチェックがいくつかあります。

  • Patroni API 経由でアクセス可能であること。
  • nofailover タグが true に設定されていないこと。
  • ウォッチドッグが完全に機能していること (構成で必要とされる場合)。
  • 正常なクラスターでのスイッチオーバーまたは自動フェイルオーバーの場合、最大レプリケーションラグ (maximum_lag_on_failover 構成パラメータ ) を超えていないこと。
  • 正常なクラスターでのスイッチオーバーまたは自動フェイルオーバーの場合、check_timeline 構成パラメータ が true に設定されているときは、タイムライン番号がクラスターのタイムラインより小さくないこと。
  • 同期モード の場合:
    • スイッチオーバーの場合 (候補を指定する場合としない場合の両方): /sync キーのメンバーにリストされていること。
    • 正常なクラスターと異常なクラスターのいずれでのフェイルオーバーの場合も、このチェックは省略されます。
警告

リーダーのいないクラスターで手動フェイルオーバーを行う場合、候補は以下の場合でも昇格が許可されます。

  • 同期モードが有効なときに /sync キーのメンバーに含まれていない場合。
  • レプリケーションラグが許容される最大値を超えている場合。
  • タイムライン番号が最後に判明しているクラスタータイムラインより小さい場合。

再起動エンドポイント

  • POST /restart: POST /restart 呼び出しを実行すると、特定のノードで Postgres を再起動できます。 POST リクエストの JSON 本体では、オプションでいくつかの再起動条件を指定できます。
    • restart_pending: ブール値、true に設定すると、Patroni は、PostgreSQL 構成にいくつかの変更を適用するために、再起動が保留中の場合にのみ PostgreSQL を再起動します。
    • role: ノードの現在のロールが POST リクエストのロールと一致する場合にのみ再起動を実行します。
    • postgres_version: postgres の現在のバージョンが POST リクエストで指定されたバージョンよりも小さい場合にのみ再起動を実行します。
    • timeout: PostgreSQL が接続の受け入れを開始するまで待機する必要がある時間。 primary_start_timeout をオーバーライドします。
    • schedule: タイムゾーン付きタイムスタンプ。将来の任意の時点に再起動をスケジュールします。
  • DELETE /restart: スケジュールされた再起動を削除します

POST /restart エンドポイントと DELETE /restart エンドポイントは、それぞれ patronictl_restart と patronictl flush cluster-name restart によって使用されます。

リロードエンドポイント

POST /reload 呼び出しは、Patroni に構成ファイルを再読み込みして適用するように命令します。これは、SIGHUP シグナルを Patroni プロセスに送信するのと同じです。再起動が必要な Postgres パラメーターの一部 (shared_buffers など) を変更した場合でも、POST /restart エンドポイントを呼び出すか、patronictl_restart を使用して、明示的に Postgres の再起動を行う必要があります。

リロード エンドポイントは patronictl_reload によって使用されます。

再初期化エンドポイント

POST /reinitialize: 指定されたノード上の PostgreSQL データ ディレクトリを再初期化します。レプリカ上でのみ実行が許可されます。呼び出されると、データ ディレクトリが削除され、pg_basebackup または代替の レプリカ作成方法 が開始されます。

Patroni が、障害が発生した Postgres を回復 (再起動) しようとするループ内にある場合、呼び出しは失敗する可能性があります。この問題を解決するには、リクエスト本文に {"force":true} を指定します。

リクエスト本文で {“from-leader”:true} を指定すると、リーダー ノードからベースバックアップを直接取得できます。これは、すべてのレプリカ ノードに障害が発生したときに再初期化を実行する場合に便利です。

再初期化エンドポイントは patronictl_reinit によって使用されます。

5 - patronictl

patronictl の設定、構文、およびサブコマンドに関するコマンド リファレンス。

Patroni には patronictl という名前のコマンドライン インターフェイスがあり、これは基本的に Patroni の REST API および DCS と対話するために使用されます。これは、クラスター内での操作の実行を容易にすることを目的としており、人間またはスクリプトで簡単に使用できます。

構成

patronictl は、構成の 3 セクションを使用します。

  • ctl: Patroni REST API に対して認証する方法、およびサーバー ID を検証する方法。詳細については、ctl設定 を参照してください。
  • restapi: Patroni REST API に対して認証する方法、およびサーバー ID を検証する方法。 ctl 構成が十分でない場合にのみ使用されます。 patronictl は、主に restapi.authentication セクション (ctl.authentication が欠落している場合) と restapi.cafile 設定 (ctl.cacert が欠落している場合) に関係します。詳細については、REST API 設定 を参照してください。
  • DCS (例: etcd): Patroni によって使用される DCS に接続して認証する方法。

これらの構成オプションは、環境変数または構成ファイルから取得できます。 環境構成の設定 または YAML 構成設定 の上記のセクションを探して、環境変数または構成ファイルを通じてそれらのオプションを設定する方法を理解してください。

環境変数の使用を選択した場合、それは簡単なアプローチです。 Patronictl は環境変数を読み取り、その値を使用します。

構成ファイルの使用を選択した場合、使用するファイルについて patronictl に通知するさまざまな方法があります。デフォルトでは、patronictl は patronictl.yaml という名前の構成ファイルをロードしようとします。この構成ファイルは、システムに応じて次のパスのいずれかにあると想定されます。

  • Mac OS X: ~/Library/Application Support/patroni
  • Mac OS X (POSIX): ~/.patroni
  • Unix: ~/.config/patroni
  • Unix (POSIX): ~/.patroni
  • Windows (ローミング): C:\Users\<user>\AppData\Roaming\patroni
  • Windows (ローミングなし): C:\Users\<user>\AppData\Local\patroni

次のいずれかの方法でその動作をオーバーライドできます。

  • カスタム構成ファイルへのパスを使用して環境変数 PATRONICTL_CONFIG_FILE を設定します。
  • patronictl の -c / --config-file コマンドライン引数をカスタム構成ファイルへのパスとともに使用します。
注記

patroni デーモンが実行されているのと同じホストで patronictl を実行している場合、patronictl に必要なすべての構成セクションがファイルに含まれていれば、同じ構成ファイルを使用することができます。

使用法

patronictl は、いくつかの便利な操作を公開します。このセクションでは、それぞれについて説明することを目的としています。

patronictl の各サブコマンドに入る前に、patronictl 自体に次のコマンドライン引数があることに注意してください。

-c / --config-file 前に説明したように、patronictl の構成ファイルへのパスを提供するために使用されます。

-d / --dcs-url / --dcs Patroni によって使用される DCS に接続文字列を提供します。

この引数は、patronictl 構成から DCS および namespace 設定をオーバーライドするか、構成に欠落している場合に定義するために使用できます。

値は DCS://HOST:PORT/NAMESPACE の形式である必要があります。たとえば、localhost 上で実行されている etcd v3 に、Patroni クラスターが service 名前空間に格納された状態で接続するには、etcd3://localhost:2379/service を指定します。引数の値に欠落している部分は、構成に存在する値またはそのデフォルトに置き換えられます。

-k / --insecure REST API サーバー SSL 証明書の検証をバイパスするフラグ。

これは、patronictl からコマンドを実行するための概要です。

patronictl [ { -c | --config-file } CONFIG_FILE ]
  [ { -d | --dcs-url | --dcs } DCS_URL ] 
  [ { -k | --insecure } ]
  SUBCOMMAND
注記

これは概要の構文です。

  • 角括弧内のオプションは省略可能です。
  • 中括弧内のオプションは、「セットの 1 つを選択する」操作を表します。
  • [, ... ] が付いたオプションは複数回指定できます。
  • 大文字で書かれたものは、値を与える必要があるリテラルを表します。

次のサブセクションで patronictl サブコマンドを説明するときに、これと同じ構文を使用します。また、以下のサブセクションでサブコマンドを説明する場合、コマンドの概要は、上記の概要の SUBCOMMAND を置き換えるものと見なす必要があります。

次のサブセクションでは、patronictl によって実装される各コマンドの説明を見つけることができます。例として、Patroni の GitHub リポジトリに存在する構成ファイル (ファイル postgres0.yml、postgres1.yml、および postgres2.yml) を使用します。

patronictl demote-cluster

書式 

demote-cluster
  [ CLUSTER_NAME ]
  [ --host HOST ]
  [ --port PORT ]
  [ --restore-command RESTORE_COMMAND ]
  [ --primary-slot-name PRIMARY_SLOT_NAME ]
  [ --force ]

説明

patronictl demote-cluster は、通常の Patroni クラスターを スタンバイ クラスター に変換します。

このコマンドは、提供されたリモート プライマリー接続オプションから構築された standby_cluster セクションを使用して動的構成にパッチを適用し、リーダーがスタンバイ リーダーとして実行されるまで待機します。 構成を変更する前に現在のクラスター トポロジを出力します。 --force が使用されていない場合は確認を求めます。

--host、--port、または --restore-command の少なくとも 1 つを指定する必要があります。

パラメータ

CLUSTER_NAME: Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--host: リモート ノードのアドレス。

--port: リモート ノードのポート。

--restore-command: リモート プライマリーから WAL レコードを復元するコマンド。

--primary-slot-name: レプリケーションに使用するリモート ノード上のレプリケーション スロットの名前。

--force: クラスターを降格するときに確認プロンプトをスキップするフラグ。

スクリプトに便利です。

例

クラスターをリモートのプライマリー エンドポイントに従うスタンバイ クラスターに降格します。

$ patronictl -c postgres0.yml demote-cluster batman --host 192.0.2.10 --port 5432 --primary-slot-name batman --force

patronictl dsn

書式 

dsn
  [ CLUSTER_NAME ]
  [ { { -r | --role } { leader | primary | standby-leader | replica | standby | any } | { -m | --member } MEMBER_NAME } ]
  [ --group CITUS_GROUP ]

説明

patronictl dsn は、Patroni クラスターの 1 つのメンバーの接続文字列を取得します。

複数のメンバーがこのコマンドのパラメーターに一致する場合、プライマリー ノードを優先してそのうちの 1 つが選択されます。

パラメータ

CLUSTER_NAME: Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

-r / --role 指定されたロールを持つメンバーを選択します。

役割は次のいずれかになります。

  • leader: 通常の Patroni クラスターまたはスタンバイ Patroni クラスターのリーダー。または
  • primary: 通常の Patroni クラスターのリーダー。または
  • standby-leader: スタンバイ Patroni クラスターのリーダー。または
  • replica: Patroni クラスターのレプリカ。または
  • standby: replica と同じ。または
  • any: 任意のロール。このパラメータを省略した場合と同じです。または

-m / --member 指定された名前を持つクラスターのメンバーを選択します。

MEMBER_NAME はメンバーの名前です。

--group 指定された Citus グループに属するメンバーを選択します。

CITUS_GROUP は、Citus グループの ID です。

例

プライマリー ノードの DSN を取得します。

$ patronictl -c postgres0.yml dsn batman -r primary
host=127.0.0.1 port=5432

postgresql1 という名前のノードの DSN を取得します。

$ patronictl -c postgres0.yml dsn batman --member postgresql1
host=127.0.0.1 port=5433

patronictl edit-config

書式 

edit-config
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { -q | --quiet } ]
  [ { -s | --set } CONFIG="VALUE" [, ... ] ]
  [ { -p | --pg } PG_CONFIG="PG_VALUE" [, ... ] ]
  [ { --apply | --replace } CONFIG_FILE ]
  [ --force ]

説明

patronictl edit-config はクラスターの動的構成を変更し、それによって DCS を更新します。

注記

TTY を通じて呼び出される場合、コマンドはページャーを通じて動的構成の差分を表示しようとします。デフォルトでは、less または more のいずれかを使用しようとします。別のページャーが必要な場合は、PAGER 環境変数を目的のページャーに設定します。

パラメータ

CLUSTER_NAME: Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループの動的構成を変更します。

指定しない場合、patronictl は、citus.group 構成が存在する場合は、そこからそれを取得しようとします。

CITUS_GROUP は、Citus グループの ID です。

-q / --quiet 構成の差分の表示をスキップするフラグ。

-s / --set 指定された動的構成オプションを指定された値で設定します。

CONFIG は、YAML ツリー内の動的構成パスの名前であり、レベルは . で結合されます。

VALUE は CONFIG の値です。 null の場合、CONFIG は動的構成から削除されます。

-p / --pg 指定された動的 Postgres 構成オプションを指定された値で設定します。

これは本質的に、-s / --set の短縮形であり、CONFIG の先頭に postgresql.parameters. が付加されます。

PG_CONFIG は、設定する Postgres 構成の名前です。

PG_VALUE は PG_CONFIG の値です。 null の場合、PG_CONFIG は動的構成から削除されます。

--apply 指定されたファイルから動的構成を適用します。

これは、CONFIG_FILE の構成ごとに 1 つずつ、複数の -s / --set オプションを指定するのと似ています。

CONFIG_FILE は、適用する動的構成を含むファイルへのパス (YAML 形式) です。 stdin から読み取りたい場合は、- を使用します。

--replace DCS の動的構成を、指定されたファイルで指定された動的構成に置き換えます。

CONFIG_FILE は、有効にする新しい動的構成を含むファイルへのパス (YAML 形式) です。 stdin から読み取りたい場合は、- を使用します。

--force 動的構成を変更するときに確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

max_connections Postgres GUC を変更します。

patronictl -c postgres0.yml edit-config batman --pg max_connections="150" --force
---
+++
@@ -1,6 +1,8 @@
loop_wait: 10
maximum_lag_on_failover: 1048576
postgresql:
+  parameters:
+    max_connections: 150
  pg_hba:
  - host replication replicator 127.0.0.1/32 md5
  - host all all 0.0.0.0/0 md5

Configuration changed

loop_wait および ttl 設定を変更します。

patronictl -c postgres0.yml edit-config batman --set loop_wait="15" --set ttl="45" --force
---
+++
@@ -1,4 +1,4 @@
-loop_wait: 10
+loop_wait: 15
maximum_lag_on_failover: 1048576
postgresql:
  pg_hba:
@@ -6,4 +6,4 @@
  - host all all 0.0.0.0/0 md5
  use_pg_rewind: true
retry_timeout: 10
-ttl: 30
+ttl: 45

Configuration changed

maximum_lag_on_failover 設定を動的構成から削除します。

patronictl -c postgres0.yml edit-config batman --set maximum_lag_on_failover="null" --force
---
+++
@@ -1,5 +1,4 @@
loop_wait: 10
-maximum_lag_on_failover: 1048576
postgresql:
  pg_hba:
  - host replication replicator 127.0.0.1/32 md5

Configuration changed

patronictl failover

書式 

failover
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  --candidate CANDIDATE_NAME
  [ --force ]

説明

patronictl failover は、クラスター内で手動フェイルオーバーを実行します。

これは、クラスターが正常でない場合に使用するように設計されています。例:

  • リーダーはいません。または
  • 同期クラスターでは使用できる同期スタンバイはありません。

同期モードが有効な場合は、非同期ノードにフェイルオーバーすることもできます。

注記

正常なクラスターで patronictl failover を実行することを妨げるものはありません。ただし、そのような場合には patronictl switchover を使用することをお勧めします。

警告

フェイルオーバーをトリガーすると、プロモートされたレプリカがプライマリーと比較してどの程度最新であるかによって、データ損失が発生する可能性があります。

パラメータ

CLUSTER_NAME: Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループでフェイルオーバーを実行します。

CITUS_GROUP は、Citus グループの ID です。

--candidate フェイルオーバー時に昇格されるノード。

CANDIDATE_NAME は、昇格するノードの名前です。

--force フェイルオーバーの実行時に確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

ノード postgresql2 にフェイルオーバーします。

$ patronictl -c postgres0.yml failover batman --candidate postgresql2 --force
Current cluster topology
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  3 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  3 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  3 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
2023-09-12 11:52:27.50978 Successfully failed over to "postgresql2"
+ Cluster: batman (7277694203142172922) -+---------+----+-------------+---------+------------+---------+
| Member      | Host           | Role    | State   | TL | Receive LSN |     Lag | Replay LSN |     Lag |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+
| postgresql0 | 127.0.0.1:5432 | Replica | stopped |    |     unknown | unknown |    unknown | unknown |
| postgresql1 | 127.0.0.1:5433 | Replica | running |  3 |   0/4000188 |       0 |  0/4000188 |       0 |
| postgresql2 | 127.0.0.1:5434 | Leader  | running |  3 |             |         |            |         |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+

patronictl flush

書式 

flush
  CLUSTER_NAME
  [ MEMBER_NAME [, ... ] ]
  { restart | switchover }
  [ --group CITUS_GROUP ]
  [ { -r | --role } { leader | primary | standby-leader | replica | standby | any } ]
  [ --force ]

説明

patronictl flush は、スケジュールされたイベントがあればそれを破棄します。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

MEMBER_NAME 指定された Patroni メンバーのスケジュールされたイベントを破棄します。

複数のメンバーを指定できます。メンバーが指定されていない場合は、すべてのメンバーが考慮されます。

注記

スケジュールされた再起動イベントを破棄する場合にのみ使用されます。

restart スケジュールされた再起動イベントを破棄します。

switchover スケジュールされたスイッチオーバー イベントを破棄します。

--group 指定された Citus グループからスケジュールされたイベントを破棄します。

CITUS_GROUP は、Citus グループの ID です。

-r / --role 指定されたロールを持つメンバーのスケジュールされたイベントを破棄します。

役割は次のいずれかになります。

  • leader: 通常の Patroni クラスターまたはスタンバイ Patroni クラスターのリーダー。または
  • primary: 通常の Patroni クラスターのリーダー。または
  • standby-leader: スタンバイ Patroni クラスターのリーダー。または
  • replica: Patroni クラスターのレプリカ。または
  • standby: replica と同じ。または
  • any: 任意のロール。このパラメータを省略した場合と同じです。
注記

スケジュールされた再起動イベントを破棄する場合にのみ使用されます。

--force フラッシュの実行時に確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

スケジュールされたスイッチオーバー イベントを破棄します。

$ patronictl -c postgres0.yml flush batman switchover --force
Success: scheduled switchover deleted

すべてのスタンバイ ノードのスケジュールされた再起動を破棄します。

$ patronictl -c postgres0.yml flush batman restart -r replica --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+---------------------------+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Scheduled restart         |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     | 2025-03-23T18:00:00-03:00 |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
Success: flush scheduled restart for member postgresql1
Success: flush scheduled restart for member postgresql2

ノード postgresql0 および postgresql1 のスケジュールされた再起動を破棄します。

$ patronictl -c postgres0.yml flush batman postgresql0 postgresql1 restart --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+---------------------------+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Scheduled restart         |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     | 2025-03-23T18:00:00-03:00 |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
Success: flush scheduled restart for member postgresql0
Success: flush scheduled restart for member postgresql1

patronictl history

書式 

history
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { -f | --format } { pretty | tsv | json | yaml } ]

説明

patronictl history は、クラスターからのフェイルオーバーおよびスイッチオーバー イベントの履歴を表示します (存在する場合)。

出力には次の情報が含まれます。

TL イベントが発生した時点の Postgres タイムライン。

LSN イベントが発生した時点の Postgres LSN。

Reason Postgres .history ファイルから取得された理由。

Timestamp イベントが発生した時刻。

New Leader イベント中に昇格した Patroni メンバー。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループからのイベントの履歴を表示します。

CITUS_GROUP は、Citus グループの ID です。

指定しない場合、patronictl は、citus.group 構成が存在する場合は、そこからそれを取得しようとします。

-f / --format 出力内のイベントのリストをフォーマットする方法。

形式は次のいずれかになります。

  • pretty: 履歴を美しいテーブルとして出力します。または
  • tsv: \t で区切られた列を含む表形式の情報として履歴を出力します。または
  • json: 履歴を JSON 形式で出力します。または
  • yaml: YAML 形式で履歴を出力します。

デフォルトは pretty です。

例

イベントの履歴を表示します。

$ patronictl -c postgres0.yml history batman
+----+----------+------------------------------+----------------------------------+-------------+
| TL |      LSN | Reason                       | Timestamp                        | New Leader  |
+----+----------+------------------------------+----------------------------------+-------------+
|  1 | 24392648 | no recovery target specified | 2023-09-11T22:11:27.125527+00:00 | postgresql0 |
|  2 | 50331864 | no recovery target specified | 2023-09-12T11:34:03.148097+00:00 | postgresql0 |
|  3 | 83886704 | no recovery target specified | 2023-09-12T11:52:26.948134+00:00 | postgresql2 |
|  4 | 83887280 | no recovery target specified | 2023-09-12T11:53:09.620136+00:00 | postgresql0 |
+----+----------+------------------------------+----------------------------------+-------------+

イベントの履歴を YAML 形式で表示します。

$ patronictl -c postgres0.yml history batman -f yaml
- LSN: 24392648
  New Leader: postgresql0
  Reason: no recovery target specified
  TL: 1
  Timestamp: '2023-09-11T22:11:27.125527+00:00'
- LSN: 50331864
  New Leader: postgresql0
  Reason: no recovery target specified
  TL: 2
  Timestamp: '2023-09-12T11:34:03.148097+00:00'
- LSN: 83886704
  New Leader: postgresql2
  Reason: no recovery target specified
  TL: 3
  Timestamp: '2023-09-12T11:52:26.948134+00:00'
- LSN: 83887280
  New Leader: postgresql0
  Reason: no recovery target specified
  TL: 4
  Timestamp: '2023-09-12T11:53:09.620136+00:00'

patronictl list

書式 

list
  [ CLUSTER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ { -e | --extended } ]
  [ { -t | --timestamp } ]
  [ { -f | --format } { pretty | tsv | json | yaml } ]
  [ { -W | { -w | --watch } TIME } ]

説明

patronictl list は、Patroni クラスターとそのメンバーに関する情報を示します。

出力には次の情報が含まれます。

Cluster Patroni クラスターの名前。

Member Patroni メンバーの名前。

Host メンバーが配置されているホスト。

Role メンバーの現在の役割。

次のいずれかになります:

  • Leader: 通常の Patroni クラスターの現在のリーダー。または
  • Standby Leader: Patroni スタンバイ クラスターの現在のリーダー。または
  • Sync Standby: 同期モードが有効になっている Patroni クラスターの同期スタンバイ。または
  • Replica: Patroni クラスターの通常のスタンバイ。

State Patroni メンバーの Postgres の現在の状態。

考えられる状態の例をいくつか示します。

  • running: Postgres が現在稼働している場合。
  • streaming: レプリカであり、Postgres が現在プライマリー ノードから WAL をストリーミングしている場合。
  • in archive recovery: レプリカであり、Postgres が現在アーカイブから WAL をフェッチしている場合。
  • stopped: Postgres がシャットダウンされていた場合。
  • crashed: Postgres がクラッシュした場合。

TL Patroni メンバー内の現在の Postgres タイムライン。

Receive LSN メンバーのストリーミング レプリケーションによって受信され、ディスクに同期された最後の先行書き込みログの場所 (pg_catalog.pg_last_(xlog|wal)_receive_(location|lsn)())。

Receive Lag メンバーの Receive LSN 位置とその上流との間のレプリケーション ラグ (MB 単位)。

Replay LSN メンバーのリカバリ中に再生された最後の先行書き込みログの場所 (pg_catalog.pg_last_(xlog|wal)_replay_(location|lsn)())。

Replay Lag メンバーの Replay LSN 位置とその上流との間のレプリケーション ラグ (MB 単位)。

それに加えて、次の情報が出力に含まれる場合があります。

System identifier Postgres システム識別子。

注記

テーブルヘッダーに表示されます。

出力形式が pretty の場合にのみ表示されます。

Group Citus グループ ID。

注記

テーブルヘッダーに表示されます。

Citus クラスターの場合にのみ表示されます。

Pending restart * は、一部の Postgres 構成を有効にするためにノードの再起動が必要であることを示します。空の値は、ノードを再起動する必要がないことを示します。

注記

メンバー属性として表示されます。

次の場合に表示されます。

  • pretty または tsv 形式で出力し、拡張出力が有効な場合。または
  • ノードの再起動が必要な場合。

Scheduled restart Patroni メンバーによって管理される Postgres インスタンスの再起動がスケジュールされたタイムスタンプ。空の値は、メンバーにスケジュールされた再起動がないことを示します。

注記

メンバー属性として表示されます。

次の場合に表示されます。

  • pretty または tsv 形式で出力し、拡張出力が有効な場合。または
  • ノードにスケジュールされた再起動がある場合。

Tags Patroni メンバーに設定されたタグが含まれます。空の値は、タグが設定されていないか、タグがデフォルト値で設定されていることを示します。

注記

メンバー属性として表示されます。

次の場合に表示されます。

  • pretty または tsv 形式で出力し、拡張出力が有効な場合。または
  • ノードにカスタム タグ、またはデフォルト以外の値を持つデフォルト タグがある場合。

Scheduled switchover Patroni クラスターのスイッチオーバーがスケジュールされている場合のタイムスタンプ。

注記

テーブルのフッターに表示されます。

スケジュールされたスイッチオーバーがある場合にのみ表示され、出力形式は pretty です。

Maintenance mode

クラスター監視が現在一時停止されている場合。

注記

テーブルのフッターに表示されます。

クラスターが一時停止されており、出力形式が pretty の場合にのみ表示されます。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループのメンバーに関する情報を表示します。

CITUS_GROUP は、Citus グループの ID です。

-e / --extended 拡張情報を表示します。

値が空であっても、Pending restart、Scheduled restart、Tags 属性を強制的に表示します。

注記

pretty および tsv 出力形式にのみ適用されます。

-t / --timestamp クラスターとそのメンバーに関する情報を出力する前にタイムスタンプを出力します。

-f / --format 出力内のクラスターメンバーのリストをフォーマットする方法。

形式は次のいずれかになります。

  • pretty: クラスターメンバーを美しいテーブルとして出力します。または
  • tsv: \t で区切られた列を含む表形式の情報としてクラスターメンバーを出力します。または
  • json: クラスターメンバーを JSON 形式で出力します。または
  • yaml: YAML 形式でクラスターメンバーを出力します。

デフォルトは pretty です。

-W 2 秒ごとに情報を自動的に更新します。

-w / --watch 指定した間隔で情報を自動的に更新します。

TIME は、更新間の間隔 (秒単位) です。

例

クラスターに関する情報をpretty 形式で表示します。

$ patronictl -c postgres0.yml list batman
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+

拡張列を使用して、クラスターに関する情報を pretty 形式で表示します。

$ patronictl -c postgres0.yml list batman -e
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+-----------------+------------------------+-------------------+------+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Pending restart | Pending restart reason | Scheduled restart | Tags |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+-----------------+------------------------+-------------------+------+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |                 |                        |                   |      |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |                 |                        |                   |      |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |                 |                        |                   |      |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+-----------------+------------------------+-------------------+------+

クラスターに関する情報を実行のタイムスタンプとともに YAML 形式で表示します。

$ patronictl -c postgres0.yml list batman -f yaml -t
2023-09-12 13:30:48
- Cluster: batman
  Host: 127.0.0.1:5432
  Member: postgresql0
  Role: Leader
  State: running
  TL: 5
- Cluster: batman
  Host: 127.0.0.1:5433
  Receive LSN: 0/40004E8
  Receive Lag: 0
  Replay LSN: 0/40004E8
  Replay Lag: 0
  Member: postgresql1
  Role: Replica
  State: streaming
  TL: 5
- Cluster: batman
  Host: 127.0.0.1:5434
  Receive LSN: 0/40004E8
  Receive Lag: 0
  Replay LSN: 0/40004E8
  Replay Lag: 0
  Member: postgresql2
  Role: Replica
  State: streaming
  TL: 5

patronictl pause

書式 

pause
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ --wait ]

説明

patronictl pause は、Patroni クラスターを一時的にメンテナンス モードにし、自動フェイルオーバーを無効にします。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループを一時停止します。

CITUS_GROUP は、Citus グループの ID です。

指定しない場合、patronictl は、citus.group 構成が存在する場合は、そこからそれを取得しようとします。

--wait すべての Patroni メンバーが一時停止されるまで待ってから、呼び出し元に制御を返します。

例

クラスターをメンテナンス モードにし、すべてのノードが一時停止されるまで待ちます。

$ patronictl -c postgres0.yml pause batman --wait
'pause' request sent, waiting until it is recognized by all nodes
Success: cluster management is paused

patronictl promote-cluster

書式 

promote-cluster
  [ CLUSTER_NAME ]
  [ --force ]

説明

patronictl promote-cluster は、スタンバイ クラスターを通常の Patroni クラスターに変換します。

このコマンドは、動的構成から standby_cluster セクションを削除し、リーダーがプライマリーとして実行されるまで待機します。 構成を変更する前に現在のクラスター トポロジを出力します。 --force が使用されていない場合は確認を求めます。

パラメータ

CLUSTER_NAME: Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--force: クラスターを昇格するときに確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

スタンバイ クラスターを通常の Patroni クラスターとして実行するように昇格します。

$ patronictl -c postgres0.yml promote-cluster batman --force

patronictl query

書式 

query
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { { -r | --role } { leader | primary | standby-leader | replica | standby | any } | { -m | --member } MEMBER_NAME } ]
  [ { -d | --dbname } DBNAME ]
  [ { -U | --username } USERNAME ]
  [ --password ]
  [ --format { pretty | tsv | json | yaml } ]
  [ { { -f | --file } FILE_NAME | { -c | --command } SQL_COMMAND } ]
  [ --delimiter ]
  [ { -W | { -w | --watch } TIME } ]

説明

patronictl query は、Patroni クラスターのメンバーに対して SQL コマンドまたはスクリプトを実行します。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループをクエリーします。

CITUS_GROUP は、Citus グループの ID です。

-r / --role 指定されたロールを持つメンバーを選択します。

役割は次のいずれかになります。

  • leader: 通常の Patroni クラスターまたはスタンバイ Patroni クラスターのリーダー。または
  • primary: 通常の Patroni クラスターのリーダー。または
  • standby-leader: スタンバイ Patroni クラスターのリーダー。または
  • replica: Patroni クラスターのレプリカ。または
  • standby: replica と同じ。または
  • any: 任意のロール。このパラメータを省略した場合と同じです。

-m / --member 指定された名前のメンバーを選択します。

MEMBER_NAME は、選択されるメンバーの名前です。

-d / --dbname 接続してクエリーを実行するデータベース。

DBNAME はデータベースの名前です。指定しない場合、デフォルトの USERNAME が使用されます。

-U / --username データベースに接続するユーザー。

USERNAME ユーザーの名前。指定しない場合、デフォルトは patronictl query を実行しているオペレーティング システム ユーザーになります。

--password 接続ユーザーのパスワードの入力を求めます。

Patroni は libpq を使用するため、代わりに ~/.pgpass ファイルを作成するか、PGPASSWORD 環境変数を設定できます。

--format クエリーの出力をフォーマットする方法。

形式は次のいずれかになります。

  • pretty: クエリー出力を美しいテーブルとして出力します。または
  • tsv: \t で区切られた列を含む表形式の情報としてクエリー出力を出力します。または
  • json: クエリー出力を JSON 形式で出力します。または
  • yaml: クエリー出力を YAML 形式で出力します。

デフォルトは tsv です。

-f / --file クエリーを実行するコマンドのソースとしてファイルを使用します。

FILE_NAME はソース ファイルへのパスです。

-c / --command クエリーで指定された SQL コマンドを実行します。

SQL_COMMAND は、実行される SQL コマンドです。

--delimiter tsv 形式で情報を出力する場合の区切り文字。省略した場合は \t。

-W 2 秒ごとにクエリーを自動的に再実行します。

-w / --watch 指定された間隔でクエリーを自動的に再実行します。

TIME は、再実行の間隔 (秒単位) です。

例

postgres ユーザーとして SQL コマンドを実行し、パスワードを要求します。

$ patronictl -c postgres0.yml query batman -U postgres --password -c "SELECT now()"
Password:
now
2023-09-12 18:10:53.228084+00:00

postgres ユーザーとして SQL コマンドを実行し、libpq 環境変数からパスワードを取得します。

$ PGPASSWORD=patroni patronictl -c postgres0.yml query batman -U postgres -c "SELECT now()"
now
2023-09-12 18:11:37.639500+00:00

SQL コマンドを実行し、2 秒ごとに pretty 形式で出力します。

$ patronictl -c postgres0.yml query batman -c "SELECT now()" --format pretty -W
+----------------------------------+
| now                              |
+----------------------------------+
| 2023-09-12 18:12:16.716235+00:00 |
+----------------------------------+
+----------------------------------+
| now                              |
+----------------------------------+
| 2023-09-12 18:12:18.732645+00:00 |
+----------------------------------+
+----------------------------------+
| now                              |
+----------------------------------+
| 2023-09-12 18:12:20.750573+00:00 |
+----------------------------------+

データベース test で SQL コマンドを実行し、出力を YAML 形式で出力します。

$ patronictl -c postgres0.yml query batman -d test -c "SELECT now() AS column_1, 'test' AS column_2" --format yaml
- column_1: 2023-09-12 18:14:22.052060+00:00
  column_2: test

メンバー postgresql2 に対して SQL コマンドを実行します。

$ patronictl -c postgres0.yml query batman -m postgresql2 -c "SHOW port"
port
5434

いずれかのスタンバイで SQL コマンドを実行します。

$ patronictl -c postgres0.yml query batman -r replica -c "SHOW port"
port
5433

patronictl reinit

書式 

reinit
  CLUSTER_NAME
  [ MEMBER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ --wait ]
  [ --force ]
  [ --from-leader ]

説明

patronictl reinit は、Patroni クラスターのレプリカ メンバーによって管理される Postgres スタンバイ インスタンスを再構築します。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

MEMBER_NAME Postgres インスタンスが再構築されるレプリカ メンバーの名前。

複数のレプリカ メンバーを指定できます。メンバーが指定されていない場合、コマンドは何も行いません。

--group 指定された Citus グループのレプリカ メンバーを再構築します。

CITUS_GROUP は、Citus グループの ID です。

--wait Postgres スタンバイ ノードの再初期化が完了するまで待ちます。

--force Postgres スタンバイ インスタンスを再構築するときに確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

--from-leader リーダーからベースバックアップを直接取得するためのフラグ。

例

Patroni クラスターのすべてのレプリカ メンバーの再構築を要求し、すぐに呼び出し元に制御を返します。

$ patronictl -c postgres0.yml reinit batman postgresql1 postgresql2 --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member postgresql1
Success: reinitialize for member postgresql2

postgresql2 の再構築をリクエストし、完了するまで待ちます。

$ patronictl -c postgres0.yml reinit batman postgresql2 --wait --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member postgresql2
Waiting for reinitialize to complete on: postgresql2
Reinitialize is completed on: postgresql2

postgresql2 の再構築をリクエストし、リーダーから直接ベースバックアップを取得します。

$ patronictl -c postgres0.yml reinit batman postgresql2 --from-leader
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member postgresql2

patronictl reload

書式 

reload
  CLUSTER_NAME
  [ MEMBER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ { -r | --role } { leader | primary | standby-leader | replica | standby | any } ]
  [ --force ]

説明

patronictl reload は、1 つ以上の Patroni メンバーのローカル構成のリロードを要求します。

また、何も変更されていない場合でも、管理対象の Postgres インスタンスで pg_ctl reload がトリガーされます。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

MEMBER_NAME 指定された Patroni メンバーのローカル構成のリロードを要求します。

複数のメンバーを指定できます。メンバーが指定されていない場合は、すべてのメンバーが考慮されます。

--group 指定された Citus グループのメンバーのリロードを要求します。

CITUS_GROUP は、Citus グループの ID です。

-r / --role 指定されたロールを持つメンバーを選択します。

役割は次のいずれかになります。

  • leader: 通常の Patroni クラスターまたはスタンバイ Patroni クラスターのリーダー。または
  • primary: 通常の Patroni クラスターのリーダー。または
  • standby-leader: スタンバイ Patroni クラスターのリーダー。または
  • replica: Patroni クラスターのレプリカ。または
  • standby: replica と同じ。または
  • any: 任意のロール。このパラメータを省略した場合と同じです。

--force ローカル構成のリロードを要求するときに確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

Patroni クラスターのすべてのメンバーのローカル構成のリロードを要求します。

$ patronictl -c postgres0.yml reload batman --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Reload request received for member postgresql0 and will be processed within 10 seconds
Reload request received for member postgresql1 and will be processed within 10 seconds
Reload request received for member postgresql2 and will be processed within 10 seconds

patronictl remove

書式 

remove
  CLUSTER_NAME
  [ --group CITUS_GROUP ]
  [ { -f | --format } { pretty | tsv | json | yaml } ]

説明

patronictl remove は、DCS からクラスターの情報を削除します。

インタラクティブなアクションです。

警告

この操作は、DCS から Patroni クラスターの情報を破棄します。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

--group 指定された Citus グループに関連する Patroni クラスターに関する情報を削除します。

CITUS_GROUP は、Citus グループの ID です。

-f / --format 確認を求めるプロンプトが表示されるときに、出力内のメンバーのリストをフォーマットする方法。

形式は次のいずれかになります。

  • pretty: メンバーを美しいテーブルとして出力します。または
  • tsv: \t で区切られた列を含む表形式の情報としてメンバーを出力します。または
  • json: メンバーを JSON 形式で出力します。または
  • yaml: メンバーを YAML 形式で出力します。

デフォルトは pretty です。

例

Patroni クラスター batman に関する情報を DCS から削除します。

$ patronictl -c postgres0.yml remove batman
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Please confirm the cluster name to remove: batman
You are about to remove all information in DCS for batman, please type: "Yes I am aware": Yes I am aware
This cluster currently is healthy. Please specify the leader name to continue: postgresql0

patronictl restart

書式 

restart
  CLUSTER_NAME
  [ MEMBER_NAME [, ...] ]
  [ --group CITUS_GROUP ]
  [ { -r | --role } { leader | primary | standby-leader | replica | standby | any } ]
  [ --any ]
  [ --pg-version PG_VERSION ]
  [ --pending ]
  [ --timeout TIMEOUT ]
  [ --scheduled TIMESTAMP ]
  [ --force ]

説明

patronictl restart は、Patroni クラスターのメンバーによって管理される Postgres インスタンスの再起動を要求します。

再起動はすぐに実行することも、後で実行するようにスケジュールすることもできます。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

--group 指定された Citus グループに関連する Patroni クラスターを再起動します。

CITUS_GROUP は、Citus グループの ID です。

-r / --role 指定されたロールを持つメンバーを選択します。

役割は次のいずれかになります。

  • leader: 通常の Patroni クラスターまたはスタンバイ Patroni クラスターのリーダー。または
  • primary: 通常の Patroni クラスターのリーダー。または
  • standby-leader: スタンバイ Patroni クラスターのリーダー。または
  • replica: Patroni クラスターのレプリカ。または
  • standby: replica と同じ。または
  • any: 任意のロール。このパラメータを省略した場合と同じです。

--any 指定されたフィルターに一致するノードの中からランダムな 1 つのノードを再起動します。

--pg-version 管理対象 Postgres インスタンスのバージョンが指定されたバージョンより古いメンバーのみを選択します。

PG_VERSION は、比較する Postgres バージョンです。

--pending Pending restart のフラグが付いているメンバーのみを選択します。

--timeout: 指定されたタイムアウトを超えて再起動がかかる場合は再起動を中止し、問題がプライマリーにある場合はレプリカにフェイルオーバーします。

TIMEOUT は、再起動を中止するまでに待機する秒数です。

--scheduled 指定されたタイムスタンプで再起動が行われるようにスケジュールします。

TIMESTAMP は、再起動が行われるときのタイムスタンプです。明確な形式で、できればタイムゾーンを使用して指定してください。リテラル now を使用して、再起動をすぐに実行することもできます。

--force 再起動操作を要求するときに確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

クラスターのすべてのメンバーをすぐに再起動します。

$ patronictl -c postgres0.yml restart batman --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  6 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: restart on member postgresql0
Success: restart on member postgresql1
Success: restart on member postgresql2

クラスターのランダムなメンバーをすぐに再起動します。

$ patronictl -c postgres0.yml restart batman --any --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  6 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: restart on member postgresql1

2023-09-13T18:00-03:00 で再起動が行われるようにスケジュールします。

$ patronictl -c postgres0.yml restart batman --scheduled 2023-09-13T18:00-03:00 --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  6 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: restart scheduled on member postgresql0
Success: restart scheduled on member postgresql1
Success: restart scheduled on member postgresql2

patronictl resume

書式 

resume
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ --wait ]

説明

patronictl resume は、Patroni クラスターのメンテナンス モードを解除し、自動フェイルオーバーを再度有効にします。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループを再開します。

CITUS_GROUP は、Citus グループの ID です。

指定しない場合、patronictl は、citus.group 構成が存在する場合は、そこからそれを取得しようとします。

--wait すべての Patroni メンバーの一時停止が解除されるまで待ってから、呼び出し元に制御を返します。

例

クラスターをメンテナンス モードから解除します。

$ patronictl -c postgres0.yml resume batman --wait
'resume' request sent, waiting until it is recognized by all nodes
Success: cluster management is resumed

patronictl show-config

書式 

show-config
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]

説明

patronictl show-config は、DCS に保存されているクラスターの動的構成を示します。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループの動的構成を表示します。

CITUS_GROUP は、Citus グループの ID です。

指定しない場合、patronictl は、citus.group 構成が存在する場合は、そこからそれを取得しようとします。

例

クラスター batman の動的構成を表示します。

$ patronictl -c postgres0.yml show-config batman
loop_wait: 10
postgresql:
  parameters:
    max_connections: 250
  pg_hba:
  - host replication replicator 127.0.0.1/32 md5
  - host all all 0.0.0.0/0 md5
  use_pg_rewind: true
retry_timeout: 10
ttl: 30

patronictl switchover

書式 

switchover
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { --leader | --primary } LEADER_NAME ]
  --candidate CANDIDATE_NAME
  [ --force ]

説明

patronictl switchover はクラスター内でスイッチオーバーを実行します。

これは、クラスターが正常な場合に使用されるように設計されています。例:

  • リーダーがいます。
  • 同期クラスターでは使用可能な同期スタンバイがあります。
注記

クラスターが正常でない場合は、代わりに patronictl failover に興味があるかもしれません。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループでスイッチオーバーを実行します。

CITUS_GROUP は、Citus グループの ID です。

--leader / --primary スイッチオーバー時に降格されるリーダーを示します。

LEADER_NAME は、クラスター内の現在のリーダーの名前と一致させるべきです。

--candidate スイッチオーバー時に昇格され、プライマリーの役割を担うノード。

CANDIDATE_NAME は、昇格するノードの名前です。

--scheduled 指定されたタイムスタンプでスイッチオーバーが発生するようにスケジュールします。

TIMESTAMP は、スイッチオーバーが発生するときのタイムスタンプです。明確な形式で、できればタイムゾーンを使用して指定してください。リテラル now を使用してスイッチオーバーを即時に実行することもできます。

--force スイッチオーバーの実行時に確認プロンプトをスキップするためのフラグ。

スクリプトに便利です。

例

ノード postgresql2 にスイッチオーバーします。

$ patronictl -c postgres0.yml switchover batman --leader postgresql0 --candidate postgresql2 --force
Current cluster topology
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  6 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  6 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
2023-09-13 14:15:23.07497 Successfully switched over to "postgresql2"
+ Cluster: batman (7277694203142172922) -+---------+----+-------------+---------+------------+---------+
| Member      | Host           | Role    | State   | TL | Receive LSN |     Lag | Replay LSN |     Lag |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+
| postgresql0 | 127.0.0.1:5432 | Replica | stopped |    |     unknown | unknown |    unknown | unknown |
| postgresql1 | 127.0.0.1:5433 | Replica | running |  6 |   0/4000188 |       0 |  0/4000188 |       0 |
| postgresql2 | 127.0.0.1:5434 | Leader  | running |  6 |             |         |            |         |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+

postgresql0 と postgresql2 の間のスイッチオーバーが 2023-09-13T18:00:00-03:00 で発生するようにスケジュールします。

$ patronictl -c postgres0.yml switchover batman --leader postgresql0 --candidate postgresql2 --scheduled 2023-09-13T18:00-03:00 --force
Current cluster topology
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  8 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  8 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  8 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
2023-09-13 14:18:11.20661 Switchover scheduled
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  8 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  8 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  8 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Switchover scheduled at: 2023-09-13T18:00:00-03:00
                    from: postgresql0
                    to: postgresql2

patronictl topology

書式 

topology
  [ CLUSTER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ { -W | { -w | --watch } TIME } ]

説明

patronictl topology は、Patroni クラスターとそのメンバーに関する情報をツリー ビュー アプローチで表示します。

出力には次の情報が含まれます。

Cluster Patroni クラスターの名前。

注記

テーブルヘッダーに表示されます。

System identifier Postgres システム識別子。

注記

テーブルヘッダーに表示されます。

Member Patroni メンバーの名前。

注記

この列の情報は、レプリケーション接続に関するメンバーのツリー ビューとして表示されます。

Host メンバーが配置されているホスト。

Role メンバーの現在の役割。

次のいずれかになります:

  • Leader: 通常の Patroni クラスターの現在のリーダー。または
  • Standby Leader: Patroni スタンバイ クラスターの現在のリーダー。または
  • Sync Standby: 同期モードが有効になっている Patroni クラスターの同期スタンバイ。または
  • Replica: Patroni クラスターの通常のスタンバイ。

State Patroni メンバーの Postgres の現在の状態。

考えられる状態の例をいくつか示します。

  • running: Postgres が現在稼働している場合。
  • streaming: レプリカであり、Postgres が現在プライマリー ノードから WAL をストリーミングしている場合。
  • in archive recovery: レプリカであり、Postgres が現在アーカイブから WAL をフェッチしている場合。
  • stopped: Postgres がシャットダウンされていた場合。
  • crashed: Postgres がクラッシュした場合。

TL Patroni メンバー内の現在の Postgres タイムライン。

Receive LSN メンバーのストリーミング レプリケーションによって受信され、ディスクに同期された最後の先行書き込みログの場所 (pg_catalog.pg_last_(xlog|wal)_receive_(location|lsn)())。

Receive Lag メンバーの Receive LSN 位置とその上流との間のレプリケーション ラグ (MB 単位)。

Replay LSN メンバーのリカバリ中に再生された最後の先行書き込みログの場所 (pg_catalog.pg_last_(xlog|wal)_replay_(location|lsn)())。

Replay Lag メンバーの Replay LSN 位置とその上流との間のレプリケーション ラグ (MB 単位)。

それに加えて、次の情報が出力に含まれる場合があります。

Group Citus グループ ID。

注記

テーブルヘッダーに表示されます。

Citus クラスターの場合にのみ表示されます。

Pending restart * は、一部の Postgres 構成を有効にするためにノードの再起動が必要であることを示します。空の値は、ノードを再起動する必要がないことを示します。

注記

メンバー属性として表示されます。

ノードの再起動が必要な場合に表示されます。

Scheduled restart Patroni メンバーによって管理される Postgres インスタンスの再起動がスケジュールされたタイムスタンプ。空の値は、メンバーにスケジュールされた再起動がないことを示します。

注記

メンバー属性として表示されます。

ノードにスケジュールされた再起動がある場合に表示されます。

Tags Patroni メンバーに設定されたタグが含まれます。空の値は、タグが設定されていないか、タグがデフォルト値で設定されていることを示します。

注記

メンバー属性として表示されます。

ノードにカスタム タグがある場合、またはデフォルト以外の値を持つデフォルト タグがある場合に表示されます。

Scheduled switchover Patroni クラスターのスイッチオーバーがスケジュールされている場合のタイムスタンプ。

注記

テーブルのフッターに表示されます。

スケジュールされたスイッチオーバーがある場合にのみ表示されます。

Maintenance mode

クラスター監視が現在一時停止されている場合。

注記

テーブルのフッターに表示されます。

クラスターが一時停止されている場合にのみ表示されます。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

指定しない場合、patronictl は、scope 構成が存在する場合は、そこからそれを取得しようとします。

--group 指定された Citus グループのメンバーに関する情報を表示します。

CITUS_GROUP は、Citus グループの ID です。

-W 2 秒ごとに情報を自動的に更新します。

-w / --watch 指定した間隔で情報を自動的に更新します。

TIME は、更新間の間隔 (秒単位) です。

例

クラスター batman のトポロジを表示します – postgresql1 と postgresql2 は postgresql0 からレプリケートされています。

$ patronictl -c postgres0.yml topology batman
+ Cluster: batman (7277694203142172922) ---+-----------+----+-------------+-----+------------+-----+
| Member        | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0   | 127.0.0.1:5432 | Leader  | running   |  8 |             |     |            |     |
| + postgresql1 | 127.0.0.1:5433 | Replica | streaming |  8 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| + postgresql2 | 127.0.0.1:5434 | Replica | streaming |  8 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+---------------+----------------+---------+-----------+----+-------------+-----+------------+-----+

patronictl version

書式 

version
  [ CLUSTER_NAME [, ... ] ]
  [ MEMBER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]

説明

patronictl version は、patronictl アプリケーションのバージョンを取得します。それに加えて、Patroni クラスターとそのメンバーに関するバージョン情報も含まれる場合があります。

パラメータ

CLUSTER_NAME Patroni クラスターの名前。

MEMBER_NAME Patroni クラスターのメンバーの名前。

--group 指定された Citus グループを持つ Patroni クラスターを対象とします。

CITUS_GROUP は、Citus グループの ID です。

例

patronictl のバージョンのみを取得します。

$ patronictl -c postgres0.yml version
patronictl version 4.0.0

patronictl とクラスター batman のすべてのメンバーのバージョンを取得します。

$ patronictl -c postgres0.yml version batman
patronictl version 4.0.0

postgresql0: Patroni 4.0.0 PostgreSQL 16.4
postgresql1: Patroni 4.0.0 PostgreSQL 16.4
postgresql2: Patroni 4.0.0 PostgreSQL 16.4

patronictl と、クラスター batman のメンバー postgresql1 および postgresql2 のバージョンを取得します。

$ patronictl -c postgres0.yml version batman postgresql1 postgresql2
patronictl version 4.0.0

postgresql1: Patroni 4.0.0 PostgreSQL 16.4
postgresql2: Patroni 4.0.0 PostgreSQL 16.4

6 - レプリカのイメージングとブートストラップ

レプリカのイメージング、ブートストラップ、およびカスタム レプリカ作成のワークフロー。

Patroni を使用すると、新しいレプリカの作成をカスタマイズできます。また、新しい空のクラスターがブートストラップされるときに何が起こるかの定義もサポートします。 2 つの区別は明確に定義されています。Patroni は、initialize キーがクラスターの DCS に存在する場合にのみレプリカを作成します。 initialize キーがない場合、Patroni は初期化キー ロックを取得する最初のノードで排他的にブートストラップを呼び出します。

ブートストラップ

PostgreSQL は、新しいクラスターを初期化するための initdb コマンドを提供し、 Patroni はデフォルトでそれを呼び出します。場合によっては、特に既存のクラスターのコピーとして新しいクラスターを作成する場合、組み込みメソッドをカスタム アクションに置き換える必要があります。 Patroni は、新しいクラスターをブートストラップするためのユーザー定義スクリプトの実行をサポートし、クラスターの名前とデータ ディレクトリへのパスなど、いくつかの必要な引数を指定します。これは、Patroni 構成の bootstrap セクションで構成されます。たとえば:

bootstrap:
    method: <custom_bootstrap_method_name>
    <custom_bootstrap_method_name>:
        command: <path_to_custom_bootstrap_script> [param1 [, ...]]
        keep_existing_recovery_conf: False
        no_params: False
        recovery_conf:
            recovery_target_action: promote
            recovery_target_timeline: latest
            restore_command: <method_specific_restore_command>

各カスタムブートストラップメソッドは、methodで名前を指定し、その名前のセクションでcommandを定義しなければなりません。特別な initdb メソッドを使用してデフォルトの動作をトリガーできます。この場合、method パラメーターは完全に省略できます。 commandには、絶対パス、Patroniの作業ディレクトリを基準とした相対パス、またはPATHで利用可能なコマンド名を指定できます。構成ファイルで定義された固定パラメーターに加えて、Patroni はクラスター固有のパラメーターを 2 つ提供します。

--scope
ブートストラップされるクラスターの名前

--datadir
ブートストラップされるクラスター インスタンスのデータ ディレクトリへのパス

これら 2 つの追加フラグの受け渡しを無効にするには、特別な no_params パラメーターを True に設定します。

ブートストラップ スクリプトが 0 を返した場合、Patroni は、それによって生成された PostgreSQL インスタンスを構成して起動しようとします。中間ステップのいずれかが失敗するか、スクリプトがゼロ以外の値を返した場合、Patroni はブートストラップが失敗したものとみなし、その後クリーンアップして初期化ロックを解放し、別のノードにブートストラップの機会を与えます。

recovery_conf ブロックがカスタム ブートストラップ メソッドと同じセクションで定義されている場合、Patroni は、新しくブートストラップされたインスタンスを開始する前に recovery.conf を生成します (または、PostgreSQL >= 12 を実行している場合は、Postgres 構成にリカバリ設定を設定します)。通常、このようなリカバリー構成には、promoteに設定したrecovery_target_actionとともに、少なくとも1つのrecovery_target_*パラメーターを含めることを推奨します。

keep_existing_recovery_conf が定義され、True に設定されている場合、Patroni は既存の recovery.conf ファイルが存在する場合は削除しません (PostgreSQL <= 11)。同様に、その場合、Patroni は、既存の recovery.signal または standby.signal が存在する場合は削除しません。また、構成されたリカバリ設定 (PostgreSQL >= 12) をオーバーライドすることもありません。これは、適切なリカバリ構成を生成する pgBackRest などのツールを使用してバックアップからブートストラップする場合に便利です。

それに加えて、カスタム ブートストラップ メソッド設定で指定された追加のキーと値のペアは、引数として --name=value 形式で command に渡されます。たとえば:

bootstrap:
    method: <custom_bootstrap_method_name>
    <custom_bootstrap_method_name>:
        command: <path_to_custom_bootstrap_script>
        arg1: value1
        arg2: value2

この構成では、commandが追加の--arg1=value1 --arg2=value2コマンドライン引数を付けて呼び出されます。

注記

ブートストラップメソッドは連鎖して実行されません。また、指定したメソッドが失敗してもデフォルトのメソッドにフォールバックしません。

たとえば、次のような構成を使用して、Barman バックアップから新しい Patroni クラスターをブートストラップできます。

bootstrap:
    method: barman
    barman:
        keep_existing_recovery_conf: true
        command: patroni_barman --api-url https://barman-host:7480 recover
        barman-server: my_server
        ssh-command: ssh postgres@patroni-host
注記

patroni_barman recover では、バックアップ API を介してリモート barman recover を実行できるように、Barman ホストに Barman と pg-backup-api の両方が構成されている必要があります。上の例では、使用可能なパラメータのサブセットを使用しています。 patroni_barman recover --help を実行すると、詳細情報を取得できます。

レプリカの構築

Patroni は、新しいレプリカを作成するために、実証済みの pg_basebackup を使用します。実行中のコピー元PostgreSQLインスタンスが必要であり、古いバックアップファイルを削除する機能は組み込まれていません。 WAL-E、pgBackRest、Barman などの他のバックアップ ソリューションを好んだり、単に独自のスクリプトを使用したりする人もいます。これらすべてのユースケースに対応するために、Patroni は新しいレプリカのクローンを作成するためのカスタム スクリプトの実行をサポートしています。これらは postgresql 構成ブロックで構成されます。

postgresql:
    create_replica_methods:
        - <method name>
    <method name>:
        command: <command name>
        keep_data: True
        no_params: True
        no_leader: 1

例: wal_e

postgresql:
    create_replica_methods:
        - wal_e
        - basebackup
    wal_e:
        command: patroni_wale_restore
        no_leader: 1
        envdir: '{{WALE_ENV_DIR}}'
        use_iam: 1
    basebackup:
        max-rate: '100M'

例: pgbackrest

postgresql:
    create_replica_methods:
        - pgbackrest
        - basebackup
    pgbackrest:
        command: /usr/bin/pgbackrest --stanza=<scope> --delta restore
        keep_data: True
        no_params: True
    basebackup:
        max-rate: '100M'

例: Barman

postgresql:
    create_replica_methods:
        - barman
        - basebackup
    barman:
        command: patroni_barman --api-url https://barman-host:7480 recover
        barman-server: my_server
        ssh-command: ssh postgres@patroni-host
    basebackup:
        max-rate: '100M'
注記

patroni_barman recover では、バックアップ API を介してリモート barman recover を実行できるように、Barman ホストに Barman と pg-backup-api の両方が構成されている必要があります。上の例では、使用可能なパラメータのサブセットを使用しています。 patroni_barman recover --help を実行すると、詳細情報を取得できます。

create_replica_methods は、使用可能なレプリカ作成メソッドとその実行順序を定義します。 Patroni は、0 を返す最初のもので停止します。各メソッドには、構成ファイル内に個別のセクションを用意し、実行するコマンドと渡すカスタムパラメーターを記載することを推奨します。すべてのパラメータは --name=value 形式で渡されます。ユーザー定義のパラメーターの他に、Patroni はクラスター固有のパラメーターをいくつか提供します。

--scope
このレプリカが属するクラスター

--datadir
レプリカのデータ ディレクトリへのパス

--role
常に ‘replica’

--connstring
クローン作成元のクラスター メンバーに接続するための接続文字列 (プライマリーまたは他のレプリカ)。接続文字列内のユーザーは、SQL およびレプリケーション プロトコル コマンドを実行できます。

特別なno_leaderパラメーターを有効にすると、実行中のリーダーまたはレプリカがない場合でも、Patroni がレプリカ作成メソッドを呼び出すことができます。その場合、接続文字列には空の文字列が渡されます。これは、以前に実行していたクラスターをバイナリ バックアップから復元する場合に便利です。

特別なkeep_dataパラメーターを有効にすると、復元を呼び出す前に PGDATA フォルダーをクリーンアップしないように Patroni に指示します。

特別なno_paramsパラメーターを有効にすると、カスタムコマンドへのクラスター固有のパラメーターの自動追加が無効になります。ユーザー定義のパラメーターは引き続き渡されます。

basebackup メソッドは特殊なケースです。create_replica_methods が空の場合に使用されますが、create_replica_methods メソッドの中に明示的にリストすることは可能です。このメソッドは、pg_basebackup を使用して新しいレプリカを初期化し、clonefrom タグが付いたレプリカがない限り、ベース バックアップはリーダーから取得されます。その場合、そのようなレプリカの 1 つが pg_basebackup のオリジンとして使用されます。設定なしで動作します。ただし、basebackup 構成セクションを指定することは可能です。他のメソッド設定と同じルールが適用されます。つまり、長い (– 付き) オプションのみを指定する必要があります。Patroniは、接続設定の上書きや、tar形式またはクライアント側で圧縮されたバックアップを作成するオプションを受け付けません。PostgreSQL 15以降では、compress: server-gzipまたはcompress: server-zstdによるサーバー側の圧縮をサポートしています。Patroniは、自身が制御するオプションやサーバー側の圧縮以外の圧縮設定を除外しますが、すべてのオプション名と値を完全に検証するわけではありません。また、WAL フォルダーにシンボリックリンクが使用されている場合、レプリカの構築または再初期化後にシンボリックリンクが保持されるように、オプションとして正しい --waldir パスを指定するのはユーザーの責任であることに注意してください。ただし、このオプションは v10 以降でのみサポートされています。

basebackup パラメータは、マップ (キーと値のペア) または要素のリストとして指定できます。各要素は、キーと値のペアまたは単一のキー (値を受け取らないオプションの場合、たとえば --verbose) のいずれかになります。これら 2 つの例を見てみましょう。

postgresql:
    basebackup:
        max-rate: '100M'
        checkpoint: 'fast'

そして

postgresql:
    basebackup:
        - verbose
        - max-rate: '100M'
        - waldir: /pg-wal-mount/external-waldir

すべてのレプリカ作成メソッドが失敗した場合、Patroni は次のイベント ループ サイクル中にすべてのメソッドを順番に再試行します。

7 - レプリケーションモード

Patroniが管理する非同期・同期レプリケーションモード。

PatroniはPostgreSQLのストリーミングレプリケーションを使用します。ストリーミングレプリケーションの詳細はPostgresのドキュメント を参照してください。デフォルトでは、PatroniはPostgreSQLに非同期レプリケーションを設定します。レプリケーション方式の選択は業務上の要件によって異なります。非同期と同期の両方式、および他の高可用性ソリューションを検討し、最適なものを判断してください。

非同期モードの永続性

非同期モードでは、可用性を確保するために、コミット済みトランザクションの一部が失われることを許容します。プライマリーサーバーに障害が発生した場合や、その他の理由で利用不能になった場合、Patroniは十分に正常なスタンバイを自動的にプライマリーへ昇格させます。そのスタンバイにレプリケーションされていないトランザクションは、プライマリー上の「分岐したタイムライン」に残り、事実上リカバリーできません1。

失われる可能性があるトランザクション量は、maximum_lag_on_failoverパラメーターで制御します。プライマリーのトランザクションログ位置をリアルタイムには取得しないため、フェイルオーバー時に失われるデータ量の実際の最悪値は、maximum_lag_on_failoverバイトのトランザクションログに、直近のttl秒間（平均ではloop_wait/2秒間）に書き込まれた量を加えたものです。ただし、通常の定常状態でのレプリケーション遅延は1秒を大幅に下回ります。

デフォルトでは、Patroniはリーダー選出時にレプリカの現在のタイムラインを考慮しません。これは状況によっては望ましくない動作です。check_timelineをtrueに設定すると、タイムラインがクラスターで最後に確認されたものより古いノードや、タイムラインを特定できないノードが新しいリーダーになることを防げます。

PostgreSQLの同期レプリケーション

Patroniでは、Postgresの同期レプリケーション を使用できます。同期レプリケーションでは、接続元のクライアントに成功を返す前に、書き込みがセカンダリーに保存されたことを確認し、クラスター全体の整合性を確保します。その代償として、書き込みのレイテンシーが増加し、スループットが低下します。このスループットはネットワーク性能の影響を受けます。

ホスティング型のデータセンター環境（AWS、Rackspaceなど、または自分で制御できないネットワーク）では、同期レプリケーションにより書き込み性能の変動が大幅に増加します。リーダーからフォロワーに到達できなくなると、リーダーは実質的に読み取り専用になります。

簡単な同期レプリケーションのテストを有効にするには、YAML設定ファイルのparametersセクションに次の行を追加します。

synchronous_commit: "on"
synchronous_standby_names: "*"

PostgreSQLの同期レプリケーションを使用する場合は、ホスト1台が故障しても書き込み可用性を確保できるよう、少なくとも3つのPostgresデータノードを使用してください。

PostgreSQLの同期レプリケーションを使用しても、あらゆる状況でトランザクションが一切失われないことを保証するわけではありません。プライマリーと現在同期レプリカとして動作しているセカンダリーが同時に故障すると、すべてのトランザクションを保持しているとは限らない3つ目のノードが昇格します。

同期モード

コミット済みトランザクションの損失を許容できない場合は、Patroniのsynchronous_mode を有効にできます。synchronous_mode を有効にすると、クライアントにコミット成功を返した可能性があるすべてのトランザクションをスタンバイが保持していると確信できない限り、Patroniはそのスタンバイを昇格させません2。つまり、一部のサーバーが利用可能でも、システムへの書き込みができない場合があります。システム管理者は、トランザクションが失われる場合でも、手動フェイルオーバーコマンドでスタンバイを昇格させることができます。

synchronous_mode を有効にしても、あらゆる状況で複数ノードにコミットが永続化されることを保証するわけではありません。適切なスタンバイが利用できない場合も、プライマリーは書き込みを受け付けますが、そのレプリケーションは保証しません。このモードでプライマリーが故障すると、スタンバイは昇格しません。以前のプライマリーのホストが復帰すると、管理者が手動フェイルオーバーを行っていない限り、自動的に昇格します。この動作により、2ノードのクラスターでも同期モードを使用できます。

synchronous_mode が有効で厳密モードが無効な状態で、唯一の同期スタンバイがクラッシュすると、Patroniの次の処理サイクルでプライマリーを単独動作モードへ切り替えるまで、コミットはブロックされます。書き込みの遅延は最悪でttl秒、平均でloop_wait/2秒です。スタンバイを手動で停止または再起動する場合は、コミット処理が中断されません。PostgreSQLの停止を開始する前に、スタンバイは同期スタンバイの役割から自身を外すようプライマリーに通知します。

各書き込みが少なくとも2つのノードに永続保存されることを必ず保証する必要がある場合は、synchronous_mode に加えてsynchronous_mode_strictを有効にしてください。このパラメーターは、同期スタンバイの候補が存在しない場合にPatroniがプライマリーの同期レプリケーションを無効にすることを防ぎます。同期コミットは同期レプリカが利用可能になるまでブロックされます。synchronous_commitがoffまたはlocalのトランザクションは、この待機を回避します。

優先順位に基づく同期モード（synchronous_mode: on）で厳密モードが有効であり、適切な同期スタンバイが利用できない場合、Patroni 4.1.5はsynchronous_standby_namesを*に設定し、警告"No standbys available!"を出力します。これにより、コミットは同期スタンバイを待ち続けます。このワイルドカードは、確認応答の送信元を/syncに以前記録されていたメンバー名に限定しません。

nosyncタグをtrueに設定すると、Patroniはそのスタンバイを同期スタンバイの選択対象から除外します。低速なネットワーク経由で接続されており、同期スタンバイになると性能が低下するスタンバイには、この設定を推奨します。nostreamタグをtrueに設定しても同じ効果があります。

同期モードは、patronictl edit-configコマンドまたはPatroniのRESTインターフェースで有効・無効を切り替えられます。手順は動的設定 を参照してください。

注意：PostgreSQLの同期レプリケーションの実装上、synchronous_mode_strictを使用していてもトランザクションが失われる可能性があります。クライアントのタイムアウトによるキャンセルパケットやバックエンド障害により、レプリケーションの確認を待っているPostgreSQLバックエンドがキャンセルされると、そのトランザクションの変更は他のバックエンドから見えるようになります。これらの変更はまだレプリケーションされていないため、スタンバイが昇格すると失われる可能性があります。

同期レプリケーション係数

Patroniはsynchronous_node_countパラメーターで同期スタンバイデータベースの数を管理します。デフォルトは1です。synchronous_mode がoffの場合、このパラメーターは効果を持ちません。有効な場合は、Patroniがsynchronous_node_countに基づいて同期スタンバイデータベースの正確な数を管理し、メンバーの参加・離脱に合わせてDCSの状態とPostgreSQLのsynchronous_standby_namesを調整します。適格なノードが不足している場合、Patroniが使用する同期スタンバイは要求された数より少なくなることがあります。ただし、厳密なクォーラムモードでは、コミットは設定された数のスタンバイからの確認応答を待ち続けます。

同期ノードの最大遅延

デフォルトでは、Patroniは他のノードの方が先に進んでいても、pg_stat_replicationビューでsynchronousとされているノードを維持します。これはsynchronous_standby_namesの変更回数を最小限にするためです。この動作を変更するには、maximum_lag_on_syncnodeパラメーターを使用できます。レプリカを「同期」とみなせる遅延量の上限を制御します。

スタンバイが複数ある場合、Patroniはレプリカの最大LSNを使用します。それ以外の場合は、リーダーの現在のWAL LSNを使用します。デフォルトは-1で、値が0以下の場合、Patroniは正常でない同期スタンバイを入れ替えません。トランザクション量が多いときに同期スタンバイが頻繁に入れ替わらないよう、十分大きな値を設定してください。

同期モードの実装

同期モードでは、PatroniはDCSの/syncキーに、最新のプライマリーと現在の同期スタンバイデータベースを含む同期状態を保持します。この状態を厳密な順序制約に従って更新し、次の不変条件を保証します。

  • 書き込みトランザクションを受け付けられるノードは、常に最新のリーダーとして記録されていなければなりません。PatroniのクラッシュやPostgreSQLが停止しない状況は、この不変条件に違反する原因になります。
  • DCSの/syncキーに同期スタンバイとして公開されている限り、そのノードはPostgreSQLでも同期スタンバイに設定されていなければなりません。
  • リーダーでも現在の同期スタンバイでもないノードは、自動的に自身を昇格させることができません。

同期スタンバイの集合が空でない場合、Patroniはsynchronous_node_countに基づき、1つ以上の同期スタンバイノードをsynchronous_standby_namesに設定します。

PatroniはHAループの反復ごとに同期スタンバイの選択を見直します。現在の同期スタンバイが接続されており、同期状態の解除を要求していなければ、その選択を維持します。それ以外の場合は、同期可能なクラスターメンバーのうち、レプリケーションが最も先に進んでいるものを選びます。

例:

DCSの/configキー 

synchronous_mode: on
synchronous_node_count: 2
...

DCSの/syncキー 

{
    "leader": "node0",
    "sync_standby": "node1,node2"
}

postgresql.conf 

synchronous_standby_names = 'FIRST 2 (node1,node2)'

上記の例では、同期していると確認されているのはnode1とnode2だけであり、プライマリー（node0）が故障した場合に自動昇格が許可されるのも、これらのノードだけです。

クォーラムコミットモード

PostgreSQL v10以降、Patroniはクォーラムに基づく同期レプリケーションをサポートしています。

このモードでは、Patroniは最後に確認されたプライマリー、クォーラムに必要なノード数、現在クォーラムへの投票資格があるノードを含む同期状態をDCSに保持します。定常状態では、投票ノードはリーダーとすべての同期スタンバイです。この状態を、ノードの昇格とsynchronous_standby_namesに関する厳密な順序制約に従って更新します。その結果、クォーラムを構成できる投票ノードのどの部分集合にも、最後に成功したコミットを保持するノードが少なくとも1つ含まれることを常に保証します。

PatroniはHAループの反復ごとに、ノードの可用性と要求されたクラスター設定に基づいて、同期スタンバイとクォーラムの選択を見直します。PostgreSQL 9.6より新しいバージョンでは、適格なすべてのノードを、レプリケーションがリーダーに追いつき次第、同期スタンバイに追加します。

クォーラムコミットでは、あるスタンバイへのレプリケーション遅延が増えても、他のスタンバイが補えるため、通常の運用中も含めて最悪時のレイテンシーを減らせます。

クォーラムに基づく同期モードを有効にするには、patronictl edit-configコマンドまたはPatroniのRESTインターフェースで、synchronous_mode をquorumに設定します。手順は動的設定 を参照してください。

synchronous_node_count、maximum_lag_on_syncnode、synchronous_mode_strictなどの他のパラメーターは、synchronous_mode=onの場合と同様に機能します。

クォーラムコミットモードで同期スタンバイの集合が空であり、厳密モードでN台のスタンバイからの確認応答が必要な場合、Patroni 4.1.5はsynchronous_standby_namesをANY N (*)に設定します。

例:

DCSの/configキー 

synchronous_mode: quorum
synchronous_node_count: 2
...

DCSの/syncキー 

{
    "leader": "node0",
    "sync_standby": "node1,node2,node3",
    "quorum": 1
}

postgresql.conf 

synchronous_standby_names = 'ANY 2 (node1,node2,node3)'

上記の例でプライマリー（node0）が故障した場合、node1、node2、node3のうち2つは最新のトランザクションを受信していますが、それがどのノードかは分かりません。node1が最新のトランザクションを受信しているかを判断するには、node2とnode3のうち少なくとも1つ（/syncキーのquorum=1）のLSNと比較する必要があります。そのうち少なくとも1つよりnode1が遅れていなければ、node1を昇格してもユーザーに見えるデータ損失が生じないことを保証できます。

  1. データ自体は残っていますが、復元にはデータリカバリーの専門家による手作業が必要です。use_pg_rewindで巻き戻しを許可している場合、故障したプライマリーをクラスターに再参加させるために、分岐したタイムラインは自動的に消去されます。ただし、use_pg_rewindが正しく動作するには、data page checksums（initdbの--data-checksumsオプション）を有効にしてクラスターを初期化するか、wal_log_hintsをonに設定するか、その両方が必要です。 ↩︎

  2. クライアントは、PostgreSQLのsynchronous_commit設定でトランザクションごとに動作を変更できます。synchronous_commitがoffまたはlocalのトランザクションは、フェイルオーバーで失われる可能性がありますが、レプリケーション遅延によってブロックされません。 ↩︎

8 - スタンバイクラスター

スタンバイクラスターの設定、動作、リモートのプライマリーからのレプリケーション。

Patroniは、「スタンバイクラスター」と呼ばれる機能を使用して、リモートのデータセンター（リージョン）へのカスケードレプリケーションも実行できます。この種類のクラスターには、次の要素があります。

  • 「スタンバイリーダー」。リモートのノードからレプリケーションを行う点を除き、通常のクラスターリーダーとほぼ同じように動作します。
  • スタンバイリーダーからレプリケーションを行うカスケードレプリカ。

スタンバイリーダーはDCS内のリーダーロックを保持し、更新します。リーダーロックが期限切れになると、カスケードレプリカは選出を行い、スタンバイの中から別のリーダーを選びます。

スタンバイクラスターと、そのレプリケーション元のプライマリークラスターの間には、これ以外の関係はありません。特に、同じDCSを使用する場合、同じDCSスコープを共有してはなりません。互いに知っているのはレプリケーション情報だけです。また、プライマリークラスターで実行したpatronictl_list やpatronictl_topology の出力に、スタンバイクラスターは表示されません。

柔軟性を確保するため、standby_cluster セクションにcreate_replica_methods キーを指定することで、クラスターが「スタンバイモード」のときにレプリカを作成し、WALレコードをリカバリーする方法を指定できます。これは、クラスターを切り離して通常のクラスターとして動作させるときのレプリカ作成とは別のものです。通常のクラスターでの作成は、postgresqlセクションのcreate_replica_methodsで制御します。「スタンバイ」と「通常」の両方のcreate_replica_methodsは、postgresqlセクション内のキーを参照します。

このようなクラスターを構成するには、Patroniの構成にstandby_cluster セクションを指定する必要があります。

bootstrap:
    dcs:
        standby_cluster:
            host: 1.2.3.4
            port: 5432
            primary_slot_name: patroni
            create_replica_methods:
            - basebackup

これらのオプションはクラスターのブートストラップ時に一度だけ適用され、その後はDCSを通じてのみ変更できることに注意してください。

PatroniはリモートのプライマリーのPGDATA内にpostgresql.confまたはpostgresql.conf.backupがあることを想定しており、ベースバックアップ後に見つからなければ起動しません。リモートのプライマリーが別の場所にpostgresql.confを保存している場合、PGDATAへのコピーは利用者の責任で行ってください。

スタンバイクラスターでレプリケーションスロットを使用する場合は、プライマリークラスターにも対応するレプリケーションスロットを作成しなければなりません。スタンバイクラスターの実装では、自動的には作成されません。プライマリークラスターでPatroniの永続レプリケーションスロット機能を使用すると、primary_slot_nameと同じ名前、またはprimary_slot_nameが指定されていない場合はそのデフォルト値の名前を持つレプリケーションスロットを維持できます。

リモートサイトにプライマリーへ接続する単一のエンドポイントがない場合は、standby_cluster.hostセクションにソースクラスターの全ホストを列挙できます。standby_cluster.hostにカンマ区切りで複数のホストが含まれる場合、Patroniは次の処理を行います。

  • スタンバイリーダーノードのprimary_conninfoにtarget_session_attrs=read-writeを追加します。
  • pg_rewindを実行する必要があるかどうかを判断するときや、スタンバイクラスターの全ノードでpg_rewindを実行するときに、target_session_attrs=read-writeを使用します。
  • pg_rewindを正常に動作させるには、data page checksums（initdbの--data-checksumsオプション）を有効にしてクラスターを初期化するか、wal_log_hintsをonに設定する、あるいはその両方を行わなければならないことに注意してください。そうでなければ、pg_rewindは正しく動作しません。

別のスタンバイクラスターや、プライマリークラスターのスタンバイメンバーからスタンバイクラスターへレプリケーションすることも可能です。その場合は、standby_cluster.hostセクションに単一のホストを定義する必要があります。ただし、この場合はスタンバイクラスターでpg_rewindの実行に失敗することに注意してください。

警告

メンバー名（各ノードのPatroni構成のnameフィールド）は、プライマリークラスターと、それに接続するすべてのスタンバイクラスターにわたって一意でなければなりません。

Patroniはメンバー名を使用してプライマリー上のsynchronous_standby_namesを設定します。メンバー名は、pg_stat_replication内の各レプリケーション接続のapplication_nameにもなります。スタンバイクラスターのノードとプライマリークラスターのメンバーが同じ名前を持つ場合、PostgreSQLには同一のapplication_name値を持つ接続が二つ見えることになります。この曖昧さにより、PostgreSQLが本来意図したプライマリークラスターのメンバーではなく、スタンバイクラスターの接続を使用して同期レプリケーションの要件を満たす可能性があります。その結果、正しいスタンバイにトランザクションが永続化されていないにもかかわらず、PostgreSQLが同期コミット済みとして早まって応答してしまいます。

これは検出されない障害です。レプリケーションは継続し、エラーもログに記録されませんが、実際には有効な同期スタンバイがない状態でクラスターが動作しているため、プライマリーが障害を起こすとデータを失う可能性があります。

9 - ウォッチドッグのサポート

Patroniクラスターでのウォッチドッグ連携とフェンシングに関する考慮事項。

複数のPostgreSQLサーバーがプライマリーとして動作すると、タイムラインが分岐してトランザクションが失われる可能性があります。この状況はスプリットブレイン問題とも呼ばれます。スプリットブレインを避けるには、DCS内のリーダーキーが期限切れになった後にPostgreSQLがトランザクションのコミットを受け付けないよう、Patroniが保証する必要があります。通常、Patroniは何らかの理由でリーダーロックの更新に失敗すると、PostgreSQLを停止することでこれを実現しようとします。しかし、次のようなさまざまな理由で実行できない場合があります。

  • バグ、メモリー不足、またはシステム管理者による誤った強制終了により、Patroniがクラッシュした。
  • PostgreSQLのシャットダウンに時間がかかりすぎる。
  • システムの高負荷、ハイパーバイザーによるVMの一時停止、その他のインフラストラクチャーの問題により、Patroniを実行できない。

こうした状況でも正しく動作することを保証するため、Patroniはウォッチドッグデバイスをサポートしています。ウォッチドッグデバイスは、指定された時間内にキープアライブのハートビートを受信しないとシステム全体をリセットする、ソフトウェアまたはハードウェアの仕組みです。通常のPatroniのスプリットブレイン防止機構が機能しない場合に、追加のフェイルセーフとなります。

PatroniはPostgreSQLをプライマリーに昇格させる前にウォッチドッグの有効化を試みます。有効化に失敗し、ウォッチドッグモードがrequiredの場合、ノードはリーダーになることを拒否します。リーダー選出への参加を判断するときにも、Patroniはウォッチドッグの構成がリーダーになることを許可するかどうかを確認します。PostgreSQLを降格させた後（たとえば手動フェイルオーバーの後）には、Patroniはウォッチドッグを再び無効化します。Patroniが一時停止状態の間も、ウォッチドッグは無効化されます。

デフォルトでは、PatroniはTTLが期限切れになる5秒前にウォッチドッグがタイムアウトするように設定します。デフォルトのloop_wait=10とttl=30の設定では、システムが強制リセットされるまでにHAループを完了させる時間が少なくとも15秒（ttl - safety_margin - loop_wait）あります。DCSへのアクセスは、デフォルトで10秒後にタイムアウトするように設定されています。そのため、ネットワークの問題などでDCSが利用できない場合、PatroniとPostgreSQLには、すべてのクライアント接続を終了した状態になるまで少なくとも5秒（ttl - safety_margin - loop_wait - retry_timeout）の猶予があります。

安全マージンは、リーダーキーの更新からウォッチドッグへのキープアライブ送信までの間にPatroniが確保する時間です。Patroniはリーダーキーの更新確認後、ただちにキープアライブの送信を試みます。ちょうど特定のタイミングでPatroniプロセスが長時間停止されると、ウォッチドッグを作動させることなく、キープアライブが安全マージンを超えて遅延する可能性があります。その結果、リーダーキーの期限切れ前にウォッチドッグが作動しない時間帯が生じ、保証が成立しなくなります。あらゆる状況でウォッチドッグが確実に作動するようにするには、safety_marginを-1に設定してウォッチドッグのタイムアウトをttl // 2にし、TTLの半分が経過した時点でタイムアウトするようにします。この保証が必要な場合は、ttlを増やすか、loop_waitとretry_timeoutを減らす、あるいはその両方を行うことが推奨されます。

現在、ウォッチドッグはLinuxのウォッチドッグデバイスインターフェースでのみサポートされています。

Linuxでのソフトウェアウォッチドッグの設定

Patroniのデフォルト構成では、Linuxで/dev/watchdogにアクセス可能な場合にその使用を試みます。ほとんどの用途では、Linuxカーネルに組み込まれたソフトウェアウォッチドッグで十分な安全性が得られます。

ソフトウェアウォッチドッグを有効にするには、Patroniを起動する前にrootとして次のコマンドを実行します。

modprobe softdog
# Replace postgres with the user you will be running patroni under
chown postgres /dev/watchdog

テストでは、modprobeコマンドラインにsoft_noboot=1を追加して再起動を無効にすると便利な場合があります。この場合、ウォッチドッグはカーネルのリングバッファーにログを一行記録するだけで、その内容はdmesgで確認できます。

Patroniはウォッチドッグが正常に有効化されると、その情報をログに記録します。

10 - クラスターの一時停止/再開モード

Patroniクラスター管理における一時停止および再開モードの動作。

目的

ある条件下では、Patroniはクラスターの管理を一時的に停止する必要がありますが、その間もクラスター状態をDCSに保持します。このような状況の例として、メジャーバージョンのアップグレードや破損からの復旧など、稀なクラスター操作が挙げられます。これらの操作中は、Patroniが認識しない理由でノードの起動・停止が頻発し、一部のノードが一時的にプライマリーに昇格する場合もあり、その結果、同時に1つのプライマリーしか実行されていないという前提が破られることがあります。したがって、Patroniは実行中のクラスターから「分離」できる必要があり、これによりPacemakerのメンテナンスモードと同等の動作を実現します。

実装

Patroniが一時停止モードで実行されている場合、PostgreSQLの状態を変更しません。ただし、以下のケースを除きます。

  • 各ノードについて、DCSのメンバーキーはクラスターに関する現在の情報をもとに更新されます。これにより、メンバーノードが実行中である場合、Patroniはそのノードで読み取り専用のクエリーを実行します。
  • リーダーロックを持つPostgresのプライマリーでは、Patroniがロックを更新します。リーダーロックを持つノードがプライマリーでなくなる（つまり手動で降格された）場合、Patroniはそのノードを再び昇格するのではなく、ロックを解放します。
  • 手動での予定外の再起動、手動での予定外のフェイルオーバー／スイッチオーバー、および再初期化は許可されています。スケジュールされた操作は許可されません。手動スイッチオーバーは、切り替え先のノードが指定されている場合にのみ許可されます。
  • Patroniが「並列」なプライマリーを検出すると警告を発しますが、リーダーロックを持たないプライマリーを降格させることはありません。
  • クラスターにリーダーロックが存在しない場合、実行中のプライマリーがロックを取得します。プライマリーノードが複数存在する場合、ロックを最初に取得したプライマリーが勝者となります。プライマリーがまったく存在しない場合、Patroniはレプリカの昇格を試みません。このルールには例外があります。以前のプライマリーが手動での昇格により自己降格したためにリーダーロックが存在しない場合、昇格リクエストで指定された候補ノードのみがリーダーロックを取得できます。新しいリーダーロックが付与された場合（すなわち手動でレプリカを昇格した後）、Patroniは、以前のリーダーからストリーミングしていたレプリカが新しいリーダーに切り替わるようにします。
  • Postgresが停止している場合、Patroniはその起動を試みません。Patroniを停止した場合、管理しているPostgresインスタンスの停止を試みません。
  • Patroniは、他のクラスターメンバーを表すスロットでも、永続スロットの構成に記載されたスロットでもないレプリケーションスロットを削除しようとはしません。

ユーザーガイド

patronictl はpause およびresume コマンドをサポートしています。

また、Patroni REST APIに{"pause": true/false/null}を指定してPATCH /configリクエストを送り、DCS内の{namespace}/{cluster}/configキーを更新することもできます。

11 - DCSフェイルセーフモード

DCSフェイルセーフモードの動作、要件、運用上の注意事項。

問題

Patroniは、リーダー選出とネットワーク分断の検出を行うため、分散構成ストア（DCS）に大きく依存しています。つまり、DCS内のリーダーロックを更新できる場合に限り、ノードはPostgresをプライマリーとして実行できます。リーダーロックの更新に失敗すると、Postgresはただちに降格し、読み取り専用として起動します。この「問題」が発生する可能性は、使用するDCSによって異なります。たとえば、Patroni専用のetcdでは発生する可能性はほぼゼロですが、etcdを基盤に持つK8s APIでは、より頻繁に観測される可能性があります。

現在の実装の理由

リーダーロックの更新が失敗する主な理由は、次の二つです。

  1. ネットワークの分断
  2. DCSの停止

一般に、単一のノードからこの二つを区別することはできないため、Patroniは最悪のケースであるネットワーク分断を想定します。ネットワークが分断されると、Patroniクラスターの他のノードがリーダーロックを取得し、Postgresをプライマリーに昇格させる可能性があります。スプリットブレインを避けるため、以前のプライマリーはリーダーロックが期限切れになる前に降格します。

DCSフェイルセーフモード

新しい特別なオプション、failsafe_modeを導入しました。これは、DCSの/configキーに保存されたグローバルな動的構成 を通じてのみ有効にできます。フェイルセーフモードが有効で、バージョン、値、インデックスの不一致以外の理由でDCS内のリーダーロックの更新が失敗した場合、Patroni REST APIを通じてクラスターの既知の全メンバーにアクセスできれば、Postgresはプライマリーとして動作を継続できます。

内部実装の詳細

  • /failsafeという名前の新しい永続キーをDCSに導入しました。
  • /failsafeキーには、ある時点での、そのPatroniクラスターの既知の全メンバーが含まれます。
  • 現在のリーダーが/failsafeキーを維持します。
  • メンバーは、/failsafeキーに含まれる場合に限り、リーダー選出に参加して新しいリーダーになれます。
  • クラスターが単一ノードで構成されている場合、/failsafeキーには単一のメンバーが含まれます。
  • DCSの「停止」が発生すると、既存のプライマリーはPOST /failsafe REST APIを通じて/failsafeキーに含まれる全メンバーに接続し、すべてのレプリカが承認すればプライマリーとして動作を継続できます。
  • メンバーのいずれかが応答しない場合、プライマリーは降格します。
  • レプリカは、受信したPOST /failsafe REST APIリクエストを、プライマリーがまだ稼働していることを示す情報として使用します。この情報はttl秒間キャッシュされます。

よくある質問

  • 現在のプライマリーは、なぜ他の全メンバーに到達できなければならないのですか。ここでクォーラムに依存することはできませんか。

    よい質問です。問題は、DCSとPatroniではクォーラムの見え方が異なる可能性があることです。DCSノードはアベイラビリティーゾーン間に均等に配置しなければなりませんが、Patroniにはそのような規則はありません。さらに重要なのは、そのような規則を導入して強制する仕組みがないことです。Patroniノードの過半数がプライマリーを含めて、分断されたネットワークの敗者側に入り、少数のノードが勝者側に入った場合、プライマリーを降格させなければなりません。他の全メンバーを確認することでのみ、この状況を検出できます。

  • DCSが停止している間にノードやPodが終了した場合はどうなりますか。

    DCSにアクセスできない場合、ハートビートループの各サイクル（loop_wait秒ごと）で、「クラスターの他の全メンバーにアクセスできるか」という確認を実行します。Podやノードが終了すると、この確認が失敗し、Postgresは読み取り専用に降格します。DCSが復旧するまで復帰しません。

  • DCSが停止している間にPatroniクラスターの全メンバーが失われた場合はどうなりますか。

    Patroniは、クラスターにリーダーがいない場合でもバックアップから新しいレプリカを作成するように構成できます。ただし、新しいメンバーが/failsafeキーに含まれていなければ、リーダーロックを取得して昇格することはできません。

  • プライマリーがDCSへのアクセスを失い、レプリカはアクセスを維持している場合はどうなりますか。

    プライマリーはフェイルセーフのコードを実行し、既知のすべてのレプリカに連絡します。これらのレプリカは、この情報をプライマリーが稼働していることを示す情報として使用し、DCS内のリーダーロックが期限切れになってもリーダー選出を開始しません。

  • フェイルセーフモードを有効にするにはどうすればよいですか。

    failsafe_modeを有効にする前に、全メンバーのPatroniのバージョンが最新であることを確認してください。その後、PATCH /config REST API 、またはpatronictl edit-config -s failsafe_mode=true を使用できます。

12 - KubernetesでのPatroniの使用

Kubernetesのオブジェクト、ラベル、サービスディスカバリーを使用したPatroniの運用。

PatroniはKubernetesオブジェクトを使用してクラスターの状態を保存し、リーダーキーを管理できます。そのため、整合性ストアを用意せずにKubernetes環境でPostgresを運用できます。つまり、追加のetcdデプロイメントを実行する必要がありません。Patroniがリーダーキーと構成キーの保存に使用できるKubernetesオブジェクトには二種類あり、kubernetes.use_endpointsまたは環境変数PATRONI_KUBERNETES_USE_ENDPOINTSで構成します。

Endpointsの使用

これは推奨モードですが、互換性のためデフォルトでは無効です。有効にすると、Patroniは作成した各Endpointsのmetadata: annotationsフィールドにクラスター構成とリーダーキーを保存します。リーダー情報を含むアノテーションと、実行中のリーダーPodを指す実際のアドレスを同時に一度で更新するため、ConfigMapsを使用する場合よりも安全にリーダーを変更できます。

ConfigMapsの使用

このモードでは、PatroniはEndpointsの代わりにConfigMapsを作成し、そのメタデータ内にキーを保存します。リーダーの変更には、リーダーのConfigMapと対応するEndpointに対する、少なくとも二回の更新が必要です。

トラフィックをPostgresのリーダーに向けるには、KubernetesのPostgresサービスが（Patroniの構成で設定した）role_labelによるラベルセレクターを使用するよう構成する必要があります。

OpenShift上で実行する場合など、状況によってはConfigMapsを使用する以外に選択肢がないことに注意してください。

構成

PatroniのKubernetes用の設定 と環境変数 は、ドキュメントの一般的な章で説明しています。

ロールラベルのカスタマイズ

デフォルトでは、Patroniはノードのロールに応じて、実行中のPodにrole=primaryなどの対応するラベルを設定します。ラベルのキーと値は、kubernetes.role_label、kubernetes.leader_label_value、kubernetes.follower_label_value、kubernetes.standby_leader_label_valueでカスタマイズできます。

デフォルトのロールラベルから独自のラベルに移行する場合は、次の手順に従うことでダウンタイムを短縮できます。

  1. kubernetes.tmp_role_labelを使用して、元のロール値を持つ一時的なラベル（tmp_roleなど）をPodに追加します。Podを再起動すると、Patroniによって次のラベルが設定されます。
labels:
  cluster-name: foo
  role: primary
  tmp_role: primary
  1. すべてのPodを更新した後、サービスのセレクターを変更して一時的なラベルを選択するようにします。
selector:
  cluster-name: foo
  tmp_role: primary
  1. 独自のロールラベルを追加します（たとえば、kubernetes.leader_label_value=leaderを設定します）。Podを再起動すると、Patroniによって次の新しいラベルが設定されます。
labels:
  cluster-name: foo
  role: leader
  tmp_role: primary
  1. すべてのPodを再度更新した後、サービスのセレクターを変更して新しいロール値を使用するようにします。
selector:
  cluster-name: foo
  role: leader
  1. 最後に、構成から一時的なラベルを削除し、すべてのPodを更新します。
labels:
  cluster-name: foo
  role: leader

例

  • Patroniリポジトリのkubernetes フォルダーには、PatroniのKubernetesセットアップをテストするためのDockerイメージとKubernetesマニフェストの例が含まれています。現在の状態では、権限の問題によりPersistentVolumesを使用できないことに注意してください。
  • Persistent Volumesを使用できる、すべての機能を備えたDockerイメージは、Spiloプロジェクト にあります。
  • Kubernetesで実行するPatroniを構成したSpiloイメージをデプロイするためのHelmチャート もあります。
  • PatroniとSpiloを使用してデータベースクラスターを大規模に運用する場合は、postgres-operator プロジェクトを参照してください。Spiloクラスターを管理するためのOperatorパターンを実装しています。

13 - Citusサポート

Citusのコーディネーターとワーカーグループに対するPatroniの統合の詳細。

Patroniを使用すると、マルチノードCitus クラスターを極めて簡単にデプロイできます。

要点

必要なのは、次の簡単なルールに従うことだけです。

  1. PostgreSQLのデータベース拡張Citus は、すべてのノードで利用可能になっている必要があります。絶対的な最小サポートバージョンはCitus 10.0ですが、ワーカーの透過的なスイッチオーバーと再起動の利点をすべて活用するには、Citus 11.2以降の使用を推奨します。
  2. クラスター名（scope）は、すべてのCitusノードで同じにする必要があります。
  3. スーパーユーザーの認証情報は、コーディネーターとすべてのワーカーノードで同じである必要があります。また、pg_hba.confでは、全ノード間のスーパーユーザーアクセスを許可しておくべきです。
  4. ワーカーノードからコーディネーターへのREST API アクセスは許可しておくべきです。たとえば認証情報は同じにし、クライアント証明書を設定している場合は、コーディネーターがワーカーノードの証明書を受け入れなければなりません。
  5. patroni.yamlに次のセクションを追加します。
citus:
  group: X  # 0 for coordinator and 1, 2, 3, etc for workers
  database: citus  # must be the same on all nodes

後はPatroniを起動するだけで、残りの処理を実行します。

  1. bootstrap.dcs.synchronous_modeが他の値に明示的に設定されていない場合、Patroniはこれをquorum に設定します。
  2. citus 拡張をshared_preload_librariesに自動的に追加します。
  3. グローバルな動的設定 でmax_prepared_transactionsが明示的に設定されていない場合、Patroniは自動的にこれを2*max_connectionsに設定します。
  4. citus.local_hostnameのGUC値を、localhostからPatroniがローカルのPostgreSQLインスタンスへの接続に使用する値へ変更します。PostgreSQLがlocalhostでリッスンしていない場合があるため、別の値が必要になることがあります。
  5. citus.databaseで指定したデータベースを自動的に作成し、続いてCREATE EXTENSION citusを実行します。
  6. ノード間の通信を可能にするため、現在のスーパーユーザーの認証情報 をpg_dist_authinfoテーブルに追加します。後からスーパーユーザーのusername/password/sslcert/sslkeyを変更する場合は、この情報の更新も忘れないでください。
  7. コーディネーターのプライマリーノードは、ワーカーのプライマリーノードを自動検出し、citus_add_node()関数でpg_dist_nodeテーブルに追加します。
  8. コーディネーターまたはワーカーのクラスターでフェイルオーバーやスイッチオーバーが発生した場合も、Patroniがpg_dist_nodeを維持します。

patronictl

コーディネーターとワーカーのクラスターは、物理的には異なるPostgreSQL/Patroniクラスターです。PostgreSQLのデータベース拡張Citus で論理的にまとめているだけなので、多くの場合は単一の実体として管理できません。

このため、patroni.yamlにcitus セクションがある場合、patronictl の動作には通常と比べて2つの主な違いがあります。

  1. listとtopologyは、デフォルトでCitus構成全体のメンバー（コーディネーターとワーカー）を出力します。新しいGroup列に、所属するCitusグループが表示されます。
  2. すべてのpatronictl コマンドに、新しい--groupオプションが追加されます。一部のコマンドでは、グループのデフォルト値をpatroni.yamlから取得する場合があります。たとえばpatronictl pause は、デフォルトでcitus セクションのgroupに対してメンテナンスモードを有効にします。一方、patronictl switchover やpatronictl remove などでは、グループを明示的に指定する必要があります。

Citusクラスターでのpatronictl list の出力例：

postgres@coord1:~$ patronictl list demo
+ Citus cluster: demo ----------+----------------+---------+----+-------------+-----+------------+-----+
| Group | Member  | Host        | Role           | State   | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------+---------+-------------+----------------+---------+----+-------------+-----+------------+-----+
|     0 | coord1  | 172.27.0.10 | Replica        | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
|     0 | coord2  | 172.27.0.6  | Quorum Standby | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
|     0 | coord3  | 172.27.0.4  | Leader         | running |  1 |             |     |            |     |
|     1 | work1-1 | 172.27.0.8  | Quorum Standby | running |  1 |   0/31D3198 |   0 |  0/31D3198 |   0 |
|     1 | work1-2 | 172.27.0.2  | Leader         | running |  1 |             |     |            |     |
|     2 | work2-1 | 172.27.0.5  | Quorum Standby | running |  1 |   0/31CDFC0 |   0 |  0/31CDFC0 |   0 |
|     2 | work2-2 | 172.27.0.7  | Leader         | running |  1 |             |     |            |     |
+-------+---------+-------------+----------------+---------+----+-------------+-----+------------+-----+

--groupオプションを追加すると、出力は次のように変わります。

postgres@coord1:~$ patronictl list demo --group 0
+ Citus cluster: demo (group: 0, 7179854923829112860) -+-------------+-----+------------+-----+
| Member | Host        | Role           | State   | TL | Receive LSN | Lag | Replay LSN | Lag |
+--------+-------------+----------------+---------+----+-------------+-----+------------+-----+
| coord1 | 172.27.0.10 | Replica        | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
| coord2 | 172.27.0.6  | Quorum Standby | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
| coord3 | 172.27.0.4  | Leader         | running |  1 |             |     |            |     |
+--------+-------------+----------------+---------+----+-------------+-----+------------+-----+

postgres@coord1:~$ patronictl list demo --group 1
+ Citus cluster: demo (group: 1, 7179854923881963547) -+-------------+-----+------------+-----+
| Member  | Host       | Role           | State   | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+------------+----------------+---------+----+-------------+-----+------------+-----+
| work1-1 | 172.27.0.8 | Quorum Standby | running |  1 |   0/31D3198 |   0 |  0/31D3198 |   0 |
| work1-2 | 172.27.0.2 | Leader         | running |  1 |             |     |            |     |
+---------+------------+----------------+---------+----+-------------+-----+------------+-----+

Citusワーカーのスイッチオーバー

Citusワーカーノードのスイッチオーバーを調整して実行する場合、Citusでは、アプリケーションからほぼ透過的に切り替えることができます。アプリケーションはコーディネーターに接続し、そこからワーカーノードへ接続するため、ワーカーノード上のシャードに対するSQLトラフィックを、Citusでコーディネーター上に一時停止できます。そのトラフィックをコーディネーターに保持している間にスイッチオーバーを行い、新しいプライマリーのワーカーノードが読み書きのクエリーを受け付ける準備を終え次第、トラフィックを再開します。

ワーカークラスターでのpatronictl switchover の例：

postgres@coord1:~$ patronictl switchover demo
+ Citus cluster: demo ----------+----------------+---------+----+-------------+-----+------------+-----+
| Group | Member  | Host        | Role           | State   | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------+---------+-------------+----------------+---------+----+-------------+-----+------------+-----+
|     0 | coord1  | 172.27.0.10 | Replica        | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
|     0 | coord2  | 172.27.0.6  | Quorum Standby | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
|     0 | coord3  | 172.27.0.4  | Leader         | running |  1 |             |     |            |     |
|     1 | work1-1 | 172.27.0.8  | Leader         | running |  1 |             |     |            |     |
|     1 | work1-2 | 172.27.0.2  | Quorum Standby | running |  1 |   0/31D3198 |   0 |  0/31D3198 |   0 |
|     2 | work2-1 | 172.27.0.5  | Quorum Standby | running |  1 |   0/31CDFC0 |   0 |  0/31CDFC0 |   0 |
|     2 | work2-2 | 172.27.0.7  | Leader         | running |  1 |             |     |            |     |
+-------+---------+-------------+----------------+---------+----+-------------+-----+------------+-----+
Citus group: 2
Primary [work2-2]:
Candidate ['work2-1'] []:
When should the switchover take place (e.g. 2024-08-26T08:02 )  [now]:
Current cluster topology
+ Citus cluster: demo (group: 2, 7179854924063375386) -+-------------+-----+------------+-----+
| Member  | Host       | Role           | State   | TL | Receive LSN | Lag | Replay LSN | Lag |
+---------+------------+----------------+---------+----+-------------+-----+------------+-----+
| work2-1 | 172.27.0.5 | Quorum Standby | running |  1 |   0/31CDFC0 |   0 |  0/31CDFC0 |   0 |
| work2-2 | 172.27.0.7 | Leader         | running |  1 |             |     |            |     |
+---------+------------+----------------+---------+----+-------------+-----+------------+-----+
Are you sure you want to switchover cluster demo, demoting current primary work2-2? [y/N]: y
2024-08-26 07:02:40.33003 Successfully switched over to "work2-1"
+ Citus cluster: demo (group: 2, 7179854924063375386) --------+---------+------------+---------+
| Member  | Host       | Role    | State   | TL | Receive LSN |     Lag | Replay LSN |     Lag |
+---------+------------+---------+---------+----+-------------+---------+------------+---------+
| work2-1 | 172.27.0.5 | Leader  | running |  1 |             |         |            |         |
| work2-2 | 172.27.0.7 | Replica | stopped |    |     unknown | unknown |    unknown | unknown |
+---------+------------+---------+---------+----+-------------+---------+------------+---------+

postgres@coord1:~$ patronictl list demo
+ Citus cluster: demo ----------+----------------+---------+----+-------------+-----+------------+-----+
| Group | Member  | Host        | Role           | State   | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------+---------+-------------+----------------+---------+----+-------------+-----+------------+-----+
|     0 | coord1  | 172.27.0.10 | Replica        | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
|     0 | coord2  | 172.27.0.6  | Quorum Standby | running |  1 |   0/41C0368 |   0 |  0/41C0368 |   0 |
|     0 | coord3  | 172.27.0.4  | Leader         | running |  1 |             |     |            |     |
|     1 | work1-1 | 172.27.0.8  | Leader         | running |  1 |             |     |            |     |
|     1 | work1-2 | 172.27.0.2  | Quorum Standby | running |  1 |   0/31D3198 |   0 |  0/31D3198 |   0 |
|     2 | work2-1 | 172.27.0.5  | Leader         | running |  2 |             |     |            |     |
|     2 | work2-2 | 172.27.0.7  | Quorum Standby | running |  2 |   0/31CDFC0 |   0 |  0/31CDFC0 |   0 |
+-------+---------+-------------+----------------+---------+----+-------------+-----+------------+-----+

コーディネーター側では、次のようになります。

# The worker primary notifies the coordinator that it is going to execute "pg_ctl stop".
2024-08-26 07:02:38,636 DEBUG: query(BEGIN, ())
2024-08-26 07:02:38,636 DEBUG: query(SELECT pg_catalog.citus_update_node(%s, %s, %s, true, %s), (3, '172.19.0.7-demoted', 5432, 10000))
# From this moment all application traffic on the coordinator to the worker group 2 is paused.

# The old worker primary is assigned as a secondary.
2024-08-26 07:02:40,084 DEBUG: query(SELECT pg_catalog.citus_update_node(%s, %s, %s, true, %s), (7, '172.19.0.7', 5432, 10000))

# The future worker primary notifies the coordinator that it acquired the leader lock in DCS and about to run "pg_ctl promote".
2024-08-26 07:02:40,085 DEBUG: query(SELECT pg_catalog.citus_update_node(%s, %s, %s, true, %s), (3, '172.19.0.5', 5432, 10000))

# The new worker primary just finished promote and notifies coordinator that it is ready to accept read-write traffic.
2024-08-26 07:02:41,485 DEBUG: query(COMMIT, ())
# From this moment the application traffic on the coordinator to the worker group 2 is unblocked.

セカンダリーノード

Patroni v4.0.0以降では、noloadbalanceタグ が付いていないCitusセカンダリーノードもpg_dist_nodeに登録されます。ただし、アプリケーションが読み取り専用クエリーにセカンダリーノードを使用するには、citus.use_secondary_nodes のGUCを変更する必要があります。

DCSの内部構造

Citusクラスター（コーディネーターとワーカー）は、論理的にまとめたPatroniクラスター群としてDCSに保存されます。

/service/batman/              # scope=batman
/service/batman/0/            # citus.group=0, coordinator
/service/batman/0/initialize
/service/batman/0/leader
/service/batman/0/members/
/service/batman/0/members/m1
/service/batman/0/members/m2
/service/batman/1/            # citus.group=1, worker
/service/batman/1/initialize
/service/batman/1/leader
/service/batman/1/members/
/service/batman/1/members/m3
/service/batman/1/members/m4
...

この方式を採用したのは、ほとんどのDCSで、1回の再帰的な読み取り要求によりCitusクラスター全体を取得できるためです。ツリー全体を読み取るのは、ワーカーノードを検出する必要があるCitusコーディネーターノードだけです。ワーカーノードは、自身のグループのサブツリーだけを読み取り、場合によってはコーディネーターグループのサブツリーも読み取ります。

Kubernetes上のCitus

Kubernetesは階層構造をサポートしないため、Patroniが作成するすべてのK8sオブジェクトにcitusグループを含める必要がありました。

batman-0-leader  # the leader config map for the coordinator
batman-0-config  # the config map holding initialize, config, and history "keys"
...
batman-1-leader  # the leader config map for worker group 1
batman-1-config
...

つまり、命名パターンは${scope}-${citus.group}-${type}です。

Patroniはラベルセレクター を使用してすべてのKubernetesオブジェクトを検出します。そのため、PatroniとCitusを実行するすべてのPodとEndpoints/ConfigMapsには共通のラベルセレクターに一致するラベルを付け、Patroniがそれらを使用するようにKubernetesの設定 または環境変数 で指定する必要があります。

Podの環境変数を使用したPatroni設定の例を2つ示します。

  1. コーディネータークラスターの場合
apiVersion: v1
kind: Pod
metadata:
  labels:
    application: patroni
    citus-group: "0"
    citus-type: coordinator
    cluster-name: citusdemo
  name: citusdemo-0-0
  namespace: default
spec:
  containers:
  - env:
    - name: PATRONI_SCOPE
      value: citusdemo
    - name: PATRONI_NAME
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.name
    - name: PATRONI_KUBERNETES_POD_IP
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: status.podIP
    - name: PATRONI_KUBERNETES_NAMESPACE
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.namespace
    - name: PATRONI_KUBERNETES_LABELS
      value: '{application: patroni}'
    - name: PATRONI_CITUS_DATABASE
      value: citus
    - name: PATRONI_CITUS_GROUP
      value: "0"
  1. グループ2のワーカークラスターの場合
apiVersion: v1
kind: Pod
metadata:
  labels:
    application: patroni
    citus-group: "2"
    citus-type: worker
    cluster-name: citusdemo
  name: citusdemo-2-0
  namespace: default
spec:
  containers:
  - env:
    - name: PATRONI_SCOPE
      value: citusdemo
    - name: PATRONI_NAME
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.name
    - name: PATRONI_KUBERNETES_POD_IP
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: status.podIP
    - name: PATRONI_KUBERNETES_NAMESPACE
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.namespace
    - name: PATRONI_KUBERNETES_LABELS
      value: '{application: patroni}'
    - name: PATRONI_CITUS_DATABASE
      value: citus
    - name: PATRONI_CITUS_GROUP
      value: "2"

どちらの例でも、citus-groupラベルが設定されています。このラベルにより、PatroniはオブジェクトがどのCitusグループに属するかを識別します。また、citus-groupラベルと同じ値を持つPATRONI_CITUS_GROUP環境変数もあります。Patroniが新しいKubernetesのConfigMapsやEndpointsを作成すると、自動的にcitus-group: ${env.PATRONI_CITUS_GROUP}ラベルを付けます。

apiVersion: v1
kind: ConfigMap
metadata:
  name: citusdemo-0-leader  # Is generated as ${env.PATRONI_SCOPE}-${env.PATRONI_CITUS_GROUP}-leader
  labels:
    application: patroni    # Is set from the ${env.PATRONI_KUBERNETES_LABELS}
    cluster-name: citusdemo # Is automatically set from the ${env.PATRONI_SCOPE}
    citus-group: '0'        # Is automatically set from the ${env.PATRONI_CITUS_GROUP}

Citusに対応したPatroniをKubernetesにデプロイする完全な例は、Patroniリポジトリのkubernetes フォルダーにあります。

重要なファイルは次の2つです。

  1. Dockerfile.citus
  2. citus_k8s.yaml

CitusのアップグレードとPostgreSQLのメジャーアップグレード

まず、ドキュメント でCitusのバージョンアップグレードについて確認してください。手順に小さな違いが1つあります。アップグレード時にPostgreSQLを再起動するには、systemctl restartの代わりにpatronictl restart を使用する必要があります。

Citusを使用したPostgreSQLのメジャーアップグレードは、もう少し複雑です。Citusのメジャーアップグレードのドキュメントと、PatroniのPostgreSQLのメジャーバージョンアップグレード のドキュメントにある手法を組み合わせる必要があります。Citusクラスターは多数のPatroniクラスター（コーディネーターとワーカー）で構成されており、それぞれを個別にアップグレードする必要がある点に注意してください。

14 - 単独インスタンスをPatroniクラスターに移行する

既存のPostgreSQLデータをPatroniクラスターに移行する手順。

このセクションでは、単独のPostgreSQLインスタンスをPatroniクラスターに移行する手順を説明します。

既存のPostgreSQLインスタンスを使用せずにPatroniクラスターを構築する場合は、実行と設定 を参照してください。

手順

既存のPostgresクラスターをPatroni管理のクラスターに移行する手順の概要を以下に示します。既存クラスターのすべてのノードが稼働中であり、移行中にPostgresの設定を変更する予定がないことを前提とします。手順は次のとおりです。

  1. Patroni設定のauthentication セクションの説明に従い、Postgresユーザーを作成します。以下のコードブロックにユーザー作成用のSQLコマンド例を示します。ユーザー名とパスワードを環境に合わせて置き換えてください。必要なユーザーがすでに存在する場合は、この手順を省略できます。

    -- Patroni superuser
-- Replace PATRONI_SUPERUSER_USERNAME and PATRONI_SUPERUSER_PASSWORD accordingly
CREATE USER PATRONI_SUPERUSER_USERNAME WITH SUPERUSER ENCRYPTED PASSWORD 'PATRONI_SUPERUSER_PASSWORD';

-- Patroni replication user
-- Replace PATRONI_REPLICATION_USERNAME and PATRONI_REPLICATION_PASSWORD accordingly
CREATE USER PATRONI_REPLICATION_USERNAME WITH REPLICATION ENCRYPTED PASSWORD 'PATRONI_REPLICATION_PASSWORD';

-- Patroni rewind user, if you intend to enable use_pg_rewind in your Patroni configuration
-- Replace PATRONI_REWIND_USERNAME and PATRONI_REWIND_PASSWORD accordingly
CREATE USER PATRONI_REWIND_USERNAME WITH ENCRYPTED PASSWORD 'PATRONI_REWIND_PASSWORD';
GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO PATRONI_REWIND_USERNAME;
GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO PATRONI_REWIND_USERNAME;
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO PATRONI_REWIND_USERNAME;
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO PATRONI_REWIND_USERNAME;

  2. すべてのPostgresノードで以下の手順を実行します。1つのノードですべての手順を終えてから次のノードへ進んでください。最初にプライマリーノードを処理し、その後各スタンバイノードを処理します。

    1. systemd経由でPostgresを実行している場合は、Postgresのsystemdユニットを無効にします。以後はPatroniがPostgresデーモンの起動と停止を管理するためです。
    2. PatroniのYAML設定ファイルを作成します。Patroni設定の生成・検証ツール を使用できます。
      • 注意（プライマリーノード固有）： クラスターメンバー間のレプリケーションでレプリケーションスロットを使用している場合は、use_slotsを有効にし、slots設定項目で既存のスロットを永続スロットとして設定することを推奨します。use_slotsを有効にすると、Patroniはメンバー間のレプリケーション用スロットを自動作成し、認識していないスロットを削除する点に注意してください。ここで永続スロットを使用する目的は、Patroniへの移行中も既存のスロットを保持することです。詳細は動的設定 を参照してください。
    3. patroniのsystemdサービスユニットでPatroniを起動します。Postgresがすでに稼働していることを自動検出し、インスタンスの監視を開始します。

  3. Postgresの「起動処理」をPatroniに引き継ぎます。そのために、patronictl restart cluster-name member-name コマンドでクラスターメンバーを再起動する必要があります。停止時間を最小限にするには、この手順を次のように分けるとよいでしょう。

    1. スタンバイノードを直ちに再起動します。
    2. プライマリーノードの再起動をメンテナンス時間帯に予約します。

  4. 手順2.2.で永続スロットを設定した場合、Patroniが作成したスロットのrestart_lsnが対応するメンバーの元のスロットのrestart_lsnに追いついたら、patronictl edit-config cluster-name コマンドでそれらをslots設定から削除してください。slots設定から削除することで、元のスロットが不要になった際にPatroniがクラスターから削除できるようになります。以下は2つのスロットのrestart_lsnを確認し、比較するクエリーの例です。

    -- Assume original_slot_for_member_x is the name of the slot in your original
-- cluster for replicating changes to member X, and slot_for_member_x is the
-- slot created by Patroni for that purpose. You need restart_lsn of
-- slot_for_member_x to be >= restart_lsn of original_slot_for_member_x
SELECT slot_name,
       restart_lsn
FROM pg_replication_slots
WHERE slot_name IN (
    'original_slot_for_member_x',
    'slot_for_member_x'
)

PostgreSQLのメジャーバージョンアップグレード

pg_upgradeを使用してメジャーアップグレードを実行する手順は次のとおりです。

  1. Patroniを停止します。
  2. プライマリーノードでPostgreSQLのバイナリを更新し、pg_upgrade を実行します。
  3. patroni.ymlを更新します。
  4. DCSからinitializeキーを削除するか、クラスターの状態全体をDCSから削除します。後者はpatronictl remove cluster-name を実行することで実施できます。新しいPostgreSQLクラスターはinitdbで初期化され、新しいPostgreSQLシステム識別子を持つため、この処理が必要です。
  5. 前の手順でクラスターの状態を削除した場合は、古いデータディレクトリのpatroni.dynamic.jsonを新しいディレクトリにコピーするとよいでしょう。以前に設定したPostgreSQLパラメーターの一部を保持できます。
  6. プライマリーノードでPatroniを起動します。
  7. スタンバイノードでPostgreSQLのバイナリとpatroni.ymlを更新し、data_dirを消去します。
  8. スタンバイノードでPatroniを起動し、レプリケーションの完了を待ちます。

PostgreSQLは、スタンバイノードでのpg_upgradeの実行をサポートしていません。処理内容を十分理解している場合は、スタンバイノードのdata_dirを消去する代わりに、https://www.postgresql.org/docs/current/pgupgrade.html で説明されているrsyncの手順を試すこともできます。ただし、最も安全な方法はPatroniにデータをレプリケーションさせることです。

よくある質問

  • Patroniの起動時に、PostgreSQLのポートにバインドできないというエラーが出ます。

    postgresql.confのlisten_addressesとport、およびpatroni.ymlのpostgresql.listenを確認する必要があります。pg_hba.confでこのアクセスを許可することも忘れないでください。

  • Patroniにノードの再起動を要求すると、PostgreSQLがcould not open configuration file "/etc/postgresql/10/main/pg_hba.conf": No such file or directoryというエラーを表示します。

    PostgreSQL設定の管理方法に応じて、いくつかの原因が考えられます。postgresql.config_dirを指定している場合、Patroniがbootstrap セクションの設定からpg_hba.confを生成するのは、新しいクラスターをブートストラップするときだけです。この状況ではPGDATAが空でなかったため、ブートストラップは行われていません。このファイルを事前に用意する必要があります。

15 - 他のツールとの統合

Patroniを外部のバックアップおよびオーケストレーションツールと統合する。

Patroniは、スタック内の他のツールと統合できます。このセクションでは、Patroniが他のツールと統合する方法についてのアイデアを提供する例を示します。ただし、すべての例を網羅しているわけではありません。

Barman

Patroniはpatroni_barmanというアプリケーションを提供しており、pg-backup-apiと通信するためのロジックを備えているため、リモートでBarman操作を実行できます。

このアプリケーションには現在、recoverとconfig-switchの2つのサブコマンドがあります。

patroni_barman recover

recoverサブコマンドは、カスタムブートストラップまたはカスタムレプリカ作成方法として使用できます。詳細については、レプリカの作成とブートストラップ を参照してください。

patroni_barman config-switch

config-switchサブコマンドは、Patroniにおけるon_role_changeコールバックとして使用されるように設計されています。たとえば、現在のプライマリーからBarmanホストへのWALのストリーミングを実行しているとします。クラスターでのフェイルオーバーが発生した場合、新しいプライマリーからWALのストリーミングを開始したいとします。この目的を達成するには、patroni_barman config-switchをon_role_changeコールバックとして使用できます。

注記

このサブコマンドは、barman config-switchコマンドに依存しており、このコマンドは事前に定義されたモデルを適用することで、Barmanサーバーの設定を上書きする役割を担います。このコマンドはBarman 3.10以降で利用可能です。詳細についてはBarmanのドキュメントを参照してください。

この例は、このPatroniノードがプライマリーに昇格した場合に設定モデルを適用するよう、Patroniを構成する方法を示しています。

postgresql:
    callbacks:
        on_role_change: >
            patroni_barman
                --api-url YOUR_API_URL
                config-switch
                --barman-server YOUR_BARMAN_SERVER_NAME
                --barman-model YOUR_BARMAN_MODEL_NAME
                --switch-when promoted
注記

patroni_barman config-switchでは、Barmanとpg-backup-apiをBarmanホストに設定しておく必要があります。これにより、バックアップAPIを通じてリモートのbarman config-switchを実行できるようになります。また、適用するBarmanモデルを事前に設定しておく必要があります。上記の例では利用可能なパラメータの一部を使用しています。詳細な情報はpatroni_barman config-switch --helpを実行するか、Barmanのドキュメントを参照してください。

16 - セキュリティに関する考慮事項

DCS、REST API、および資格情報の取り扱いに関するセキュリティ上の考慮事項。

Patroniクラスターには、不正アクセスから保護すべき2つのインターフェースがあります。1つは分散型構成ストレージ（DCS）、もう1つはPatroni REST APIです。

DCSの保護

Patroniとpatronictl は、DCSに対してデータの格納および取得を行います。

DCSに機密情報が含まれていない場合でも、Patroni/PostgreSQLの構成の一部を変更できるため、最初に保護すべきはDCS自体です。

保護の詳細は使用するDCSの種類によって異なります。サポートされているDCSの種類における認証および暗号化パラメータ（トークン／基本認証／クライアント証明書）は、設定 で説明されています。

一般的な推奨は、すべてのDCS通信でTLSを有効にすることです。

REST APIの保護

REST APIの保護はより複雑な作業です。

PatroniのREST APIは、リーダー選出の実行中にPatroni自身が使用し、patronictl がフェイルオーバー／スイッチオーバー／再初期化／再起動／リロードを実行するために使用し、HAProxyまたはその他のロードバランサーがHTTPヘルスチェックを実行するために使用され、もちろんモニタリングにも利用できます。

セキュリティの観点から、REST APIには安全な（GETリクエスト、情報の取得のみ）と安全でない（PUT、POST、PATCHおよびDELETEリクエスト、ノードの状態の変更）エンドポイントが含まれます。

安全でないエンドポイントは、restapi.authentication.usernameおよびrestapi.authentication.passwordパラメータを設定することでHTTP basic-authで保護できます。安全なエンドポイントをTLSを有効化せずに保護する方法はありません。

REST API用のTLSを有効にし、PKIを構築した場合、すべてのエンドポイントでAPIサーバーとAPIクライアントの相互認証が可能になります。

restapiセクションのパラメータにより、サーバーへのTLSクライアント認証が可能になります。verify_clientパラメータの値に応じて、APIサーバーがクライアント証明書の検証成功を要求する対象は、安全なAPI呼び出しと安全でないAPI呼び出しの両方（verify_client: required）、安全でないAPI呼び出しのみ（verify_client: optional）、あるいはどのAPI呼び出しでもない（verify_client: none）のいずれかです。

ctlセクションのパラメータにより、クライアント（Patroniと同じ構成を使用するpatronictl ）がTLSサーバーを認証できます。insecure: trueを設定することで、クライアントによるサーバー証明書の検証を無効化できます。TLSクライアントパラメータの詳細については、設定 を参照してください。

PostgreSQLデータベース本体に対する不正アクセスからの保護は、本ドキュメントの範囲外であり、https://www.postgresql.org/docs/current/client-authentication.html で説明されています。

17 - 複数のデータセンターにまたがるHA

Patroniのレプリケーションを使用した、複数のデータセンターにまたがる高可用性の構成パターン。

複数のデータセンターにデプロイしたPostgreSQLクラスターの高可用性は、レプリケーションに基づきます。レプリケーションには同期と非同期があります（レプリケーションモード を参照）。

どちらの場合も、次の概念を明確に理解することが重要です。

  • Postgresがプライマリーまたはスタンバイリーダーとして動作できるのは、リーダーキーを所有し、それを更新できる場合だけです。
  • etcd、ZooKeeper、Consulのノードは、3または5という奇数台で実行することを推奨します。

同期レプリケーション

ゾーンの停止に自動的に耐えられる複数DCのクラスターにするには、少なくとも3つのゾーンが必要です。

アーキテクチャーの図は次のとおりです。

構成図

etcd、ZooKeeper、Consulのいずれかのクラスターを、複数のDCにまたがって、各ゾーンに一つずつ、少なくとも3ノードでデプロイしなければなりません。

Postgresについては、異なるDCに少なくとも2ノードをデプロイしなければなりません。そのうえで、グローバルな動的構成 にsynchronous_mode: trueを設定する必要があります。

これにより同期レプリケーションが有効になり、プライマリーノードはいずれかのノードを同期ノードとして選択します。

非同期レプリケーション

データセンターが二つだけの場合は、独立したetcdクラスターを二つ用意し、二つ目のデータセンターでPatroniのスタンバイクラスター を実行する方が適切です。最初のサイトが停止した場合は、standby_cluster を手動で昇格させられます。

アーキテクチャーの図は次のとおりです。

構成図

DC2はDC1の状態を判断できないため、自動昇格はできません。

この状況ではpg_ctl promoteを使用すべきではありません。動的構成 からstandby_cluster セクションを削除して、正常なクラスターを「手動で昇格」させる必要があります。

警告

ソースクラスターがまだ稼働している状態でスタンバイクラスターを昇格させると、スプリットブレインが発生します。

「初期」の状態に戻したい場合、解決する方法は次の二つだけです。

  • standby_clusterセクションを再び追加すると、pg_rewindが実行されます。ただし、pg_rewindを正しく動作させるには、data page checksums（initdbの--data-checksumsオプション）を有効にしてクラスターを初期化するか、wal_log_hintsをonに設定する、あるいはその両方を行わなければなりません。それでも、他の要因でpg_rewindが失敗する可能性は残ります。
  • スタンバイクラスターを最初から再構築します。

スタンバイクラスターを昇格させる前に、ソースクラスターが停止していることを手動で確認しなければなりません（STONITH）。DC1が復旧したら、そのクラスターをスタンバイクラスターに変換する必要があります。

その前に、データベースを手動で調べて、DC1とDC2の間のネットワークが機能しなくなった時点から、DC1のクラスターを手動で停止した時点までに発生したすべての変更を抽出できます。

抽出した変更は、DC2のクラスターに手動で適用することもできます。

18 - FAQ

Patroni の操作とトラブルシューティングに関するよくある質問。

このセクションでは、Patroni に関して最もよくある質問に対する回答を示します。各サブセクションでは、さまざまな種類の質問に焦点を当てます。

これがあなたの疑問のほとんどを解決するのに役立つことを願っています。さらに懸念がある場合、または予期しない問題に直面している場合は、チャット および バグの報告 を参照して、ヘルプを取得したり問題を報告したりする方法を確認してください。

他の HA ソリューションとの比較

repmgr などの他のソリューションでは必要ないのに、Patroni では DCS ノードの別個のクラスターが必要なのはなぜですか？

HA ソリューションを実装するにはさまざまな方法があり、それぞれに長所と短所があります。

repmgr のようなソフトウェアは、ノード間で通信を実行して、いつアクションを実行するかを決定します。

一方、Patroni は、DCS に保存されている状態に依存します。 DCS は、Patroni が何をすべきかを決定するための信頼できる情報源として機能します。

個別の DCS クラスターを使用するとアーキテクチャが肥大化する可能性がありますが、このアプローチにより、Postgres クラスター内でスプリット ブレイン シナリオが発生する可能性も低くなります。

Postgres 管理に関して、Patroni と他の HA ソリューションの違いは何ですか？

Patroni は、Postgres クラスターの高可用性を管理するだけでなく、Postgres 自体も管理します。

Postgres ノードがまだ存在しない場合は、プライマリー ノードとスタンバイ ノードのブートストラップが行われ、ノードの Postgres 構成も管理されます。 Postgres ノードがすでに存在する場合、Patroni がクラスターの管理を引き継ぎます。

上記に加えて、Patroni には自己修復機能もあります。つまり、プライマリー ノードに障害が発生した場合、Patroni はレプリカへのフェイルオーバーを行うだけでなく、元のプライマリーを新しいプライマリーのレプリカとして再参加させようとします。同様に、レプリカに障害が発生した場合、Patroni はそのレプリカの再参加を試みます。

だからこそ、Patroni は「HA ソリューションのテンプレート」と呼ばれるのです。物理レプリケーションの管理にとどまらず、Postgres 全体を管理します。

DCS

同じ etcd クラスターを使用して、2 つ以上の Patroni クラスターからのデータを保存できますか？

はい、できます！

Patroni クラスターに関する情報は、Patroni の namespace および scope 設定がプレフィックスとして付けられたパスの下の DCS に保存されます。

異なる Patroni クラスター間で namespace と scope が競合しない限り、同じ DCS クラスターを使用して複数の Patroni クラスターからの情報を保存できるはずです。

同じDCSクラスターを参照する異なるPatroniクラスターで、同じnamespaceとscopeの組み合わせを使用するとどうなりますか？
2つ目のクラスターのPostgresシステム識別子が異なる場合、PatroniはそのDCSパス内のデータが一致しないことを検出します。ポーズモード以外では、保存された状態が別のクラスターに属し、Patroniの設定に誤りがあると判断して、2つ目のクラスターを管理せずに終了します。

同じ DCS クラスターを共有する異なる Patroni クラスターを処理する場合は、必ず異なる namespace / scope を使用してください。

DCS クラスターを失った場合はどうなりますか？

DCS は、基本的に Patroni クラスターのステータスと動的構成を保存するために使用されます。

その最初の結果は、DCS フェイルセーフモード が有効になっていない限り、その DCS に依存するすべての Patroni クラスターが読み取り専用モードになることです。

DCS クラスターを失った場合はどうすればよいですか？

DCS クラスターが失われた場合、考えられる結果は 3 つあります。

  1. DCS クラスターが完全に復旧した場合：これには、Patroni 側からのアクションは必要ありません。 DCS クラスターが回復すると、Patroni も回復できるはずです。
  2. DCS クラスターが元の場所で再作成され、エンドポイントは同じままになります。 Patroni 側では変更は必要ありません。
  3. 新しい DCS クラスターが異なるエンドポイントで作成されます。各 Patroni ノードの Patroni 構成内の DCS エンドポイントを更新する必要があります。

2. または 3. のシナリオに直面した場合、Patroni はクラスターの現在のステータスに基づいてステータス情報を再度作成し、Patroni クラスターの各メンバーの Postgres データ ディレクトリ内に保存されている patroni.dynamic.json という名前のバックアップ ファイルに基づいて DCS 上に動的構成を再作成します。

DCS クラスターの過半数を失った場合はどうなりますか？

DCS が応答しなくなるため、Patroni は現在の読み取り/書き込み Postgres ノードを降格させます。

覚えておいてください: Patroni は、DCS の状態に依存してクラスター上でアクションを実行します。

DCS フェイルセーフモード を使用すると、この状況を軽減できます。

patronictl

Patroni ホストで patronictl を実行する必要がありますか？

いいえ、その必要はありません。

Patroni ホストにアクセスできる場合、そのホストで patronictl を実行すると、patroni エージェントとまったく同じ構成ファイルを patronictl アプリケーションに使用できるため便利です。

ただし、patronictl は基本的にクライアントであり、リモート マシンから実行できます。必要なのは、DCS および Patroni メンバーの REST API に到達できるように、十分な構成を提供することだけです。

1 つの Patroni メンバーの情報が patronictl list コマンドの出力から消えたのはなぜですか？

patronictl list で表示される情報は、DCS の内容に基づいています。

メンバーに関する情報が DCS から消えた場合は、そのノード上の Patroni エージェントが実行されていないか、DCS と通信できない可能性が高くなります。

メンバーは情報を更新できないため、情報は最終的に DCS から期限切れになり、その結果メンバーは patronictl list の出力に表示されなくなります。

patronictl list コマンドの出力で、Patroni メンバーの 1 つに関する情報が最新ではないのはなぜですか？

patronictl list で表示される情報は、DCS の内容に基づいています。

デフォルトでは、その情報は Patroni によってほぼ loop_wait 秒ごとに更新されます。つまり、すべてが正常に機能している場合でも、DCS に保存されている情報に最大 loop_wait 秒の遅れが生じる可能性があります。

ただし、これはルールではないことに注意してください。 Patroni によって実行される一部の操作により、DCS 情報が即座に更新されます。

構成

動的構成とローカル構成の違いは何ですか？

動的構成 (またはグローバル構成) は、DCS に保管される構成であり、Patroni クラスターのすべてのメンバーに適用されます。これは主に、構成を保存すべき場所です。

ノードに固有の設定、またはグローバル構成を上書きする設定は、目的の Patroni メンバーにのみローカル構成として設定する必要があります。そのローカル構成は、構成ファイルまたは環境変数を通じて指定できます。

詳細については、構成 を参照してください。

Patroni の構成の種類と優先順位は何ですか？

種類は次のとおりです。

  • 動的構成: すべてのメンバーに適用されます。
  • ローカル構成: ローカルメンバーに適用され、動的構成をオーバーライドします。
  • 環境構成: ローカル メンバーに適用され、動的構成とローカル構成の両方を上書きします。

注: 一部の Postgres GUC はグローバルに、つまり動的構成を通じてのみ設定できます。これに加えて、Patroni がハードコードされた値を強制する GUC もあります。

詳細については、構成 を参照してください。

Patroni 構成ファイルの作成に役立つ機能はありますか？

はい、あります。

patroni --generate-sample-config または patroni --generate-config コマンドを使用して、それぞれサンプルの Patroni 構成、および既存の Postgres インスタンスに基づく Patroni 構成を生成できます。

詳細については、サンプル構成の生成 および 構成の生成 を参照してください。

bootstrap.dcs 構成でパラメーターを変更しましたが、Patroni は変更をクラスター メンバーに適用しません。なにが問題ですか？

bootstrap.dcs で構成された値は、新しいクラスターをブートストラップする場合にのみ使用されます。これらの値は、ブートストラップ中に DCS に書き込まれます。

ブートストラップ フェーズが終了した後は、DCS を介してのみ動的構成を変更できます。

詳細については、次の質問を参照してください。

動的構成を変更するにはどうすればよいですか？

DCS の構成を変更する必要があります。これは、次のいずれかの方法で実現されます。

ローカル設定を変更するにはどうすればよいですか？

対応する Patroni メンバーの構成ファイルを変更し、SIGHUP を使用して Patroni エージェントに通知する必要があります。これは、次のいずれかのアプローチを使用して実行できます。

  • POST リクエストを REST API 再読み込みエンドポイント に送信します。または

  • patronictl reload を実行します。または

  • SIGHUP を使用して Patroni プロセスにローカルに通知します。

    • systemd を通じて Patroni を開始した場合は、コマンド systemctl reload PATRONI_UNIT.service を使用できます。PATRONI_UNIT は Patroni サービスの名前です。または
    • 他の方法で Patroni を開始した場合は、patroni プロセスを特定し、kill -s HUP PID を実行する必要があります。PID は、patroni プロセスのプロセス ID です。

注: patronictl reload によるリロードが機能しない場合があります。

  • 期限切れの REST API 証明書: patronictl の -k オプションを使用することでこれを軽減できます。
  • 間違った資格情報: たとえば、構成ファイル内の restapi または ctl 資格情報を変更し、同じ構成ファイルを Patroni および patronictl に使用する場合です。

環境構成を変更するにはどうすればよいですか？

環境構成は、Patroni の起動時にのみ読み取られます。

これを念頭に置いて、環境構成を変更した場合は、対応する Patroni エージェントを再起動する必要があります。

クラスターでフェイルオーバーが発生しないよう注意してください。patronictl pause の確認をお勧めします。

通常の動作中に繰り返されるハートビート ログの行を減らすにはどうすればよいですか?

Lock owner: ... や no action. I am ... などの行が繰り返されるためにログにノイズが多すぎる場合は、log.deduplicate_heartbeat_logs: true を構成します。

これは、Patroni YAML ファイル (ログ設定 ) または PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS=true を使用して設定できます。

これにより、ハートビート メッセージの繰り返しが抑制されるためログの量が減りますが、フェイルオーバー診断時に役立つループごとのハートビートの可視性も失われることに注意してください。

リロードが必要な Postgres GUC を変更するとどうなりますか？

前の質問で説明したように動的構成またはローカル構成を変更すると、Patroni が Postgres 構成の再ロードを処理します。

再起動が必要な Postgres GUC を変更するとどうなりますか？

Patroni は、影響を受けるメンバーに pending restart のフラグを付けます。

メンバーをいつ、どのように再起動するかを決定するのはあなた次第です。これは、次のいずれかの方法で実現できます。

注: 一部の Postgres GUC では、Postgres ノードを再起動する順序に関して特別な管理が必要です。詳細については、共有メモリーのパラメーター を参照してください。

Patroni 構成の etcd と etcd3 の違いは何ですか？

etcd は etcd の API バージョン 2 を使用し、etcd3 は etcd の API バージョン 3 を使用します。

API バージョン 2 によって保存された情報は、API バージョン 3 では管理できず、その逆も同様であることに注意してください。

次の理由から、etcd ではなく etcd3 を構成することをお勧めします。

  • API バージョン 2 は、etcd v3.4 以降、デフォルトで無効になっています。
  • API バージョン 2 は etcd v3.6 で完全に削除されました。

Patroni 構成で use_slots を有効にしていますが、クラスター メンバーがしばらくオフラインになると、そのメンバーによって使用されているレプリケーション スロットが上流ノードで削除されます。その問題を回避するにはどうすればよいでしょうか？

次の 2 つのオプションがあります。

  1. member_slots_ttl (デフォルト値 30min、Patroni 4.0.0 および PostgreSQL 11 以降で利用可能) を調整でき、メンバーのダウンタイムが構成されたしきい値より短い場合、不在メンバーのレプリケーション スロットは削除されません。
  2. メンバーに対して永続的な物理レプリケーション スロットを構成できます。

Patroni 3.2.0 以降、メンバー スロットを Patroni によって管理される永続スロットとして持つことができるようになりました。

PostgreSQL 11 以降では、Patroni はすべてのノードに永続的な物理スロットを作成し、スロットが削除されないようにするだけでなく、メンバーによって使用された LSN に従ってすべてのノードのスロットの LSN を進めます。

後で対応するメンバーを削除することにした場合、永続スロットの構成を調整するのはあなたの責任です。そうしないと、Patroni はそれらのスロットを永久に保持し続けます。

注: 3.2.0 より古い Patroni でも、メンバー スロットを永続的な物理スロットとして構成することは可能でしたが、それらは現在のリーダーでのみ管理されます。つまり、フェイルオーバー/スイッチオーバーが発生した場合、これらのスロットは新しいリーダー上に作成されますが、不在ノードに必要なすべての WAL セグメントがそこにあることは保証されません。

注: Patroni 3.2.0 であっても、小さな競合状態が発生する可能性が残ります。レプリカ上でスロットが作成された直後は、リーダー上の同じスロットより先に進んでいる場合があり、誰もそのスロットを消費していない場合、フェイルオーバー後に一部のファイルが欠落する可能性が依然としてあります。このことを念頭に置き、必要な WAL のリストアや PITR を可能にする継続的アーカイブを構成することを推奨します。

loop_wait、retry_timeout、ttl の違いは何ですか？

Patroni は、HA サイクルと呼ばれるものを随時実行します。各 HA サイクルで、クラスターに対して一連のチェックを実行してその健全性を判断し、ステータスに応じてスタンバイへのフェイルオーバーなどのアクションを実行する場合があります。

loop_wait は、HA チェックの新しいサイクルを実行する前に Patroni がスリープする時間を秒単位で決定します。

retry_timeout は、DCS および Postgres での再試行操作のタイムアウトを設定します。たとえば、DCS が retry_timeout 秒を超えて応答しない場合、Patroni は安全のためにプライマリー ノードを降格する可能性があります。

ttl は、DCS の leader ロックのリース時間を設定します。クラスターの現在のリーダーが、HA サイクル中に ttl を超えてリースを更新できない場合、リースは期限切れになり、クラスター内で leader race がトリガーされます。

注: これらの設定を変更する場合は、Patroni がドキュメントの 動的 セクションで説明されているルールと最小値を強制することに注意してください。

Postgres 管理

Postgres 構成で Postgres GUC を直接変更できますか？

可能ですが、それは避けるべきです。

Postgres 構成は Patroni によって管理されており、構成ファイルを直接編集しようとしても、Patroni が最終的にそれらを上書きするため、編集は無駄に終わる可能性があります。

Patroni によって実行される管理を回避するために使用できるオプションがいくつかあります。

  • $PGDATA/postgresql.base.conf を通じて Postgres GUC を変更します。または
  • postgresql.base.conf の代わりに使用される postgresql.custom_conf を定義して、外部で管理できるようにします。または
  • ALTER SYSTEM / ALTER DATABASE / ALTER USER を使用して GUC を変更します。

詳細については、セクション 重要な構成ルール を参照してください。

いずれの場合も、Patroni を通じてすべての Postgres 構成を管理することをお勧めします。これにより、管理が集中化され、必要な場合の Patroni のデバッグが容易になります。

Postgres ノードを直接再起動できますか？

いいえ、Postgres を直接管理しようとするべきではありません!

Patroni を使用せずに Postgres サーバーを再起動しようとすると、クラスターがフェイルオーバーに直面する可能性があります。

Postgres サーバーを管理する必要がある場合は、Patroni によって公開されている方法で実行してください。

Patroni は、既存の Postgres クラスターの管理を引き継ぐことができますか？

はい、できます！

詳細な手順については、既存データの引き継ぎ を参照してください。

Patroni は Postgres をどのように管理しますか？

Patroni は、pg_ctl や postgres などの Postgres バイナリを実行することによって、Postgres の起動と停止を処理します。

これを念頭に置いて、systemd ユニット (例: postgresql.service) など、Postgres クラスターを管理し得る他のソースを無効化することが必須です。クラスター内の Postgres インスタンスを開始、停止、昇格できるのは Patroni のみであるべきです。そうしないと、スプリット ブレイン シナリオが発生する可能性があります。たとえば、プライマリーとして動作していたノードが障害で停止し、ユニット postgresql.service が有効になっている場合、そのユニットが Postgres を再び起動し、スプリット ブレインを引き起こす可能性があります。

概念と要件

Patroni の一部を構成するアプリケーションはどれですか？

Patroni には基本的に 2 つのアプリケーションが同梱されています。

  • patroni: これは、Postgres ノードの管理を担当する Patroni エージェントです。
  • patronictl : これは、Patroni クラスターと対話する (スイッチオーバー、再起動、構成の変更などを実行する) ために使用されるコマンドライン ユーティリティです。詳細については、patronictl を参照してください。

Patroni の standby cluster とは何ですか？

これは、プライマリー Postgres ノードが実行されていないクラスターです。つまり、クラスター内に読み取り/書き込みメンバーがありません。

これらの種類のクラスターは、別のクラスターからデータをレプリケートするために存在し、通常、データ センター間でデータをレプリケートする場合に役立ちます。

クラスター内には、リモート Postgres ノードからの変更のレプリケーションを担当するスタンバイとなるリーダーが存在します。次に、そのようなリーダー メンバーからのカスケード レプリケーションで構成された一連のスタンバイが存在します。

注: スタンバイ クラスターは、レプリケーション元のソース クラスターについて何も知りません。WAL ストリーミングの代わりに restore_command を使用することもでき、完全に独立した DCS クラスターを使用することもできます。

詳細については、スタンバイクラスター を参照してください。

Patroni の leader とは何ですか？

Patroni の leader は、クラスターのコーディネーターのようなものです。

通常の Patroni クラスターでは、leader が読み取り/書き込みノードになります。

スタンバイ Patroni クラスターでは、leader (別名 standby leader) がリモート Postgres ノードからのレプリケーションを担当し、それらの変更をスタンバイ クラスターの他のメンバーにカスケードします。

Patroni では、クラスター内に最小数の Postgres ノードが必要ですか？

いいえ、Patroni は任意の数の Postgres ノードで実行できます。

Patroni は DCS から分離されていることを覚えておいてください。

Patroni の 一時停止 とはどういう意味ですか？

一時停止は、Postgres 管理から一歩引くようユーザーが Patroni に要請できるようにするために、Patroni が提供する操作です。

これは主に、クラスターでメンテナンスを実行する必要があり、プライマリーを停止したときにスタンバイにフェイルオーバーするなど、Patroni が HA に関連する決定を行うのを避けたい場合に役立ちます。

詳細については、一時停止 を参照してください。

自動フェイルオーバー

Patroni の自動フェイルオーバー メカニズムはどのように機能しますか？

Patroni の自動フェイルオーバーは、leader race と呼ばれるものに基づいています。

Patroni は、クラスターのステータスを DCS に保存します。その中には、クラスターの現在の leader である Patroni メンバーの名前を保持する leader ロックがあります。

その leader ロックには有効期限が関連付けられています。リーダー ノードが leader ロックのリースを期限内に更新できなかった場合、キーは最終的に DCS から期限切れになります。

leader ロックの有効期限が切れると、Patroni が leader race と呼ぶものがトリガーされ、すべてのノードがチェックの実行を開始して、leader ロールを引き継ぐ最適な候補であるかどうかを判断します。これらのチェックの一部には、他のすべての Patroni メンバーの REST API への呼び出しが含まれます。

leader ロックを引き継ぐための最良の候補であると判断したすべての Patroni メンバーは、引き継ぎを試みます。 leader ロックを取得できる最初の Patroni メンバーは、読み取り/書き込みノード (または standby leader) に昇格し、他のメンバーはこれに従うように構成されます。

Patroni クラスターで自動フェイルオーバーを一時的に無効にすることはできますか？

はい、できます！

これを実現するには、クラスターを一時的に一時停止します。これは通常、メンテナンスを実行する場合に役立ちます。

クラスターの自動フェイルオーバーを再開したい場合は、一時停止を解除するだけです。

詳細については、一時停止 を参照してください。

ブートストラップとスタンバイの作成

Patroni はプライマリー Postgres ノードをどのように作成しますか？スタンバイ Postgres ノードについてはどうですか？

デフォルトでは、Patroni は initdb を使用して新しいクラスターをブートストラップし、pg_basebackup を使用して leader メンバーのコピーからスタンバイ ノードを作成します。

カスタム ブートストラップ メソッドとカスタム レプリカ作成メソッドを作成することで、その動作をカスタマイズできます。

カスタム メソッドは通常、pgBackRest や Barman などのバックアップ ツールによって作成されたバックアップを復元する場合に役立ちます。

詳細については、カスタムブートストラップ および カスタムレプリカの作成 を参照してください。

モニタリング

Patroni クラスターを監視するにはどうすればよいですか？

Patroni は、REST API でいくつかの便利なエンドポイントを公開します。

  • /metrics: Prometheus で使用できる形式でモニタリング メトリクスを公開します。
  • /patroni: ローカルの Patroni/Postgres ノードの状態を JSON 形式で公開します。ここに表示される情報は、/metrics エンドポイントによって表示される情報と非常に似ています。

これらのエンドポイントを使用して、監視チェックを実装できます。

19 - リリースノート

時系列の Patroni リリース ノートと変更履歴。

バージョン 4.1.5

2026-08-12 リリース

互換性の向上

  • PostgreSQL 14.24、15.19、16.15、17.11、18.6 との互換性 (Alexander Kukushkin)

    新しい output_plugin_libraries GUC を追加します。これは、論理デコード出力プラグインを制限します。

改善点

  • REST API 接続リセットのログを WARNING ではなく DEBUG で記録 (Kyle McLaren)

    本物の (接続以外の) エラーの処理に影響を与えることなく、一般的な「書き込み中にクライアントが消えた」という亜種が沈黙していることを確認します。

バグ修正

  • thread_stack_size 検証の調整を修正 (Sundong Kim)

    thread_stack_size スキーマ エントリの aligned 値を 65535 から 65536 に修正します。以前は、patroni --validate-config は、デーモン自体によって適用される 524288 デフォルトを含む、ほぼすべての現実的な値を拒否していました。

  • 'quorum' およびブール型の文字列を受け入れるための synchronous_mode の検証を許可します (Eray Araz)

    patroni --validate-config は、以前は、実行時に受け入れられる quorum や PostgreSQL スタイルのブール文字列などの synchronous_mode 値を拒否していました。

バージョン 4.1.4

2026-07-07 リリース

バグ修正

  • systemd パッケージを使用する前に NOTIFY_SOCKET 環境変数を確認してください (Polina Bungina)

    FileNotFoundError: [Errno 2] No such file or directory 例外を回避するために、NOTIFY_SOCKET 環境変数が設定されている場合にのみ、パッケージをインポートして使用してください。

  • pg_replication_slots クエリーを統合 (Polina Bungina)

    failover 値と synced 値の不適切な処理により、不適切な論理レプリケーション スロットの削除中に KeyError 例外が発生していました。

  • 構成生成時にバージョン固有の認証パラメーターを考慮する (Polina Bungina)

    patroni --generate-config コマンドでは、PostgreSQL 接続から取得したバージョンに基づいて、環境から誤って取得された適用できない認証パラメーターをすべて削除します。

  • PostgreSQL インスタンスがスタンバイとして起動している間に pg_rewind を処理します (Alexander Kukushkin)

    PostgreSQL インスタンスが実行中であるがまだ接続を受け入れていない場合は、pg_controldata 情報にフォールバックします。

  • patroni_postgres_timeline の Prometheus メトリック タイプを修正しました (Huseyin Demir)

    patroni_postgres_timeline メトリクスは、常に単調増加するとは限らないため、counter ではなく gauge として宣言します (たとえば、PostgreSQL インスタンスが実行されていない場合は、0 にリセットされる可能性があります)。

  • クライアントのバックエンドが完全に停止するまでウォッチドッグを停止しないでください。 (Alexander Kukushkin)

    以前は、primary_stop_timeout が最小ウォッチドッグ タイムアウトより短く、停止タイムアウトが実際に期限切れになった場合、すべてのクライアント バックエンドが終了する前に Patroni がウォッチドッグを無効にしていました。

  • 監視クエリーのステートメント タイムアウト エラーを処理 (Alexander Kukushkin)

    ステートメントのタイムアウト エラーが発生した場合は、キャッシュされたロールをフォールバックとして使用して、プライマリーの降格を回避します。さらに、高価な pg_stat_statements GC 呼び出しを回避するために、監視クエリーの pg_stat_statements.track を none に強制的に設定します。

  • wal_status=lost を使用した Patroni 管理のレプリケーション スロットの削除 (Alexander Kukushkin)

    wal_status=lost を使用したレプリケーション スロットは使用できなくなりました。 Patroni は、そのようなスロットを削除し、必要に応じて再作成するようになりました。

  • patronictl メンバー検証エラーのロール表現を修正しました (Polina Bungina)

    例外メッセージ内で正しい文字列表現が使用されていることを確認し、エラーが Error: No CtlPostgresqlRole.REPLICA among provided members のような形式になるのを防ぎます。

バージョン 4.1.3

2026-05-05 リリース

安定性の向上

  • ラベルが間違っている etcd エラーを適切に処理する (Ants Aasma)

    現在の etcd バージョンでは、リースの更新中に etcd リーダーが失われると、Unknown エラーが発生します。 Patroni は、報告されたエラー コードを Unavailable にオーバーライドします。

バグ修正

  • PG_VERSION ファイルが存在しない場合はバイナリ バージョンを使用する (Polina Bungina)

    場合によっては、たとえばカスタム ブートストラップを使用する場合、PG_VERSION ファイルがデータ ディレクトリに存在しないことがあります。この場合、Patroni はバージョンを 0.0 として扱っていたため、バージョン固有のロジックの一部で問題が発生していました。この修正により、Patroni はそのような場合にバイナリからバージョンを取得しようとします。

  • 初期のログメッセージの欠落を避けるためにロガーの初期化をリファクタリングしました。 (Alexander Kukushkin)

    初期のログ メッセージをキャプチャするには、Config をロードする前に PatroniLogger を作成します。

  • RELOADING=1 systemd 通知に MONOTONIC_USEC を含めます (Alexander Kukushkin)

    systemd 257+ では、Type=notify-reload サービス用に RELOADING=1 とともに MONOTONIC_USEC が必要です。これがないと、systemctl reload は無期限にハングします。

改善点

  • backup_label が存在する場合、シングルユーザーのクラッシュ リカバリをスキップします。 (Vadim Ponomarev)

    (カスタム ブートストラップ メソッドを使用せずに) 外部バックアップから復元されたレプリカを起動するときは、シングル ユーザー クラッシュ リカバリをスキップし、通常の起動中に PostgreSQL に処理させます。

  • python-systemd パッケージを使用せずに systemd で実行されている場合に警告するようになりました。 (Alexander Kukushkin)

    起動時に「systemd 統合はサポートされていません」とログに記録する代わりに、NOTIFY_SOCKET を確認し、python-systemd パッケージがインストールされていない systemd で実際に実行している場合にのみ警告します。

バージョン 4.1.2

2026-04-21 リリース

Systemd サポートの改善

  • notify-reload systemd ユニット タイプのサポートを追加しました (Ronan Dunklau)

    RELOADING=1 および READY=1 通知を systemd に送信することで、Patroni が実際に構成のリロードを処理するまで、systemctl reload が待機できるようにします。

  • シャットダウン時に STOPPING=1 通知を systemd に送信します (Alexander Kukushkin)

    Patroni は、systemd 通知プロトコルに従って、systemd にシャットダウンしていることを適切に通知するようになりました。

  • PostgreSQL に systemd を通知させないでください。 (Alexander Kukushkin)

    サンプルの systemd ユニット ファイルから NotifyAccess=all を削除します。 PostgreSQL の起動時に環境から NOTIFY_SOCKET をフィルターして、READY=1 または STOPPING=1 が systemd に送信されないようにします。 Patroni より前に開始され、すでに NOTIFY_SOCKET がある PostgreSQL を引き継ぐ場合は、PostgreSQL のシャットダウン中に READY=1 を再アサートして、その STOPPING=1 を無効にします。

バージョン 4.1.1

2026-04-08 リリース

安定性の向上

  • Python 3.11+ のスレッド変更との互換性 (Alexander Kukushkin)

    実行時にスレッドを開始/停止しないようにします。 REST API および非同期タスクを実行するためのスレッド プールを導入します。グローバル thread_pool_size および restapi.thread_pool_size の構成を許可します。

  • Python 3.14 との互換性 (Alexander Kukushkin)

    Python 3.14 に対してテストを実行し、互換性の問題を修正します。

  • v3.6.9、v3.5.28、v3.4.42 の etcd セキュリティ修正との互換性 (Alexander Kukushkin)

    これらの etcd リリースでは CVE に対処し、動作が変更されたため、クラスター トポロジの読み取りとリース キープアライブは認証なしでは許可されなくなりました。 Patroni は、メンバー検出パスとリースキープアライブ パスで認証し、認証失敗時に再認証し、それに応じてリクエストを再試行することでこれを処理するようになりました。

  • Etcd3 エラー処理の改善 (Alexander Kukushkin)

    壊れた JSON 応答を処理し、JSON エラーの解析方法を柔軟にし、etcd 内部エラーのレポートを改善します。

バグ修正

  • 一時的な Kubernetes 403 エラーでリーダーの更新を再試行します (Sophia Ruan、Alexander Kukushkin)

    Kubernetes API が一時的に 403 Permission Denied を返す場合 (たとえば、一時的な RBAC の問題中)、Patroni は現在のノードがまだリーダーシップを保持しているかどうかを確認し、すぐに降格するのではなく retry_timeout 内でリーダーの更新を再試行するようになりました。

  • 同期モードおよび一時停止時のリーダーノードの名前変更に関する問題を修正しました。 (Alexander Kukushkin)

    /sync キーは、一時停止中の Patroni 再起動 (Postgres 再起動なし) でリーダー ノードの名前を変更した後、更新されませんでした。これにより、次回の再起動後に一時停止せずに Patroni が昇格できなくなりました。

  • 同じプライマリーがタイムラインを増やしたときに pg_rewind チェックをトリガーする (Alexander Kukushkin)

    このようなタイムラインの増加は、シングル ユーザー モードでのクラッシュ リカバリと、他のレプリカ ノードが DCS から分離されている間にリーダー キーを取得した後のプロモートの結果として発生する可能性があります。この場合、リーダー、したがって primary_conninfo が変更されなかったため、レプリカ ノードは pg_rewind ステート マシンをトリガーしませんでした。

  • initdb ブートストラップ中は、スーパーユーザーのパスワードが空でない場合にのみ書き込みます。 (Michael Banck)

    initdb ブートストラップ中に空のパスワードを書き込むと問題が発生していました。

  • failover_priority のバグを synchronous_mode=on で修正しました (Alexander Kukushkin)

    synchronous_node_count > 1 の場合、tag.failover_priority 値は無視されました。

  • primary_conninfo パスワード比較のバグを修正しました (Alexander Kukushkin)

    PostgreSQL 10 以降、Patroni は primary_conninfo でパスファイルを使用しますが、リロードを伴う yaml ファイル構成でレプリケーション パスワードが更新された後、パスファイルの更新に失敗しました。

  • nofailover タグを使用してレプリカを一時停止モードで再起動しないでください。 (Alexander Kukushkin)

    Patroni は、nofailover タグが true に設定されている場合、手動でシャットダウンした PostgreSQL レプリカを一時停止モードで起動していました。

  • PostgreSQL が開始状態の場合の check_recovery_conf() を修正しました。 (Alexander Kukushkin)

    PostgreSQL v12 以降の場合、サーバーがまだ起動中で接続を受け入れていない間は、pg_settings をクエリーできません。 postgresql.conf を書き込むときに、不足している回復パラメーターが内部状態に追加されるようになりました。さらに、Ha.is_healthiest_node() の Postgresql.is_starting() チェックを復元します。

  • initdb/basebackup のユーザー オプションを辞書形式で検証します (m4rrypro)

    initdb または basebackup オプションが (リストではなく) ディクショナリとして提供された場合、option_is_allowed() 検証がバイパスされ、ブロックされたオプションの使用が可能になりました。

  • basebackup オプションのサーバー側圧縮を許可する (m4rrypro)

    compress オプションは basebackup では完全にブロックされていましたが、PostgreSQL 15 以降、サーバー側の圧縮は便利で、プレーンな形式で透過的に機能します。クライアント側の圧縮は依然として拒否されます。

  • カスタム ブートストラップの実行中に PostgreSQL 設定をリロードしないでください。 (Alexander Kukushkin)

    カスタム ブートストラップは複雑で、PostgreSQL の起動と停止が複数回行われる可能性があります。このプロセス中に PostgreSQL 構成をリロードすると、予期しない動作が発生する可能性があります。

  • postgresql.parameters が辞書であることを確認します。 (Alexander Kukushkin)

    postgresql.parameters が辞書ではない場合、新しい設定を破棄します。

バージョン 4.1.0

2025-09-23 リリース

新機能

  • systemd “notify” ユニット タイプのサポートを追加しました (Ronan Dunklau)

    通知ユニット タイプを使用しない場合、Patroni を開始し、systemd を使用してすぐに SIGHUP シグナルを送信し、シグナル ハンドラーを設定する前に事実上強制終了することができます。

  • API および ctl で受信および再生 LSN/ラグ情報を提供します (Polina Bungina)

    Patroni REST API /cluster エンドポイントと patronictl list コマンドは、各レプリカ メンバーの受信 LSN、リプレイ LSN、受信ラグ、およびリプレイ ラグ情報を提供するようになりました。

  • スタンバイ クラスターへの完全な降格を確実にする (Polina Bungina)

    動的構成に standby_cluster セクションを導入すると、クラスターが適切に降格されるようにしてください。

  • patronictl demote-cluster および promote-cluster コマンドを実装する (Polina Bungina)

    クラスターの降格と昇格のための新しいコマンドは、動的構成の編集と結果ステータスの確認の両方を処理します。

  • sync_priority タグを実装する (Polina Bungina)

    このパラメータは、synchronous_mode が on に設定されている場合に、同期レプリカの選択中にメンバーが持つべき優先順位を制御します。

  • --validate-config の --print オプションを実装します (Polina Bungina)

    検証が成功したら、ローカル構成 (環境構成の上書きを含む) を出力します。

  • kubernetes.bootstrap_labels の実装 (Polina Bungina)

    この機能を使用すると、initializing new cluster、running custom bootstrap script、starting after custom bootstrap、または creating replica 状態にあるときにメンバー ポッドに割り当てられるラベルを定義できます。

  • 重複するハートビート ログを抑制する構成オプションを追加しました (Michael Morris)

    true に設定すると、同一のハートビートログが連続して出力されなくなります。

  • オプションの cluster_type 属性を永続レプリケーション スロットに追加しました (Michael Banck)

    これにより、特定の永続レプリケーション スロットを常に作成するか、プライマリー クラスターまたはスタンバイ クラスター上にのみ作成するかを設定できます。

  • HTTP サーバー ヘッダーを構成可能にする (David Grierson)

    HTTP サーバー ヘッダーで公開される情報を制限できる restapi.server_tokens 構成パラメーターを導入します。

  • レプリカ メンバーのレプリケーションに対する準備状況 API チェックを実装 (Ants Aasma)

    以前の実装では、PostgreSQL が開始されるとすぐにレプリカが準備完了したとみなされました。この変更により、レプリカ ポッドは、PostgreSQL がレプリケート中で、リーダーからそれほど遠くない場合にのみ準備ができているとみなされます。

改善点

  • ウォッチドッグ構成エラーのログ レベルを下げる (Ants Aasma)

    ウォッチドッグが required モードで構成されていない限り、デバッグ ログ レベルで Could not activate Linux watchdog device ログ行を表示します。以前は情報レベルで表示されていました。

  • pg_stat_wal_receiver の written_lsn と latest_end_lsn を活用します (Alexander Kukushkin)

    written_lsn (実際の書き込み LSN) は、pg_last_wal_receive_lsn() によって返されるもの (実際にはフラッシュ LSN) よりも優先されるようになりました。 latest_end_lsn は、ソース ホスト上の WAL フラッシュを指します。プライマリーの場合、DCS に格納されている値は loop_wait 秒ごとにのみ更新されるため、リプレイ ラグをより適切に計算できます。

  • failover=true オプションで作成されたスロットとの相互作用を回避します。 (Alexander Kukushkin)

    この変更は、論理フェイルオーバー スロット機能を完全に機能させるために必要です。

  • PostgreSQL 状態を /metrics REST API エンドポイントに追加します (Ivan Filianin)

    PostgreSQL インスタンスの状態情報が、/metrics REST API エンドポイントの Prometheus 形式の出力で利用できるようになりました。

バージョン 4.0.7

2025-09-22 リリース

新機能

  • PostgreSQL 18 RC1 のサポートを追加 (Alexander Kukushkin)

    GUC のバリデータ ルールが拡張されました。 Patroni は、新しいバックグラウンド I/O ワーカーを適切に処理するようになりました。

バグ修正

  • Windows でのローカルホストの IPv6 への解決に関する潜在的な問題を修正しました。 (András Váczi)

    PostgreSQL で listen_addresses を構成する場合、0.0.0.0 または 127.0.0.1 を使用すると、リッスンするアドレスは IPv4 のみに制限され、IPv6 は除外されます。ただし、一般的な Windows システムでは、localhost はデフォルトで IPv6 アドレス ::1 に解決されることがよくあります。互換性を確保するために、Patroni は、Windows システム上で localhost ではなく 127.0.0.1 をリッスンするように PostgreSQL を構成するようになりました。

  • /config キーが DCS に存在する場合のみグローバル設定を返すようにしました。 (Alexander Kukushkin)

    Patroni REST API は、/config キーが DCS にない場合、エラーを生成する代わりに空の構成を返していました。

  • Etcd が利用できない場合にフェイルセーフ モードがトリガーされない問題を修正しました。 (Alexander Kukushkin)

    Patroni は、etcd3 例外を常に適切に処理するとは限らず、その結果、フェイルセーフ モードがトリガーされませんでした。

  • シグナル ハンドラーの再入デッドロックを修正 (Waynerv)

    PID=1 を使用して Docker コンテナーで実行されている Patroni は、いくつかの特殊な場合に、SIGCHLD を受信した後にデッドロックが発生していました。

  • WAL が予約されていない場合に (永続的な) 物理スロットを再作成します (Israel Barth Rubio)

    WAL を予約せずに Patroni スコープ外で作成された永続的な物理レプリケーション スロットにより、replication slot cannot be advanced エラーが発生していました。これを回避するために、Patroni はそのようなスロットを再作成するようになりました。

  • etcd3 の監視キャンセル メッセージを適切に処理するようにしました。 (Alexander Kukushkin)

    etcd3 が監視チャネルにキャンセル メッセージを送信するとき、接続は閉じられません。これにより、Patroni が古いデータを使用することになります。 Patroni は、チャンク化された応答を読み取るループを中断し、Patroni 側の接続を閉じることで問題を解決するようになりました。

  • HTTPConnection ソケットが pyopenssl でラップされている場合の処理 (Alexander Kukushkin)

    Patroni は、python-etcd で強制されている pyopenssl インターフェイスを正しく使用していませんでした。

ドキュメントの改善

  • 2 ノード クラスター ガイダンスを改善しました (Nikolay Samokhvalov)

    フェイルオーバー中の動作と DCS 要件を明確にします。

バージョン 4.0.6

2025-06-06 リリース

バグ修正

  • 優先順位の高いリーダーからのフェイルオーバーのバグを修正しました。 (Alexander Kukushkin)

    以前のリーダーが現在のノードと同じ LSN を報告する場合、Patroni は優先順位の高いそのリーダーを無視します。

  • PGDATA の外部で作成された postgresql.conf ファイルの権限を修正しました (Michael Banck)

    PGDATA ディレクトリの外に postgresql.conf ファイルを作成する場合は、システム全体の umask 値を尊重してください。

  • synchronous_mode=quorum のスイッチオーバーに関するバグを修正しました。 (Alexander Kukushkin)

    候補者が指定されている場合は、定足数要件をチェックしません。

  • クラスターの term を比較して古い etcd ノードを無視する (Alexander Kukushkin)

    etcd クラスターの最後の既知の “raft_term” を記憶し、クライアント リクエストを実行するときに、それを etcd ノードによって報告された “raft_term” と比較します。

  • SIGHUP 受信時に PostgreSQL 構成ファイルを更新する (Alexander Kukushkin)

    以前は、Patroni は、グローバルまたはローカル構成の変更が検出された場合にのみ、PostgreSQL 構成ファイルを置き換えていました。

  • etcd3 によって発生した Unavailable 例外を適切に処理するようにしました。 (Alexander Kukushkin)

    Patroni は以前、そのようなリクエストを同じ etcd3 ノードで再試行していましたが、別のノードに切り替える方がより良い戦略です。

  • etcd3 リース処理を改善しました (Alexander Kukushkin)

    Patroni が HA ループごとに少なくとも 1 回、etcd3 リースを更新するようにしてください。

  • リーダー ロックを取得しようとするときに、409 ステータス コードの注釈を再確認します。 (Alexander Kukushkin)

    Patroni バージョン 4.0.3 で読み取られたリーダー オブジェクトに対して行われたのと同じ動作を実装します。

  • スロットを進めるときは replay_lsn を考慮してください (Polina Bungina)

    replay_lsn を超えてレプリカのスロットを進めようとしないでください。さらに、replay_lsn がレプリカ上のこのスロットの confirmed_flush_lsn を既に超えているが、レプリカがこのスロットがプライマリー上にある実際の LSN をまだ再生していない場合は、スロットを replay_lsn の位置に進めます。

  • プロモート後に CHECKPOINT が実行されていることを確認してください。 (Alexander Kukushkin)

    CHECKPOINT がまだ終了していないため、チェックポイント タスクが降格時にリセットされなかった可能性があります。その結果、次のプロモートがトリガーされるときに、古い result が使用されることになりました。

  • “offline” 降格を同時に実行しないでください。 (Alexander Kukushkin)

    シャットダウンが遅い場合、次のハートビート ループで DCS エラー処理メソッドが再度ヒットし、AsyncExecutor is busy, demoting from the main thread 警告が発生し、オフライン降格が再び開始される可能性があります。

  • 初期化失敗時にデータ ディレクトリの名前を変更する前に data_dir 値を正規化します (Waynerv)

    data_dir パラメーター値の末尾のスラッシュによって、初期化の失敗後に名前変更プロセスが中断されないようにします。

  • synchronous_standby_names に期待値が含まれていることを確認します (Alexander Kukushkin)

    以前は、非クォーラム同期レプリケーションのステート マシンを実装するメカニズムは、synchronous_standby_names の実際の値をチェックしませんでした。その結果、pg_stat_replication が synchronous_standby_names のサブセットである場合、synchronous_standby_names の古い値が使用されていました。

バージョン 4.0.5

2025-02-20 リリース

安定性の向上

  • python-json-logger>=3.1 との互換性 (Alexander Kukushkin)

    古い API の使用法によって生成される警告を削除します。

  • Python 3.13 との互換性 (Alexander Kukushkin)

    Python 3.13 に対してテストを実行します。

  • pyinstaller>=4.4 との互換性 (Joe Jensen)

    pyinstaller toc 属性が存在しない場合は、デフォルトの iter_modules にフォールバックします。

  • PostgreSQL 9.5 サポートに関する問題を修正しました (Alexander Kukushkin)

    • pg_rewind 出力形式を適切に処理します。
    • synchronous_standby_names 形式が “num” 仕様をサポートしていないことを考慮してください。

  • urlparse の最新の変更との互換性 (Alexander Kukushkin)

    urlparse は、URL に [] 文字を含む複数のホストを受け入れなくなりました。この問題を軽減するには、可能な場合は libpq から PQconninfoParse() のネイティブ ラッパーに切り替え、古いバージョンの libpq にリンクされている古い psycopg2 バージョンに対してのみ実装を使用してください。

バグ修正

  • 再起動の確認時に再起動されるメンバーのみを表示します (András Váczi)

    以前は、patronictl restart <clustername> --pending を実行すると、再起動が保留されているかどうかに関係なく、確認ですべてのメンバーがリストされていました。

  • Patroni 停止時に長時間実行中のジョブをキャンセルし、レプリカ ブートストラップ失敗時にデータ ディレクトリを削除する (Alexander Kukushkin)

    以前は、レプリカのブートストラップ中に Patroni が停止しても、pg_basebackup / wal-g / pgBackRest / barman などのツールが動作を継続することがありました。

  • patronictl edit-config でスラッシュを含むクラスター名を適切に処理するようにしました。 (Antoni Mur)

    cluster_name のスラッシュをアンダースコアに置き換えます。

  • 物理スロットを早期に削除しないようにします (Alexander Kukushkin)

    フェイルオーバー後に、xmin を含む物理レプリケーション スロットの削除を延期します。新しいプライマリーでは、このメンバーが昇格されるまで、レプリカでは、クラスター内にリーダーが存在するまで延期します。

  • controldata() のサブプロセスによって発生したすべての例外を処理します。 (Alexander Kukushkin)

    Patroni は、pg_controldata ユーティリティの呼び出し時に発生する可能性のあるすべての例外を適切に処理していませんでした。

  • フェイルオーバー時に元リーダーのスロットが保持されないバグを修正しました。 (Alexander Kukushkin)

    フェイルオーバー時に前のリーダーの /member キーが同時に期限切れになるときに、DCS に存在するメンバーに誤って依存することを避けてください。

  • クォーラム ステート マシンのいくつかのバグを修正しました (Alexander Kukushkin)

    • リーダー レースに健全なノードがあるかどうかを評価する場合、降格する前にクォーラム要件を考慮する必要があります。これがないと、元のリーダーが非同期ノードに囲まれて回復することになる可能性があります。
    • QuorumStateResolver は、レプリカ ノードがすぐに参加して切断される場合を正しく処理していませんでした。

改善点

  • 空の設定ファイルまたは辞書以外の設定ファイルでのエラーを改善しました (Julian)

    Patroni 構成ファイルに有効な Mapping オブジェクトが含まれているかどうかを検証するときに、より明示的な例外をスローします。

バージョン 4.0.4

2024-11-22 リリース

安定性の向上

  • py-consul モジュールとの互換性を追加しました (Alexander Kukushkin)

    python-consul モジュールは長い間メンテナンスされていませんが、py-consul が正式な代替品です。 python-consul との下位互換性は維持されます。

  • prettytable>=3.12.0 モジュールとの互換性を追加しました (Alexander Kukushkin)

    非推奨の警告に対処します。

  • ydiff==1.4.2 モジュールとの互換性 (Alexander Kukushkin)

    最新バージョンの互換性の問題を修正し、requirements.txt でバージョンを制限し、最新バージョンの互換性テストを導入します。

バグ修正

  • プライマリー リカバリの失敗後に on_role_change コールバックを実行する (Polina Bungina、Alexander Kukushkin)

    さらに、クラッシュ後に起動に失敗したプライマリーに対して on_role_change コールバックを実行して、レプリカとしてのその後の起動が失敗した場合でも、コールバックが実行される可能性を高めます。

  • patronictl list -W のスレッド リークを修正しました (Alexander Kukushkin)

    DCS インスタンス オブジェクトをキャッシュして、スレッド リークを回避します。

  • サポートされているパラメータのみが接続文字列に書き込まれるようにしました。 (Alexander Kukushkin)

    Patroni は、新しいバージョンで導入されたパラメータを接続文字列に渡していたため、接続エラーが発生していました。

バージョン 4.0.3

2024-10-18 リリース

バグ修正

  • ユーザー作成時にパスワードが漏えいしないよう pgaudit を無効にする (kviset)

    pgaudit 拡張機能が有効になっている場合、Patroni は作成時に superuser、replication、および rewind のパスワードをログに記録していました。

  • 混合セットアップの問題を修正しました: プライマリーが Patroni v4 より前、レプリカが v4+ (Alexander Kukushkin)

    リーダー上で実行されている Patroni バージョンが 4.0.0 より前の場合は、/status キーからメンバーのスロット位置を取得しようとするのではなく、/members キーから抽出された xlog_location を使用します。そうしないと、レプリカ上で WAL が蓄積されていました。

  • Patroni バリデーターを持たない有効な PostgreSQL GUC を無視しないでください (Polina Bungina)

    GUC に Patroni バリデーターがなくても、実際には有効な GUC であるかどうかを、引き続き postgres --describe-config に対してチェックします。

改善点

  • K8s でリーダー オブジェクトを読み取るときに、409 ステータス コードの注釈を再確認します。 (Alexander Kukushkin)

    リクエストがターゲットを正常に更新している間に、PATCH リクエストが Patroni によってキャンセルされた場合は、追加の更新を回避します。

  • sslnegotiation クライアント側接続オプションのサポートを追加しました (Alexander Kukushkin)

    sslnegotiation は、最終的な PostgreSQL 17 リリースに追加されました。

バージョン 4.0.2

2024-09-17 リリース

バグ修正

  • 構成検証ファイルの検出中に例外を処理します (Alexander Kukushkin)

    Patroni にリスト操作を実行するための十分な権限がないディレクトリをスキップします。

  • 非アクティブなホット物理レプリケーション スロットが xmin を保持しないようにします (Alexander Kukushkin、Polina Bungina)

    バージョン 3.2.0 以降、Patroni はレプリカ上のすべてのメンバーに対して物理レプリケーション スロットを作成し、pg_replication_slot_advance() 関数を使用してそれらを定期的に前方に移動します。ただし、何らかの理由で hot_standby_feedback が有効で、プライマリーがレプリカに降格された場合、現在非アクティブなスロットの NOT NULL xmin 値が新しいプライマリーに伝播されます。その結果、xmin ホライズンは前方に移動されず、バキュームはデッドタプルをクリーンアップできなくなります。この修正により、Patroni は、非アクティブであるはずだが NOT NULL xmin 値を持つ物理レプリケーション スロットを再作成します。

  • 起動フェーズ中に未処理の DCSError を修正しました (Waynerv)

    ノード名の一意性を確認する前に、DCS 接続を確認してください。

  • pg_settings のクエリー時に CMDLINE_OPTIONS GUC を明示的に含めるようになりました。 (Alexander Kukushkin)

    Patroni が実行中のスタンバイに参加するときに、コマンド ライン パラメーターとしてポストマスターに渡されるすべての GUC が復元されていることを確認してください。これは、Patroni 3.2.2 で修正されたバグのフォローアップです。

  • synchronous_standby_names 引用ロジックのバグを修正しました (Alexander Kukushkin)

    PostgreSQL ドキュメントによると、ANY および FIRST キーワードは二重引用符で囲まれることになっていますが、Patroni では以前は二重引用符で囲まれていませんでした。

  • キープアライブ接続の範囲外の問題を修正 (hadizamani021)

    設定された ttl に基づいて計算された keepalive オプション値が、現在のプラットフォームで許可されている最大値を超えていないことを確認してください。

バージョン 4.0.1

2024-08-30 リリース

バグ修正

  • Patroni はそれ自体に不要なレプリケーション スロットを作成していました。 (Alexander Kukushkin)

    この問題は、name に大文字または特殊文字が含まれている場合に発生していました。

バージョン 4.0.0

2024-08-29 リリース

警告
  • このバージョンでは、“master” という用語を削除し、“primary” を使用する作業が完了しました。これは、いくつかの後方互換性のない変更を意味します。リリース ノートをよく読んでください。 Patroni 4+ へのアップグレードは、Patroni 3.1.0 以降を実行している場合にのみ確実に機能します。古いバージョンから 4+ に直接アップグレードすることは可能ですが、残りのノードが他の Patroni バージョンで実行されているときにプライマリーで障害が発生すると、予期しない動作が発生する可能性があります。

後方互換性のない変更

  • Patroni コード内の非包括的な “master” 用語を削除する際に、次の後方互換性のない変更が導入されました。
    • Kubernetes では、Patroni はデフォルトで role ラベルを primary に設定します。以前の動作を維持し、ダウンタイムや長時間にわたる複雑な移行を回避したい場合は、パラメーター kubernetes.leader_label_value および kubernetes.standby_leader_label_value を master に構成できます。続きを読む ここで 。
    • Patroni ロールは、master ではなく primary として DCS に書き込まれます。
    • Patroni REST API によって返される Patroni ロールが master から primary に変更されました。
    • Patroni REST API は、/switchover、/failover、/restart エンドポイントへのリクエストで role=master を受け入れなくなりました。
    • /metrics REST API エンドポイントは patroni_master メトリックを報告しなくなります。
    • patronictl は、どのコマンドでも --master オプションを受け入れなくなりました。代わりに --leader または --primary オプションを使用する必要があります。
    • カスタム レプリカ作成メソッドの宣言的構成の no_master オプションは特別なオプションとして扱われなくなりました。代わりに no_leader を使用してください。
    • patroni_wale_restore スクリプトは --no_master オプションを受け入れなくなりました。
    • patroni_barman スクリプトは --role=master オプションを受け入れなくなりました。
    • すべてのコールバック スクリプトは、role=master の代わりに渡された role=primary オプションを使用して実行されます。
  • patronictl failover は、Patroni 3.2.0 以降非推奨となった --leader オプションを受け入れません。
  • ユーザー作成機能 (bootstrap.users 構成セクション) は、Patroni 3.2.0 以降に非推奨となっていたものが削除されました。

新機能

  • Quorum ベースのフェイルオーバー (Ants Aasma、Alexander Kukushkin)

    この機能は、クォーラム ベースの同期レプリケーション (PostgreSQL v10 から利用可能) を実装します。これにより、1 つのスタンバイへのレプリケーションの待ち時間が長くなっても、他のスタンバイで補うことができるため、通常の運用中であっても最悪の場合の待ち時間を短縮できます。 Patroni は、受信した最新のトランザクションに基づいてフェイルオーバー候補を選択することにより、ユーザーに見えるデータ損失を防ぐ追加の保護手段を実装します。

  • Citus セカンダリを pg_dist_node に登録します (Alexander Kukushkin)

    Patroni は、role==replica、state==running で、noloadbalance タグ を持たないノードのリストを pg_dist_node に維持するようになりました。

  • メンバーのレプリケーション スロットの保持を構成可能 (Alexander Kukushkin)

    メンバー キーが存在しない場合にメンバー レプリケーション スロットを維持する期間を制御する member_slots_ttl グローバル構成パラメーターのサポートを実装します。

  • Patroni によって作成されたログ ファイルのアクセス許可を設定可能にしました (Alexander Kukushkin)

    Patroni によって作成されたログ ファイルに特定のアクセス許可を設定できます。指定しない場合、現在の umask 値に基づいて権限が設定されます。

  • PostgreSQL 17 beta3 との互換性 (Alexander Kukushkin)

    GUC のバリデータ ルールが拡張されました。 Patroni はシャットダウン中にすべての新しい補助バックエンドを処理し、論理レプリケーション スロットの同期に必要な dbname を primary_conninfo に設定します。

  • Patroni 構成検証用の --ignore-listen-port オプションを実装します (Sahil Naphade)

    patroni --validate-config の実行時に、すでにバインドされているポートを無視できるようにします。

改善点

  • wal_log_hints を構成可能にする (Paul_Kim)

    use_pg_rewind が off に設定されている場合に、wal_log_hints 構成が有効になることによるオーバーヘッドを回避できます。

  • pg_basebackup コマンドを DEBUG レベルでログに記録 (Waynerv)

    失敗した初期化のデバッグを容易にします。

バグ修正

  • フェイルセーフ時にカスケード ノードの永続スロットを前進させる (Alexander Kukushkin)

    フェールセーフ モードがアクティブになっているときに、カスケード レプリカのスロットがプライマリー上で適切に前進していることを確認します。これは、POST /failsafe REST API リクエストに対するレプリカの応答を xlog_location で拡張することによって行われます。

  • 現在のノードを同期として選択させないでください。 (Alexander Kukushkin)

    現在のプライマリー ノードから、現在のプライマリーの名前と一致する application_name を含む “something” ストリーミングが存在する可能性があります。 Patroni はこの状況を適切に処理していなかったので、プライマリーが同期ノードとして宣言される可能性があり、その結果、スイッチオーバーがブロックされていました。

  • POST /failsafe の restapi.allowlist_include_members を無視します (Alexander Kukushkin)

  • GUC 検証を改善しました (Polina Bungina)

    postgres --describe-config コマンドの実行による追加の検証のため、以前は Patroni 構成を通じてそこにリストされていない GUC を設定することはできませんでした。この制限は現在では削除されています。

  • UNIX ソケットが検出された場合、localhost の行を .pgpass ファイルに追加しました。 (Alexander Kukushkin)

    指定された host パラメータが / 文字で始まる場合、Patroni は .pgpass ファイルに追加行を追加します。これにより、host がデフォルトのソケット ディレクトリ パスと一致する場合の特殊なケースに対処できます。

  • ログの問題を修正 (Waynerv)

    フェールセーフ処理ログに適切なリクエスト URL を定義し、ポストマスター チェック ログのタイムスタンプの順序を修正しました。

バージョン 3.3.2

2024-07-11 リリース

バグ修正

  • プレーンな Postgres 同期レプリケーション モードを修正しました (Israel Barth Rubio)

    synchronous_mode が Patroni に導入されて以来、プレーンな Postgres 同期レプリケーションは機能しませんでした。このバグ修正により、synchronous_mode が無効になっている場合、Patroni はユーザーの構成に従って synchronous_standby_names の値を設定します。

  • スタンバイで論理スロットの無効化を処理します (Polina Bungina)

    PG16 以降、スタンバイ上の論理レプリケーション スロットは、horizon (ホライズン) により無効化される可能性があるため、これ以降、Patroni は無効化されたスロットのコピー (つまり、再作成) を強制します。

  • 論理スロットのアドバンスとコピーによる競合状態を修正しました。 (Alexander Kukushkin)

    このバグにより、無効化された論理レプリケーション スロットが PostgreSQL 再起動で複数回コピーされる場合に発生する可能性がありました。

バージョン 3.3.1

2024-06-17 リリース

安定性の向上

  • Python 3.12 との互換性 (Alexander Kukushkin)

    logging.LogRecord に追加された新しい属性を処理します。

バグ修正

  • replicatefrom タグ処理における無限再帰を修正しました。 (Alexander Kukushkin)

    この修正の一環として、is_physical_slot() のチェックも改善し、ドキュメントを調整します。

  • スタンバイクラスターでの間違ったロールレポートを修正しました。 (Alexander Kukushkin)

    synchronous_standby_names と同期レプリケーションは実際のプライマリー ノードでのみ機能し、カスケード レプリケーションの場合は Postgres によって単純に無視されます。この修正が行われる前は、patronictl list と GET /cluster は一部のノードを同期していると誤って報告していました。

  • allow_in_place_tablespaces GUC の可用性を修正 (Polina Bungina)

    allow_in_place_tablespaces は PostgreSQL 15 に追加されただけでなく、PostgreSQL 10-14 にもバックパッチされました。

バージョン 3.3.0

2024-04-04 リリース

警告

すべての古い Patroni バージョンは ydiff>=1.3 と互換性がありません。

問題の “fix” に使用できるオプションは次のとおりです。

  1. Patroni を最新バージョンにアップグレードします
  2. Patroni のインストール後に ydiff<1.3 をインストールする
  3. cdiff モジュールをインストールする

新機能

  • auth_data を Zookeeper クライアントに渡す機能を追加しました (Aras Mumcuyan)

    接続に使用する認証資格情報を指定できます。

  • Barman 統合用の contrib スクリプトを追加しました (Israel Barth Rubio)

    Barman 操作をリモートで実行できるようにし、カスタム ブートストラップ/カスタム レプリカ メソッドまたは on_role_change コールバックとして使用できるアプリケーション patroni_barman を提供します。詳細については、ここで を確認してください。

  • JSON ログ形式をサポート (alisalemmi)

    plain (デフォルト) とは別に、Patroni は json ログ形式もサポートするようになりました。 python-json-logger>=2.0.2 ライブラリをインストールする必要があります。

  • pending_restart_reason 情報を表示 (Polina Bungina)

    pending_restart フラグが設定される原因となった PostgreSQL パラメーターに関する拡張情報を提供します。 patronictl list と /patroni REST API エンドポイントの両方で、パラメーター名とその “diff” が pending_restart_reason として表示されるようになりました。

  • nostream タグを実装する (Grigory Smolkin)

    nostream タグが true に設定されている場合、ノードは WAL をストリーミングするためにレプリケーション プロトコルを使用せず、代わりにアーカイブ リカバリに依存します (restore_command が構成されている場合)。また、ノード自体とそのすべてのカスケード レプリカ上の永続的な論理レプリケーション スロットのコピーと同期も無効になります。

改善点

  • log セクションの検証を実装します (Alexander Kukushkin)

    これまで、バリデーターは提供されたログ構成の正確性をチェックしていませんでした。

  • PostgreSQL パラメーター変更のログを改善しました (Polina Bungina)

    古い値を人間が判読できる形式に変換し、pg_controldata と Patroni のグローバル構成の不一致に関する情報をログに記録します。

バグ修正

  • 許可されていない pg_basebackup オプションを適切に除外しました (Israel Barth Rubio)

    バグのため、Patroni は、- setting: value 形式で提供されている場合、basebackup レプリカ ブートストラップ メソッドに構成された許可されていないオプションを適切にフィルターで除外していませんでした。

  • etcd3 認証エラー処理を修正しました (Alexander Kukushkin)

    リクエストを実行する直前に認証が行われなかった場合、etcd3 認証エラーが発生した場合は常に 1 回再試行します。また、再認証時にウォッチャーを再起動しないでください。

  • バリデーター ファイル検出のロジックを改善 (Waynerv)

    可能な場合は、importlib ライブラリを使用して、利用可能な構成パラメータを持つファイルを検出します (Python 3.9+ の場合)。この実装はより安定しており、zip アーカイブに基づく Patroni ディストリビューションを壊すことはありません。

  • standby_cluster セクションで複数のホストが指定されている場合にのみ target_session_attrs を使用するようにしました。 (Alexander Kukushkin)

    standby_cluster.host セクションにカンマで区切られた複数のホストが含まれている場合にのみ、target_session_attrs=read-write がスタンバイ リーダー ノードの primary_conninfo に追加されるようになりました。

  • ydiff ライブラリ バージョン 1.3+ の互換性コードを追加しました (Alexander Kukushkin)

    Patroni は、Python モジュールではなく単なる端末ツールであると想定されているため、公開されていない ydiff の一部の API に依存しています。残念ながら、1.3 の API の変更により、古い Patroni バージョンが壊れてしまいました。

バージョン 3.2.2

2024-01-17 リリース

バグ修正

  • DCS が消去されたときに、レプリカが initialize キーを復元しないようにする (Alexander Kukushkin)

    この問題は、Patroni がスタンドアロンの PG クラスターを引き継ぐメソッドで発生していました。

  • Consul から更新されたばかりの同期キーを取得するときに一貫した読み取りを使用します。 (Alexander Kukushkin)

    Consul には、更新したばかりのキーの ModifyIndex をすぐに取得するためのインターフェイスが提供されていないため、明示的な読み取り操作を実行する必要があります。デフォルトでは古い読み取りが許可されているため、古いバージョンのキーを取得することがありました。

  • 再起動が必要なパラメーターが元の値にリセットされた場合に PostgreSQL 構成をリロードする (Polina Bungina)

    以前は、Patroni は構成を更新せず、pending_restart をリセットするだけでした。

  • 同期モードで非同期候補へのフェイルオーバーを実行する際の確認プロンプト メッセージの誤った反転ロジックを修正しました (Polina Bungina)

    この問題は patronictl にのみ存在しました。

  • patronictl のフェイルオーバー候補からリーダーを除外します (Polina Bungina)

    クラスターが正常な場合、既存のリーダーへのフェイルオーバーは何も行われません。

  • Citus データベースと拡張機能をべき等に作成する (Alexander Kukushkin、Zhao Junwang)

    Citus データベースにさらに依存関係を追加する必要がある場合に備えて、post_bootstrap スクリプトでそれらを作成できるようになります。

  • 矛盾する nofailover タグをフィルタリングしないでください (Polina Bungina)

    ノードに設定された構成 {nofailover: false, failover_priority: 0} ではレースに参加できませんでしたが、nofailover タグが優先されるため、レースに参加できるはずです。

  • PyInstaller の凍結問題を修正しました (Sophia Ruan)

    freeze_support() が argparse の後に呼び出されたため、Patroni は Postgres を開始できませんでした。

  • patronictl および Citus 構成の構成ジェネレーターのバグを修正しました (Israel Barth Rubio)

    これにより、環境変数を介して設定された patronictl および Citus 構成パラメーターが、生成された構成に書き込まれることが妨げられました。

  • 実行中のスタンバイに参加するときに、リカバリ GUC と一部の Patroni 管理パラメータを復元します (Alexander Kukushkin)

    Patroni は、内部構造の 1 つで port が欠落しているというエラーにより、Postgres v12 以降の再起動に失敗していました。

  • pending_restart フラグ周りの修正 (Polina Bungina)

    recovery_target_action = promote を使用したカスタム ブートストラップの場合、または誰かが ALTER SYSTEM などを使用して hot_standby または wal_log_hints を変更した場合は、pending_restart を公開しないでください。

バージョン 3.2.1

2023-11-30 リリース

バグ修正

  • patronictl の --format 引数に受け入れられる値を制限しました (Alexander Kukushkin)

    以前は任意の文字列を受け入れ、値が認識されない場合は出力を生成していませんでした。

  • リーダー キーを解放する前に、シャットダウン時にレプリカ ノードがチェックポイント LSN を受信したことを確認します。 (Alexander Kukushkin)

    以前は、場合によっては、その後に CHECKPOINT が続く SWITCH レコードの LSN を使用していました (アーカイブ モードが有効な場合)。その結果、以前のプライマリーは pg_rewind を実行する必要がある場合がありましたが、データ損失は発生しませんでした。

  • ノード名の一意性チェックを実行するときに実際の HTTP リクエストを実行します。 (Alexander Kukushkin)

    コンテナー内でPatroniを実行すると、ポートをリッスンして着信接続を受け入れるdocker-proxy経由でトラフィックがルーティングされる場合があります。このことが誤検出の原因になっていました。

  • Etcd v2 を使用した Citus サポートを修正しました (Alexander Kukushkin)

    Patroni は、etcd v2 を使用した新しい Citus クラスターのデプロイに失敗していました。

  • Postgres v16+ での pg_rewind の動作を修正しました。 (Alexander Kukushkin)

    pg_waldump のエラー メッセージ形式が v16 で変更されたため、必要でない場合でも pg_rewind が Patroni によって呼び出されていました。

  • カスタム ブートストラップのバグを修正しました (Alexander Kukushkin)

    Patroni は、ブートストラップ コマンドそのものである --command 引数を誤って適用していました。

  • REST API ヘルスチェックエンドポイントの問題を修正しました (Sophia Ruan)

    接続が適切に閉じられなかったために、Postgres の再起動後に Postgres の unknown 状態が返される可能性がありました。

  • postgres --describe-config の出力結果をキャッシュ (Waynerv)

    これらは、PostgreSQL 構成の検証にどの GUC が利用できるかを判断するために使用され、Patroni の実行中にこのリストが変更されることは想定されていません。

バージョン 3.2.0

2023-10-25 リリース

非推奨の通知

  • bootstrap.users サポートはバージョン 4.0.0 で削除されます。新しいクラスターのデプロイ後にユーザーを作成する必要がある場合は、bootstrap.post_bootstrap フックを使用してください。

後方互換性のない変更

  • loop_wait + 2*retry_timeout <= ttl ルールを強制し、可能な最小値をハードコードします (Alexander Kukushkin)

    最小値: loop_wait=2、retry_timeout=3、ttl=20。値が小さい場合、またはルールに違反している場合は、値が調整され、警告が Patroni ログに書き込まれます。

新機能

  • フェイルオーバーの優先順位 (Mark Pekala)

    tags.failover_priority の助けを借りて、リーダー レース中にノードをより優先させることができるようになりました。詳細については、ドキュメント (ref タグ) を参照してください。

  • patroni --generate-config [--dsn DSN] および patroni --generate-sample-config を実装しました (Polina Bungina)

    実行中の PostgreSQL クラスターの構成ファイル、または新しい Patroni クラスターのサンプル構成ファイルを生成できます。

  • Patroni REST API には Postgres への専用接続を使用します (Alexander Kukushkin)

    システムにストレスがかかっている場合に、メインのハートビート ループがブロックされるのを避けるのに役立ちます。

  • ノードの name を使用して一部のエンドポイントを強化します (sskserk)

    モニタリング エンドポイントの場合は name が scope の隣に追加され、メトリクス エンドポイントの場合は name がタグに追加されます。

  • フェイルオーバー/スイッチオーバーの厳密な違いを確保する (Polina Bungina)

    ログ メッセージをより正確にし、正常な同期クラスター内の非同期ノードへのフェイルオーバーを許可します。

  • 永続的な物理レプリケーション スロットを永続的な論理スロットと同様に動作させるようにしました。 (Alexander Kukushkin)

    リーダーになることが許可されているすべてのノード上に永続的な物理レプリケーション スロットを作成し、pg_replication_slot_advance() 関数を使用してスタンバイ ノード上のスロットの restart_lsn を進めます。

  • patronictl の --dcs 引数を通じて名前空間を指定する機能を追加しました (Israel Barth Rubio)

    構成ファイルなしで patronictl を使用する場合に、この機能が便利です。

  • カスタム ブートストラップ構成に追加パラメーターのサポートを追加しました (Israel Barth Rubio)

    以前は、カスタム引数を command に追加することしかできませんでしたが、現在はそれらをマッピングとしてリストできるようになりました。

改善点

  • citus.local_hostname GUC を、Patroni が Postgres に接続するために使用するのと同じ値に設定します。 (Alexander Kukushkin)

    Citus がローカルの Postgres への接続を必要とする場合があります。デフォルトでは localhost が使用されますが、常に使用できるわけではありません。

バグ修正

  • スタンバイ クラスターの synchronous_mode 設定を無視する (Polina Bungina)

    Postgres はカスケード同期レプリケーションをサポートしておらず、synchronous_mode を無視しないことによってスタンバイ クラスターでのスイッチオーバーが壊れていました。

  • on_reload コールバックの SIGCHLD を処理 (Alexander Kukushkin)

    そうしないとゾンビ プロセスが発生し、次の on_reload が実行されるときにのみ回収されます。

  • etcd v3 を使用する場合の AuthOldRevision エラーを処理 (Alexander Kukushkin、Kenny Do)

    このエラーは、etcd が JWT を使用するように構成されている場合、および etcd のユーザー データベースが更新されたときに発生します。

バージョン 3.1.2

2023-09-26 リリース

バグ修正

  • wal_keep_size チェックのバグを修正しました (Alexander Kukushkin)

    wal_keep_size は、通常はユニットを持つ GUC ですが、Patroni はその値を int にキャストできませんでした。その結果、bootstrap.dcs の値はその後 /config キーに書き込まれませんでした。

  • /sync キーと synchronous_standby_names 間の不一致を検出して解決します。 (Alexander Kukushkin)

    通常、Patroni は非常に特定の順序で /sync と synchronous_standby_names を更新しますが、バグが発生した場合、または手動で synchronous_standby_names をリセットした場合、Patroni は矛盾した状態になりました。その結果、非同期ノードでフェイルオーバーが発生する可能性がありました。

  • 実行中の Postgres に参加するときに GUC の値を読み取ります (Alexander Kukushkin)

    一時停止する で再起動すると、Patroni は postgresql.conf から synchronous_standby_names GUC を破棄していました。これを解決し、同様の問題を回避するために、Patroni は、すでに実行中の Postgres に結合する場合、GUC の値を読み取ります。

  • ノードの一意性をチェックする際の煩わしい警告をサイレントにしました (Alexander Kukushkin)

    Patroni がすぐに再起動されると、WARNING メッセージが urllib3 によって生成されます。

バージョン 3.1.1

2023-09-20 リリース

バグ修正

  • プロモート時にフェイルセーフ状態をリセット (ChenChangAo)

    フェールセーフ モードがアクティブ化された直後にスイッチオーバー/フェイルオーバーが発生した場合、フェールセーフが非アクティブになった後、新たに昇格されたプライマリーは自身を降格していました。

  • patronictl で無用な警告をサイレントにしました (Alexander Kukushkin)

    patronictl が Patroni と同じ patroni.yaml ファイルを使用し、PGDATA ディレクトリにアクセスできる場合、グローバル構成の不正な値に関する煩わしい警告が表示されていた可能性があります。

  • 特殊なケースに対して同期モードを明示的に有効にしました (Alexander Kukushkin)

    プライマリーからストリーミングするレプリカがない場合、同期モードは事実上アクティブ化されていませんでした。

  • 0 整数値の検証に関するバグを修正しました (Israel Barth Rubio)

    ほとんどの場合、警告が表示されるだけで、問題は発生しませんでした。

  • スタンバイクラスターの論理スロットを返さないようにしました。 (Alexander Kukushkin)

    Patroni はスタンバイ クラスターに論理レプリケーション スロットを作成できないため、グローバル構成で定義されている場合は無視する必要があります。

  • patronictl --help 出力で docstring を表示しないようにしました (Israel Barth Rubio)

    click モジュールは、そのための特別なヒントを取得する必要があります。

  • kubernetes.standby_leader_label_value のバグを修正しました (Alexander Kukushkin)

    この機能は事実上、まったく機能しませんでした。

  • クラスター システム識別子を patronictl list 出力に返しました (Polina Bungina)

    この問題は、Citus のサポートを実装する際に発生しました。識別子はコーディネーターとすべてのワーカーで異なるため、識別子を隠す必要があります。

  • Kubernetes 実装で write_leader_optime メソッドをオーバーライド (Alexander Kukushkin)

    このメソッドは、新しいプライマリーとなる使用可能な正常なレプリカがない場合に、リーダー エンドポイント/ConfigMap にシャットダウン LSN を書き込むことになっています。

  • 一時停止中の停止した postgres を開始しないでください。 (Alexander Kukushkin)

    競合状態のため、Patroni は、一部のリカバリ パラメーター (primary_conninfo など) が変更されたため、スタンバイを再起動する必要があると誤って想定していました。

  • patronictl query コマンドのバグを修正しました (Israel Barth Rubio)

    -m 引数のみが指定された場合、または -r または -m がいずれも指定されなかった場合は機能しませんでした。

  • postgres を起動するためにコマンドラインで使用される整数パラメーターを適切に処理します (Polina Bungina)

    値が文字列として提供され、整数にキャストされていない場合、Citus クラスターの max_connections に基づく max_prepared_transactions の計算が正しく行われませんでした。

  • pg_rewind を決定するときは pg_stat_wal_receiver に依存しないでください (Alexander Kukushkin)

    レプリケーション接続を介して IDENTIFY_SYSTEM によって報告されるタイムラインが常に正しい一方で、pg_stat_wal_receiver によって報告される received_tli が実際に再生されるタイムラインよりも進んでいることが発生する可能性があります。

バージョン 3.1.0

2023-08-03 リリース

後方互換性のない変更

  • restapi.keyfile および restapi.certfile のセマンティクスを変更しました (Alexander Kukushkin)

    以前は、Patroni は、ctl セクションにそれぞれの構成パラメーターがない場合、フォールバックとして restapi.keyfile および restapi.certfile をクライアント証明書として使用していました。

警告

クライアント証明書の検証を有効にした場合 (restapi.verify_client が required に設定されている場合)、ctl.certfile、ctl.keyfile、ctl.keyfile_password で 有効なクライアント証明書 も提供しなければなりません。指定しない場合、Patroni は正しく動作しません。

新機能

  • Pod ロール ラベルを構成可能にする (Waynerv)

    値は、kubernetes.leader_label_value、kubernetes.follower_label_value、および kubernetes.standby_leader_label_value パラメーターを使用してカスタマイズできます。この機能は、master ロールを primary に変更するときに非常に役立ちます。機能と移行手順の詳細については、ここで をご覧ください。

改善点

  • patroni --validate-config のさまざまな改善 (Alexander Kukushkin)

    さまざまな DCS、bootstrap.dcs、ctl、restapi、および ウォッチドッグ セクションのパラメーター検証が改善されました。

  • Patroni の実行中にリカバリ中にクラッシュした場合、Postgres をリカバリモード以外で起動する (Alexander Kukushkin)

    これにより、回復時間が短縮され、不必要なタイムラインの増加を防ぐことができます。

  • /status キーの不必要な更新を避ける (Alexander Kukushkin)

    永続的な論理スロットがない場合、プライマリーの LSN が先に進まない場合でも、Patroni はハートビート ループごとに /status を更新していました。

  • 古いプライマリーがリーダー レースに勝つのを許可しない (Alexander Kukushkin)

    リソース不足により Patroni が長時間ハングしていた場合、リーダー ロックを取得する前に、他のノードが Postgres を昇格していないかどうかがさらにチェックされます。

  • 特定の PostgreSQL パラメーター検証の可視性を実装しました (Alexander Kukushkin、Feike Steenbergen)

    max_connections、max_wal_senders、max_prepared_transactions、max_locks_per_transaction、max_replication_slots、または max_worker_processes の検証が失敗した場合、Patroni は適切なデフォルト値を使用していました。これに加えて、警告も表示されます。

  • PGDATA で作成されたファイルとディレクトリのアクセス許可を設定します (Alexander Kukushkin)

    Patroni によって作成されたすべてのファイルには、所有者の読み取り/書き込み権限のみがありました。この動作により、別のユーザーで実行され、グループの読み取り権限に依存するバックアップ ツールが機能しなくなります。現在、Patroni は PGDATA に対するアクセス許可を尊重し、PGDATA 内に作成されるすべてのディレクトリとファイルに対するアクセス許可を正しく設定します。

バグ修正

  • シェルを介して archive_command を実行します (Waynerv)。

    Patroni は、シングルユーザー モードでクラッシュ リカバリを実行する前、または pg_rewind の前に、一部の WAL セグメントをアーカイブする場合があります。 archive_command に && などのいくつかのシェル演算子が含まれている場合、Patroni では機能しませんでした。

  • 「スイッチオーバー時」シャットダウンチェックを修正しました (Polina Bungina)

    指定された候補がまだストリーミング中であり、シャットダウン チェックポイントを受信していない可能性がありますが、他のいくつかのノードが正常であったためにリーダー キーが削除されました。

  • 「プライマリーである」チェックを修正しました (Alexander Kukushkin)

    リーダーのレース中、レプリカは古いリーダーの Postgres がまだプライマリーとして実行されていることを認識できませんでした。

  • patronictl list を修正しました (Alexander Kukushkin)

    tsv、json、および yaml 出力形式にクラスター名フィールドがありませんでした。

  • 一時停止後の pg_rewind の動作を修正しました (Alexander Kukushkin)

    特定の条件下では、Patroni は、メンテナンス モードを終了した後、偽のプライマリーを pg_rewind を使用してクラスターに戻すことができませんでした。

  • Etcd v3 実装のバグを修正しました (Alexander Kukushkin)

    create_revision/mod_revision フィールドを使用するキー更新がリビジョンの不一致により失敗した場合、内部 KV キャッシュを無効にします。

  • 一時停止中のスタンバイ クラスターのレプリカの動作を修正しました (Alexander Kukushkin)

    リーダー キーの有効期限が切れると、スタンバイ クラスターのレプリカはリモート ノードに従わず、primary_conninfo をそのまま保持します。

バージョン 3.0.4

2023-07-13 リリース

新機能

  • スタンバイ ノードのレプリケーション ステータスを表示するようにしました (Alexander Kukushkin)

    PostgreSQL 9.6+ の場合、Patroni は、スタンバイが他のノードからストリーミングしている場合はレプリケーション状態を streaming として報告し、レプリケーション接続がなく、restore_command が設定されている場合は in archive recovery として報告します。状態は、DCS の member キー、REST API、および patronictl list 出力に表示されます。

改善点

  • Etcd v3 のエラー メッセージを改善しました (Alexander Kukushkin)

    etcd v3 クラスターにアクセスできない場合、Patroni は /v2 エンドポイントにアクセスできないことを報告していました。

  • 可能な場合は patronictl でクォーラム リードを使用する (Alexander Kukushkin)

    etcd または Consul クラスターは読み取り専用に低下する可能性がありますが、patronictl ビューからはすべて問題ありませんでした。今はエラーが出て失敗します。

  • 構成内の名前の重複によるスプリットブレインを防止します (Mark Pekala)

    Patroni の起動時に、同じ名前のノードが DCS に登録されているかどうかを確認し、その REST API のクエリーを試みます。 REST API にアクセスできる場合、Patroni はエラーで終了します。人的ミスから守るのに役立ちます。

  • Patroni の実行中にクラッシュした場合、Postgres をリカバリモード以外で起動する (Alexander Kukushkin)

    これにより、回復時間が短縮され、不必要なタイムラインの増加を防ぐことができます。

バグ修正

  • REST API SSL 証明書は、SIGHUP の受信時にリロードされませんでした (Israel Barth Rubio)

    回帰は 3.0.3 で導入されました。

  • max_connections のようなパラメータの整数 GUC 検証を修正しました (Feike Steenbergen)

    Patroni は引用符で囲まれた数値を好みませんでした。回帰は 3.0.3 で導入されました。

  • synchronous_mode の問題を修正しました (Alexander Kukushkin)

    synchronous_mode_strict が有効なときに、欠落している同期スタンバイを誤って待機しないように、synchronous_commit=off を使用して txid_current() を実行します。

バージョン 3.0.3

2023-06-22 リリース

新機能

  • PostgreSQL 16 beta1 との互換性 (Alexander Kukushkin)

    GUC のバリデータ ルールを拡張しました。

  • PostgreSQL GUC のバリデーターを拡張可能にします (Israel Barth Rubio)

    バリデータ ルールは、patroni/postgresql/available_parameters/ ディレクトリにある YAML ファイルからロードされます。ファイルはアルファベット順に並べられ、次々に適用されます。これにより、非標準の Postgres ディストリビューション用のカスタム バリデーターを使用できるようになります。

  • restapi.request_queue_size オプションを追加しました (Andrey Zhidenkov、Aleksei Sukhov)

    Patroni REST API によって使用される TCP ソケットのリクエスト キュー サイズを設定します。キューがいっぱいになると、それ以降のリクエストでは「Connection denied」エラーが発生します。デフォルト値は 5 です。

  • 新しいクラスターを初期化するときに initdb を直接呼び出します (Matt Baker)

    以前は pg_ctl を介して呼び出されていましたが、initdb に渡すパラメーターの特別な引用符が必要でした。

  • 停止前フックを追加 (Le Duane)

    フックは postgresql.before_stop を介して設定でき、pg_ctl stop の直前に実行されます。終了コードはシャットダウン プロセスには影響しません。

  • カスタム Postgres バイナリ名のサポートを追加しました (Israel Barth Rubio、Polina Bungina)

    カスタム Postgres ディストリビューションを使用する場合、Postgres バイナリが、コミュニティの Postgres ディストリビューションで使用されるものとは異なる名前でコンパイルされる場合があります。カスタム バイナリ名は、postgresql.bin_name.* 設定項目および PATRONI_POSTGRESQL_BIN_* 環境変数を使用して構成できます。

改善点

  • patroni --validate-config のさまざまな改善 (Polina Bungina)

    • bootstrap.initdb をオプションにします。これは新しいクラスターの場合にのみ必要ですが、構成に欠落していると patroni --validate-config がエラーを出しました。
    • postgresql.bin_dir が空の場合、または設定されていない場合にエラーを発生させません。代わりに、まずデフォルトの PATH で Postgres バイナリを検索してみてください。
    • postgresql.authentication.rewind セクションをオプションにします。これが存在しない場合、Patroni はスーパーユーザーを使用しています。

  • patronictl のエラーレポートを改善しました (Israel Barth Rubio)

    \n シンボルは、実際の改行シンボルではなく、そのままレンダリングされました。

バグ修正

  • Citus サポートの問題を修正しました (Alexander Kukushkin)

    昇格されたワーカーからコーディネーターへの REST API 呼び出しがスイッチオーバー中に失敗した場合、指定された Citus グループは無期限にブロックされたままになっていました。

  • patronictl の --dcs-url オプションで etcd3 URL を許可します (Israel Barth Rubio)

    ユーザーが patronictl の --dcs-url オプションを介して etcd3 URL を渡そうとすると、以前は例外が発生していました。

バージョン 3.0.2

2023-03-24 リリース

警告

バージョン 3.0.2 は、3.6 よりも古い Python のサポートを終了しました。

新機能

  • 同期スタンバイ レプリカ ステータスを /metrics エンドポイントに追加しました (Thomas von Dein、Alexander Kukushkin)

    以前は primary/standby_leader/replica のみをレポートしていました。

  • patronictl での PAGER のユーザーフレンドリーな処理 (Israel Barth Rubio)

    これにより、PAGER 環境変数を介してページャーを構成できるようになり、デフォルトの less および more がオーバーライドされます。

  • K8s の再試行可能な HTTP ステータス コードを構成可能にする (Alexander Kukushkin)

    一部の管理対象プラットフォームでは、ステータス コード 401 Unauthorized を取得する可能性がありますが、数回再試行すると解決される場合があります。

改善点

  • recovery_target_action が promote に設定されている場合にのみ、カスタム ブートストラップ中に hot_standby を off に設定します。 (Alexander Kukushkin)

    recovery_target_action=pause を正しく動作させるために必要でした。

  • on_reload コールバックが他のコールバックを強制終了することを許可しないでください。 (Alexander Kukushkin)

    on_start/on_stop/on_role_change は通常、仮想 IP の追加/削除に使用されますが、on_reload はそれらを妨げるべきではありません。

  • AWS コールバック サンプル スクリプトで IMDSFetcher に切り替えました (Polina Bungina)

    IMDSv2 では動作するトークンが必要ですが、IMDSFetcher はそれを透過的に処理します。

バグ修正

  • Kubernetes 上で実行されている Citus クラスターの patronictl switchover を修正しました (Lukáš Lalinský)

    default とは異なる名前空間では機能しませんでした。

  • メジャー バージョンが不明な場合は PGDATA に書き込まないでください。 (Alexander Kukushkin)

    開始直後の PGDATA が空だった場合 (まだマウントされていない可能性があります)、Patroni は、実際のメジャー バージョンが v10+ であっても、PostgreSQL バージョンについて誤った仮定を立て、誤って recovery.conf ファイルを作成していました。

  • コーディネーターフェイルオーバー後のCitusメタデータのバグを修正しました (Alexander Kukushkin)

    citus_set_coordinator_host() 呼び出しではメタデータの同期は発生せず、変更はワーカー ノードでは認識されませんでした。この問題は、citus_update_node() に切り替えることで解決されます。

  • すべての etcd ノードが “failed” である場合、構成ファイルにリストされている etcd ホストをフォールバックとして使用します (Alexander Kukushkin)

    etcd クラスターは時間の経過とともにトポロジを変更する可能性があり、Patroni はそれに従おうとします。ある時点ですべてのノードが到達不能になった場合、Patroni は、再接続を試行するときに、構成のノードと最後に知られているトポロジの組み合わせを使用します。

バージョン 3.0.1

2023-02-16 リリース

バグ修正

  • on_role_change コールバック スクリプトに適切なロール名を渡します。 (Alexander Kukushkin, Polina Bungina)

    Patroni は、昇格時に promoted ロールを on_role_change コールバック スクリプトに誤って渡していました。渡されたロール名が master に戻されました。この回帰は 3.0.0 で導入されました。

バージョン 3.0.0

2023-01-30 リリース

このバージョンでは、Citus との統合が追加され、プライマリーを降格することなく、一時的な DCS の停止に耐えることが可能になります。

警告

  • Version 3.0.0 は、Python 2.7 をサポートする最後のリリースです。今後のリリースでは、3.7 よりも古い Python バージョンのサポートが終了します。

  • RAFT サポートは非推奨になりました。メンテナンスには最善を尽くしますが、起こり得る問題については保証も責任も負いません。

  • このバージョンは、“master” を削除し、“primary” を使用するための最初のステップです。次のメジャー リリースへのアップグレードは、少なくとも 3.0.0 を実行している場合にのみ確実に機能します。

新機能

  • DCS フェイルセーフ モード (Alexander Kukushkin、Polina Bungina)

    この機能が有効になっている場合、Patroni クラスターは一時的な DCS の停止にも耐えることができます。詳細については、ドキュメント を参照してください。

  • Citus サポート (Alexander Kukushkin、Polina Bungina、Jelte Fennema)

    Patroni を使用すると、HA を使用した Citus クラスターのデプロイと管理が容易になります。詳細については、ここで ページを確認してください。

改善点

  • 不明だがアクティブなレプリケーション スロットを削除するときに繰り返されるエラーを抑制しました (Michael Banck)

    Patroni は引き続きこれらのログを書き込みますが、DEBUG にのみ書き込みます。

  • HA ループごとに監視クエリーを 1 つだけ実行します (Alexander Kukushkin)

    同期レプリケーションが有効な場合はそうではありませんでした。

  • 失敗した最新のデータ ディレクトリのみを保持する (William Albertus Dembo)

    ブートストラップが失敗した場合、Patroni はタイムスタンプ サフィックスを付けて $PGDATA フォルダーの名前を変更するために使用されていました。今後、サフィックスは .failed になり、そのようなフォルダーが存在する場合は、名前を変更する前に削除されます。

  • 同期レプリケーション接続のチェックを改善しました (Alexander Kukushkin)

    新しいホストが synchronous_standby_names に追加されると、pg_stat_replication.sync_state = 'sync' に加えてプライマリーに追いついた場合にのみ、DCS で同期として設定されます。

削除された機能

  • patronictl scaffold を削除 (Alexander Kukushkin)

    これを導入した唯一の理由は、スタンバイ クラスターを実行する暫定的な回避策でした。

バージョン 2.1.7

2023-01-04 リリース

バグ修正

  • レガシー Python モジュールとの小さな非互換性を修正しました (Alexander Kukushkin)

    これらにより、Debian buster/Ubuntu bionic上で Patroni をビルド/実行できなくなりました。

バージョン 2.1.6

2022-12-30 リリース

改善点

  • SSL ソケットのシャットダウン時の迷惑な例外を修正しました。 (Alexander Kukushkin)

    HAProxy は、HTTP ステータス コードを取得するとすぐに接続を閉じているため、Patroni が SSL 接続を適切にシャットダウンする時間がありません。

  • arm64 用の Dockerfile の例を調整 (Polina Bungina)

    明示的な amd64 と x86_64 を削除します。libnss_files.so.* は削除しないでください。

セキュリティの向上

  • 非レプリケーション接続に対して search_path=pg_catalog を強制する (Alexander Kukushkin)

    Patroni はスーパーユーザー接続に大きく依存しているため、pg_catalog の対応するオブジェクトと同じ名前と署名を持つ public スキーマのユーザー定義関数や演算子を使用して実行される可能性のある攻撃から保護したいと考えています。そのため、Patroni によって作成されたすべての接続に対して search_path=pg_catalog が適用されます (レプリケーション接続を除く)。

  • パスワードが pg_stat_statements に記録されないようにする (Feike Steenbergen)

    これは、ユーザーの作成時に pg_stat_statements.track_utility=off を設定することで実現されます。

バグ修正

  • proxy_address をオプションとして宣言 (Denis Laxalde)

    これは事実上必須ではないオプションであるためです。

  • insecureオプションの動作を改善しました（Alexander Kukushkin）。

    REST API要求にクライアント証明書を使用していると、ctlのinsecureオプションが正しく動作していませんでした。

  • 新しいクラスターがブートストラップされるときに、bootstrap.dcs からウォッチドッグ構成を取得します (Matt Baker)

    Patroni は、DCS のブートストラップに使用される構成を取得するのではなく、新しいクラスターをブートストラップするときにデフォルトでウォッチドッグを最初に構成していました。

  • WIN32で実行可能ファイルを探す際のファイル拡張子の扱いを修正しました（Martín Marqués）。

    ファイル名に拡張子がまだない場合のみ、.exe を追加してください。

  • Consul TTL 設定を修正 (Alexander Kukushkin)

    HTTPClient で値を設定するときに ttl/2.0 を使用しましたが、クラスのプロパティで現在の値に 2 を乗算するのを忘れていました。その結果、Consul TTL が 2 倍ずれていました。

削除された機能

  • patronictl configure を削除 (Polina Bungina)

    個別の patronictl 構成作成はもう必要ありません。

バージョン 2.1.5

2022-11-28 リリース

このバージョンでは、PostgreSQL 15 との互換性が強化され、etcd v3 のサポートが実稼働対応として宣言されています。 Raft の Patroni はベータ版のままです。

新機能

  • patroni --validate-config の改善 (Denis Laxalde)

    構成が無効な場合はコード 1 で終了し、エラーを標準エラー出力に出力します。

  • 一時停止中にレプリケーション スロットを削除しないでください。 (Alexander Kukushkin)

    Patroni は、メンバーがクラスターに参加またはクラスターから離脱するときに、物理レプリケーション スロットを自動的に作成または削除します。一時停止中のスロットは削除されなくなります。

  • エンドポイントを監視するための HEAD リクエスト メソッドをサポートします (Robert Cutajar)

    GET の代わりに使用された場合、Patroni は HTTP ステータス コードのみを返します。

  • Windows での behave テストをサポート (Alexander Kukushkin)

    新しい REST API エンドポイント POST /sigterm を導入することにより、Windows で正常な Patroni シャットダウン (SIGTERM) をエミュレートします。

  • postgresql.proxy_address の紹介 (Alexander Kukushkin)

    これは、DCS のメンバー キーに proxy_url として書き込まれ、サービスの検出に使用または役立つ可能性があります。

安定性の向上

  • スレッドから pg_replication_slot_advance() を呼び出します (Alexander Kukushkin)

    多くの論理レプリケーション スロットを持つビジーなクラスターでは、pg_replication_slot_advance() 呼び出しがメインの HA ループに影響を及ぼし、メンバー キーの有効期限が切れる可能性がありました。

  • 古いプライマリーで pg_rewind を呼び出す前に、欠落している可能性のある WAL をアーカイブします (Polina Bungina)

    プライマリーがクラッシュして長時間ダウンした場合、一部の WAL ファイルがアーカイブと新しいプライマリーから失われる可能性があります。 pg_rewind が古いプライマリーからこれらの WAL ファイルを削除し、スタンバイとして起動できなくなる可能性があります。 ready WAL ファイルをアーカイブすることで、この問題が軽減されるだけでなく、一般的に継続的なアーカイブ エクスペリエンスが向上します。

  • Kubernetes サービスを作成しようとするときの 403 エラーを無視する (Nick Hudson、Polina Bungina)

    Patroni は、サービスの作成に失敗してログをスパム送信していましたが、実際にはすでに存在している可能性があります。

  • liveness プローブの改善 (Alexander Kukushkin)

    ハートビート ループがプライマリーの ttl よりも長く実行されている場合、またはレプリカの 2*ttl よりも長く実行されている場合、liveness プローブが失敗するようになります。これにより、Kubernetes 上の ウォッチドッグ の代替として使用できるようになります。

  • スイッチオーバー時に同期ノードのみがロックを取得しようとするようにしました。 (Alexander Kukushkin、Polina Bungina)

    以前は、ターゲットを指定せずに手動スイッチオーバーが実行された場合、最新のデータを持つ非同期メンバーが、わずかな確率でリーダーになることがありました。

  • ブートストラップの実行中にクローン作成を避ける (Ants Aasma)

    クラスターのブートストラップの実行中に、リーダーを必要としないレプリカ作成メソッドが起動されないようにします。

  • kazoo-2.9.0 との互換性 (Alexander Kukushkin)

    Python のバージョンによっては、クローズされたソケットで select() が呼び出された場合、SequentialThreadingHandler.select() メソッドで TypeError 例外と IOError 例外が発生する場合があります。

  • ソケットのシャットダウン前にSSL接続を明示的にシャットダウンしました。 (Alexander Kukushkin)

    これを行わないと、OpenSSL 3.0 で unexpected eof while reading エラーが発生しました。

  • prettytable>=2.2.0 との互換性 (Alexander Kukushkin)

    内部の API 変更により、クラスター名のヘッダーが間違った行に表示されていました。

バグ修正

  • Etcd lease_grant の期限切れトークンを処理 (monsterxx03)

    エラーが発生した場合は、新しいトークンを取得してリクエストを再試行します。

  • GET /read-only-sync エンドポイントのバグを修正しました (Alexander Kukushkin)

    これは以前のリリースで導入されましたが、実際には機能しませんでした。

  • データ ディレクトリ ストレージが消失した場合の処理 (Alexander Kukushkin)

    Patroni は、PGDATA が存在し、空でないことを定期的にチェックしますが、ストレージに問題が発生した場合、os.listdir() は OSError 例外を発生させ、ハートビート ループを中断します。

  • ユーザー バックエンドが閉じるのを待機するときに master_stop_timeout を適用します (Alexander Kukushkin)

    ユーザー バックエンドのように見えるものは、実際には停止に失敗しているバックグラウンド ワーカー (Citus Maintenance Daemonなど) である可能性があります。

  • postgresql.listen に対して *:<port> を受け入れます (Denis Laxalde)

    patroni --validate-config は無効であると訴えていました。

  • Raft でのタイムアウトの修正 (Alexander Kukushkin)

    Patroni または patronictl は、起動時に既知のメンバーから Raft クラスター トポロジを取得しようとします。これらの呼び出しは適切なタイムアウトなしで行われました。

  • トークンが変更された場合に Consul サービスを強制的に更新 (John A. Lotoski)

    そうしないと、「rpc error making call: rpc error making call: ACL not found」というエラーが発生します。

バージョン 2.1.4

2022-06-01 リリース

新機能

  • 典型的な Debian/Ubuntu システムでの pg_rewind の動作を改善しました (Gunnar “Nick” Bluth)

    postgresql.conf をデータ ディレクトリの外に保持する Postgres セットアップ (例: Ubuntu/Debian パッケージ) では、pg_rewind --restore-target-wal は restore_command の値を把握できません。

  • Consul サービス チェックで TLSServerName の設定を許可する (Michael Gmelin)

    チェックが IP によって実行され、Consul node_name が FQDN ではない場合に便利です。

  • ウォッチドッグに ppc64le サポートを追加しました (Jean-Michel Scheiwiler)

    また、一部の非 x86 プラットフォームでのウォッチドッグのサポートが修正されました。

  • aws.py コールバックを boto から boto3 に切り替えました (Alexander Kukushkin)

boto 2.x は 2018 以降放棄され、Python 3.9 で失敗します。

  • K8s 上のサービス アカウント トークンを定期的に更新 (Haitao Li)

    Kubernetes v1.21 以降、サービス アカウント トークンは 1 時間で期限切れになります。

  • /read-only-sync 監視エンドポイントを追加しました (Dennis4b)

    これは /read-only に似ていますが、同期レプリカのみが含まれます。

安定性の向上

  • プライマリーとの論理デコード設定に構成の不一致がある場合は、論理レプリケーション スロットをレプリカにコピーしないでください。 (Alexander Kukushkin)

    スロットが plugin または database 構成オプションと一致しない場合、レプリカはプライマリーから論理レプリケーション スロットをコピーしなくなります。以前は、スロットがこれらの構成オプションと一致するかどうかのチェックは、レプリカがスロットをコピーしてそれを使用して開始するまで実行されず、不必要な再起動が繰り返されていました。

  • PostgreSQL v12+ のリカバリ構成パラメーターの特別な処理 (Alexander Kukushkin)

    レプリカとして開始するとき、Patroni は、pg_settings からクエリーする代わりに現在のパラメーター値をキャッシュすることで、リーダー アドレスが変更された場合に postgresql.conf を更新し、再起動/リロードできる必要があります。

  • postgresql.listen パラメータでの IPv6 アドレスの処理が改善されました (Alexander Kukushkin)

    listen パラメータにはポートがあるため、IPv6 アドレスを角括弧内に入れようとしますが、リストに複数の IP がある場合、角括弧は正しく削除されませんでした。

  • ダイバージェンス チェック時に replication 資格情報を使用するのは PostgreSQL v10 以前のみとする (Alexander Kukushkin)

    rewind が有効な場合、Patroni は、新しい Postgres バージョンで superuser または rewind 資格情報を再度使用します。

バグ修正

  • dateutil.parser のインポートが欠落していたのを修正しました (Wesley Mendes)

    テストが失敗しなかったのは、それが他のモジュールからもインポートされていたためです。

  • optime アノテーションが文字列であることを確認します。 (Sebastian Hasler)

    場合によっては、Patroni が数値として渡そうとしていました。

  • 失敗したpg_rewind試行の処理を改善しました (Alexander Kukushkin)

    pg_rewind 中にプライマリーが使用できなくなると、$PGDATA は壊れた状態のままになります。その後、構成で許可されていない場合でも、Patroni はデータ ディレクトリを削除します。

  • PostgreSQL の準備ができていない場合は、リーダー ConfigMap/Endpoint から slots アノテーションを削除しないでください。 (Alexander Kukushkin)

    slots 値が渡されない場合、アノテーションは現在の値を保持します。

  • K8s API ウォッチャーの同時実行の問題を処理 (Alexander Kukushkin)

    特定の (未知の) 条件下では、ウォッチャーが古い状態のままになる可能性があります。その結果、attempt_to_acquire_leader() メソッドは、HTTP ステータス コード 409 により失敗する可能性があります。その場合、ウォッチャーの接続をリセットし、最初から再起動します。

バージョン 2.1.3

2022-02-18 リリース

新機能

  • patronictl の暗号化された TLS キーのサポートを追加しました。 (Alexander Kukushkin)

    これは、ctl.keyfile_password または PATRONI_CTL_KEYFILE_PASSWORD 環境変数を介して構成できます。

  • /metrics エンドポイントにメトリクスを追加しました (Alexandre Pereira)

    具体的には、patroni_pending_restart と patroni_is_paused です。

  • スタンバイクラスター構成で複数ホストを指定できるようにしました。 (Michael Banck)

    スタンバイ クラスターが Patroni クラスターからレプリケートされている場合は、PostgreSQL v10 以降の libpq で利用できるクライアント側のフェイルオーバーを利用するとよいでしょう。つまり、スタンバイ リーダーの primary_conninfo と、接続文字列の target_session_attrs=read-write を設定する pg_rewind です。 pgpass ファイルは複数行 (ホストごとに 1 行) で生成され、プライマリー クラスター ノードで CHECKPOINT を呼び出す代わりに、スタンバイ クラスターは pg_control が更新されるのを待ちます。

安定性の向上

  • 従来の psycopg2 との互換性 (Alexander Kukushkin)

    たとえば、Ubuntu 18.04 パッケージからインストールされた psycopg2 には、UndefinedFile 例外がまだありません。

  • すべての etcd ノードが応答しない場合は etcd3 ウォッチャーを再起動します (Alexander Kukushkin)

    ウォッチャーが生きている場合、すべての etcd ノードに障害が発生していても、get_cluster() メソッドは古い情報を返し続けます。

  • 一時停止中にスタンバイクラスターのリーダーロックを削除しないでください。 (Alexander Kukushkin)

    以前は、ロックはスタンバイ リーダーではなくプライマリーとして実行されているノードによってのみ維持されていました。

バグ修正

  • スタンバイ リーダー ブートストラップのバグを修正しました (Alexander Kukushkin)

    Patroni は、Postgres が 60 秒後に接続の受け入れを開始しない場合、ブートストラップが失敗したとみなしていました。このバグは 2.1.2 リリースで導入されました。

  • カスケード スタンバイへのフェイルオーバーに関するバグを修正しました (Alexander Kukushkin)

    カスケード スタンバイでどのスロットを作成するかを判断する際、リーダーが存在しない可能性があることを考慮するのを忘れていました。

  • Postgres 構成バリデーターの小さな問題を修正しました (Alexander Kukushkin)

    PostgreSQL v14 で導入された整数パラメータは、validator.py で最小値と最大値が引用符で囲まれていたため、検証に失敗していました。

  • リーダーのステータスを確認するときにレプリケーション資格情報を使用する (Alexander Kukushkin)

    remove_data_directory_on_diverged_timelines が設定されているものの、rewind_credentials が定義されておらず、ノード間のスーパーユーザー アクセスが許可されていない可能性があります。

  • REST API 証明書の置換での「ポートが使用中」エラーを修正しました (Ants Aasma)

    証明書を切り替えるときに、同時の API リクエストで競合状態が発生しました。交換期間中にアクティブな API リクエストがある場合、交換はポート使用中エラーでエラーとなり、Patroni はアクティブな API サーバーがない状態でスタックします。

  • パスワードに % 文字が含まれている場合のクラスター ブートストラップのバグを修正しました。 (Bastien Wirtz)

    ブートストラップ メソッドは、すべてのパラメーターを適切に引用符で囲んで DO ブロックを実行しますが、cursor.execute() メソッドはパラメーターが渡された空のリストを好みませんでした。

  • 「AttributeError: no attribute ’leader’」例外を修正しました。 (Hrvoje Milković)

    これは、同期モードが有効で、DCS コンテンツが消去された場合に発生する可能性があります。

  • 発散タイムラインチェックのバグを修正しました (Alexander Kukushkin)

    Patroni は、タイムラインが分岐していると誤って想定していました。 pg_rewind の場合は問題は発生しませんでしたが、pg_rewind が許可されておらず、remove_data_directory_on_diverged_timelines が設定されている場合は、以前のリーダーが再初期化されることになります。

バージョン 2.1.2

2021-12-03 リリース

新機能

  • psycopg>=3.0 との互換性 (Alexander Kukushkin)

    デフォルトでは、psycopg2 が優先されます。 psycopg>=3.0 は、psycopg2 が利用できない場合、またはバージョンが古すぎる場合にのみ使用されます。

  • dcs_last_seen フィールドを REST API に追加します (Michael Banck)

    このフィールドには、クラスター メンバーが最後に (UNIX エポックとして) DCS と正常に通信した時刻が記録されます。これは、ネットワーク パーティションの特定や分析に役立ちます。

  • pg_controldata が「shut down」を報告したときにリーダーのロックを解除します。 (Alexander Kukushkin)

    archive_command が遅い/障害が発生している場合のスイッチオーバー/シャットダウンが遅いという問題を解決するために、Patroni は、pg_controldata が PGDATA が正常に終了した状態 shut down であると報告し始め、すべての変更を受信したレプリカが少なくとも 1 つあることを確認した直後にリーダー キーを削除します。この条件を満たすレプリカがない場合、リーダー キーは削除されず、古い動作が保持されます。つまり、Patroni はロックを更新し続けます。

  • sslcrldir 接続パラメータのサポートを追加しました (Kostiantyn Nemchenko)

    新しい接続パラメータが PostgreSQL v14 に導入されました。

  • Zookeeper で ZNode の ACL 設定を許可する (Alwyn Davis)

    新しい構成オプション zookeeper.set_acls を導入して、Kazoo が作成する各 ZNode にデフォルトの ACL を適用するようにします。

安定性の向上

  • 次回のリカバリの試行を次の HA ループまで遅らせます。 (Alexander Kukushkin)

    (たとえば) ディスク容量不足により Postgres がクラッシュし、そのために起動に失敗した場合、Patroni は熱心にリカバリしようとするため、ログが溢れます。

  • 降格する前にログを追加します。これには時間がかかる場合があります (Michael Banck)

    降格が完了するまでに時間がかかる場合があり、ログを見ても実際に何が起こっているのかが明らかではない場合があります。

  • 「I am」ステータス メッセージを改善しました (Michael Banck)

    no action. I am a secondary ({0}) と no action. I am ({0}), a secondary

  • wal_keep_size に変換するときに wal_keep_segments を int にキャストする (Jorge Solórzano)

    wal_keep_segments をグローバル 動的構成 の文字列として指定することができますが、Python は動的に型付けされた言語であるため、文字列は単純に乗算されます。例: wal_keep_segments: "100" は 100100100100100100100100100100100100100100100100MB に変換されました。

  • 同期レプリケーションが有効な場合、同期ノードのみにスイッチオーバーを許可します。 (Alexander Kukushkin)

    それに加えて、ノードは既知の同期ノードに対してのみリーダー選挙を行います。

  • Postgres が遅い場合にキャッシュされたロールをフォールバックとして使用します。 (Alexander Kukushkin)

    極端な場合には、Postgres が非常に遅くなり、通常の監視クエリーが数秒で終了しないことがあります。 statement_timeout 例外が適切に処理されないと、リーダー キーの有効期限が切れたり、更新が失敗したりしたときに、Postgres が時間どおりに降格されないという状況が発生する可能性があります。このような例外が発生した場合、Patroni はキャッシュされた role を使用して、Postgres がプライマリーとして実行されているかどうかを判断します。

  • メンバー ZNode の不必要な更新を回避します (Alexander Kukushkin)

    メンバー データの値が変更されていない場合、更新は行われません。

  • プロモート後のチェックポイントの最適化 (Alexander Kukushkin)

    最新のタイムラインがすでに pg_control に保存されている場合は、CHECKPOINT を実行しないでください。 initdb で新しいクラスターを初期化した直後の不要な CHECKPOINT を回避するのに役立ちます。

  • 同期ノードを選択する際に nofailover のないメンバーを優先します (Alexander Kukushkin)

    以前は、同期ノードはレプリケーション ラグにのみ基づいて選択されていたため、nofailover タグを持つノードは、他のノードと同じ確率で同期ノードになる可能性がありました。プライマリーに障害が発生した場合、フェイルオーバーが自動的に実行できないため、この動作は混乱を招くと同時に危険でもありました。

  • etcd マシン キャッシュから重複したホストを削除します (Michael Banck)

    etcd クラスター内のアドバタイズされたクライアント URL が正しく構成されていない可能性があります。この場合、Patroni 内の重複を削除するのは簡単な成果です。

バグ修正

  • スロット管理中に一時レプリケーション スロットをスキップします (Alexander Kukushkin)

    v10 から開始すると、pg_basebackup は WAL ストリーミング用の一時レプリケーション スロットを作成しますが、スロット名が不明であるため、Patroni はそれを削除しようとしていました。これを修正するために、pg_replication_slots ビューをクエリーするときにすべての一時スロットをスキップします。

  • pg_replication_slot_advance() がタイムアウトしないようにします (Alexander Kukushkin)

    この場合、Patroni はデフォルトの statement_timeout を使用していたため、呼び出しが失敗すると回復できない可能性が非常に高く、その結果、pg_wal と pg_catalog のサイズが増大して肥大化します。

  • /status は降格時に更新されませんでした (Alexander Kukushkin)

    PostgreSQL を降格した後、古いリーダーは DCS 内の最後の LSN を更新します。 2.1.0 から、新しい /status キーが導入されましたが、optime は依然として /optime/leader に書き込まれていました。

  • 降格時に DCS 例外を処理します (Alexander Kukushkin)

    リーダー ロックの更新に失敗したためにマスターを降格しているときに、DCS が完全にダウンし、get_cluster() 呼び出しで例外が発生する可能性があります。適切に処理されないと、DCS が回復するまで Postgres が停止したままになります。

  • use_unix_socket_repl が機能しない場合もありました (Alexander Kukushkin)

    具体的には、postgresql.unix_socket_directories が設定されていない場合です。この場合、Patroni は libpq のデフォルト値を使用することになります。

  • Patroni REST API に関するいくつかの問題を修正しました (Alexander Kukushkin)

    clusters_unlocked が未定義の場合があり、GET /metrics エンドポイントで例外が発生しました。さらに、エラー処理方法では、connect_address タプルには常に 2 つの要素があると想定していましたが、実際には IPv6 の場合はさらに多くの要素がある可能性があります。

  • 巻き戻しを決定する前に、新しく昇格したノードが回復を完了するまで待ちます。 (Alexander Kukushkin)

    実際のプロモーションが行われて新しいタイムラインが作成されるまでには、しばらく時間がかかる場合があります。待機せずに、レプリカは巻き戻しが必要ではないという結論に達する可能性があります。

  • 巻き戻しを決定する際に、履歴ファイル内で欠落しているタイムラインを処理するようになりました。 (Alexander Kukushkin)

    現在のレプリカ タイムラインがプライマリーの履歴ファイルにない場合、レプリカは巻き戻しが必要ないと誤って想定していました。

バージョン 2.1.1

2021-08-19 リリース

新機能

  • ETCD SRV 名前サフィックスのサポート (David Pavlicek)

    etcd を使用すると、同じドメイン内の複数の etcd クラスターを区別できるようになり、Patroni もこの機能をサポートするようになりました。

  • 履歴に新しいリーダー情報を追加 (huiyalin525)

    新しい列が patronictl history 出力に追加されます。

  • CA バンドルをクラスター内 Kubernetes 構成用に構成可能にします (Aron Parsons)

    デフォルトでは、Patroni は /var/run/secrets/kubernetes.io/serviceaccount/ca.crt を使用しており、この新機能によりカスタム kubernetes.cacert を指定できます。

  • Consul サービスとしての動的な登録/登録解除とタグの変更をサポートします (Tommy Li)

    以前は、Patroni の再起動が必要でした。

バグ修正

  • REST API の不必要なリロードを回避します (Alexander Kukushkin)

    以前のリリースでは、ディスク上で変更された場合に REST API 証明書を再ロードする機能が追加されました。残念ながら開始直後に無条件でリロードが発生してしまいました。

  • etcd.use_proxies が設定されている場合はクラスター メンバーを解決しません。 (Alexander Kukushkin)

    Patroni は起動時にメンバーのリストをクエリーして etcd クラスターの健全性をチェックします。それに加えて、ホスト名を解決しようとしましたが、これはプロキシ経由で etcd を操作する場合には必要なく、不要な警告を引き起こしていました。

  • pg_stat_replication 内の NULL 値を持つ行をスキップします (Alexander Kukushkin)

    state = 'streaming' の場合でも、pg_stat_replication ビューの replay_lsn、flush_lsn、または write_lsn フィールドに NULL 値が含まれる可能性があるようです。

バージョン 2.1.0

2021-07-06 リリース

このバージョンでは、PostgreSQL v14 との互換性が追加され、論理レプリケーション スロットがフェイルオーバー/スイッチオーバーを切り抜けられるようになり、REST API の許可リスト (allowlist) のサポートが実装され、ログの数もハートビートごとに 1 行に削減されます。

新機能

  • PostgreSQL v14 との互換性 (Alexander Kukushkin)

    Patroni 自体が “pause” モードでない場合は、WAL 再生の一時停止を解除します。プライマリーの max_connections などの特定のパラメーターの変更により、“paused” になる可能性があります。

  • フェイルオーバー論理スロット (Alexander Kukushkin)

    PostgreSQL v11+ で、フェイルオーバー/スイッチオーバーをまたいで論理レプリケーション スロットを存続させます。 レプリケーション スロットは、再起動によってプライマリーからレプリカにコピーされ、その後、pg_replication_slot_advance() 関数を使用して前に移動されます。その結果、スロットはフェイルオーバー前にすでに存在しており、イベントは失われないはずですが、一部のイベントが複数回配信される可能性があります。

  • Patroni REST API の許可リストを実装しました (Alexander Kukushkin)

    構成されている場合、ルールに一致する IP のみが安全でないエンドポイントの呼び出しを許可されます。それに加えて、クラスターのメンバーの IP をリストに自動的に含めることもできます。

  • UNIX ソケット経由のレプリケーション接続のサポートを追加しました (Mohamad El-Rifai)

    以前は、Patroni はレプリケーション接続に常に TCP を使用していたため、SSL 検証で問題が発生する可能性がありました。 UNIX ソケットを使用すると、レプリケーション ユーザーを SSL 検証から免除できます。

  • ユーザー定義タグのヘルスチェック (Arman Jafari Tehrani)

    事前定義されたタグ: とともに、patronictl list 出力および REST API に表示されるカスタム タグをいくつでも指定できます。今後、ヘルスチェックでカスタムタグを使用できるようになります。

  • Prometheus /metrics エンドポイントを追加しました (Mark Mercado、Michael Banck)

    /patroni と同じメトリクスを公開するエンドポイント。

  • Patroni ログのおしゃべり性を軽減しました (Alexander Kukushkin)

    すべてが正常に進むと、HA ループの実行ごとに 1 行だけが書き込まれます。

後方互換性のない変更

  • 古い permanent logical replication slots 機能は、PostgreSQL v10 以前では動作しなくなります。 (Alexander Kukushkin)

    プロモーションの実行後に論理スロットを作成する戦略では、論理イベントが失われないことを保証できないため、無効化されました。

  • ノードがロックを保持している場合、/leader エンドポイントは常に 200 を返します (Alexander Kukushkin)

    スタンバイ クラスターを昇格するには、ロード バランサーのヘルス チェックを更新する必要がありますが、これはあまり便利ではなく、忘れがちです。これを解決するために、/leader ヘルス チェック エンドポイントの動作を変更します。通常のクラスターであるか standby_cluster であるかを考慮せずに、200 を返します。

Raft サポートの改善

  • Raft トラフィック暗号化の信頼できるサポート (Alexander Kukushkin)

    PySyncObj のさまざまな問題により、暗号化サポートは非常に不安定でした

  • Raft 実装における DNS の問題を処理します (Alexander Kukushkin)

    self_addr および/または partner_addrs が IP の代わりに DNS 名を使用して構成されている場合、PySyncObj はオブジェクトの作成時に 1 回だけ効果的に解決を実行していました。同じノードが別の IP でオンラインに戻ると問題が発生していました。

安定性の向上

  • psycopg2-2.9+ との互換性 (Alexander Kukushkin)

    psycopg2 では、autocommit = True は with connection ブロックで無視され、レプリケーション プロトコル接続が切断されます。

  • Zookeeper で実行される過剰な HA ループを修正しました。 (Alexander Kukushkin)

    メンバー ZNodes の更新により連鎖反応が発生し、HA ループが連続して複数回実行されることになりました。

  • REST API 証明書がディスク上で変更された場合、リロードします (Michael Todorovic)

    REST API 証明書ファイルがその場で (in place) 更新された場合、Patroni はリロードを実行していませんでした。

  • kerberos 認証が使用されている場合は pgpass ディレクトリを作成しないでください。 (Kostiantyn Nemchenko)

    Kerberos とパスワード認証は相互に排他的です。

  • カスタム ブートストラップに関する小さな問題を修正しました (Alexander Kukushkin)

    PITR を実行する場合にのみ Postgres を hot_standby=off で開始し、PITR が完了した後に再起動します。

バグ修正

  • kazoo-2.7+ との互換性 (Alexander Kukushkin)

    Patroni は独自に再試行を処理するため、使用可能な接続がない場合は Zookeeper クラスターへのリクエストが直ちに破棄されるという kazoo の古い動作に依存しています。

  • プロキシ経由で接続していることがわかっている場合、etcd v3 クラスターのバージョンを明示的に要求します。 (Alexander Kukushkin)

    Patroni は、gRPC-gateway 経由で etcd v3 クラスターと連携しており、クラスターのバージョンに応じて、異なるエンドポイント (/v3、/v3beta、または /v3alpha) を使用する必要があります。このバージョンはクラスター トポロジと一緒にのみ解決されましたが、プロキシ経由で接続する場合は後者が実行されなかったためです。

バージョン 2.0.2

2021-02-22 リリース

新機能

  • 外部管理のレプリケーション スロットを無視する機能 (James Coleman)

    Patroni は、未知のレプリケーション スロットを削除しようとしていますが、レプリケーション スロットを外部で管理する必要がある場合は確かにあります。今後は、削除してはならないスロットを設定できるようになります。

  • REST API の暗号スイート制限のサポートを追加しました (Gunnar “Nick” Bluth)

    これは、restapi.ciphers または PATRONI_RESTAPI_CIPHERS 環境変数を介して構成できます。

  • REST API の暗号化された TLS キーのサポートを追加しました (Jonathan S. Katz)

    これは、restapi.keyfile_password または PATRONI_RESTAPI_KEYFILE_PASSWORD 環境変数を介して構成できます。

  • REST API 認証資格情報の定数時間比較 (Alex Brasetvik)

    タイミング攻撃に対して脆弱な == の代わりに hmac.compare_digest() を使用してください。

  • レプリケーション ラグに基づいて同期ノードを選択する (Krishna Sarabu)

    同期ノード上のレプリケーション ラグが設定されたしきい値を超え始めた場合、そのノードは非同期に降格されるか、他のノードに置き換えられるか、あるいはその両方になる可能性があります。動作は maximum_lag_on_syncnode で制御されます。

安定性の向上

  • カスタム ブートストラップを実行するときに hot_standby = off で postgres を開始します (Igor Yanchenko)

    カスタム ブートストラップ中、Patroni はベースバックアップを復元し、Postgres を起動して、リカバリが完了するまで待機します。スタンバイ上の一部の PostgreSQL パラメーターはプライマリーよりも小さくすることができず、新しい値 (WAL から復元された) が構成された値より大きい場合、Postgres はパニックを起こして停止します。このような動作を回避するために、hot_standby モードを使用せずにカスタム ブートストラップを実行します。

  • 必要なウォッチドッグが正常でない場合にユーザーに警告します。 (Nicolas Thauvin)

    required モードでウォッチドッグ デバイスに書き込めないか、デバイスが存在しない場合、メンバーを昇格することはできません。この構成ミスを検索する場所をユーザーに示す警告を追加しました。

  • シングルユーザー モードのリカバリのログ出力を詳しくする (Alexander Kukushkin)

    Patroni が PostgreSQL が正常にシャットダウンされていないことに気付いた場合、場合によっては、Postgres をシングル ユーザー モードで起動することによってクラッシュ リカバリが実行されます。 (ディスク上のスペース不足などにより) リカバリが失敗しても、エラーが飲み込まれる可能性があります。

  • python-consul2 モジュールとの互換性を追加しました (Alexander Kukushkin、Wilfried Roset)

    古き良き python-consul は数年前からメンテナンスされていないため、誰かが新機能とバグ修正を備えたフォークを作成しました。

  • patronictl を実行する場合は bypass_api_service を使用しないでください。 (Alexander Kukushkin)

    K8s ポッドが非 default 名前空間で実行されている場合、Kubernetes エンドポイントをクエリーするための十分な権限があるとは限りません。この場合、Patroni は警告を表示し、bypass_api_service 設定を無視します。 patronictl の場合、警告は少し面倒でした。

  • raft.data_dir が存在しない場合は作成するか、書き込み可能であることを確認してください (Mark Mercado)

    ユーザーフレンドリー性と使いやすさが向上します。

バグ修正

  • 一時停止中にリーダーのロックが失われた場合、再起動またはプロモートを中断しないでください。 (Alexander Kukushkin)

    一時停止中は、ロックなしで postgres をプライマリーとして実行できます。

  • REST API の shutdown_request() に関する問題を修正しました (Nicolas Limage)

    SSL 接続の処理を改善し、スレッドが開始されるまでハンドシェイクを遅らせるために、Patroni は HTTPServer のいくつかのメソッドをオーバーライドします。 shutdown_request() メソッドが忘れられていました。

  • Zookeeper使用時のスリープ時間の問題を修正しました。 (Alexander Kukushkin)

    HA コードの実行の間に、Patroni が最大 2 倍長くスリープしている可能性がありました。

  • ブートストラップの失敗後にデータ ディレクトリを移動するときの無効な os.symlink() 呼び出しを修正しました。 (Andrew L’Ecuyer)

    ブートストラップが失敗した場合、Patroni はデータ ディレクトリ、pg_wal、およびすべてのテーブルスペースの名前を変更します。その後、シンボリックリンクを更新して、ファイルシステムの一貫性を保ちます。 src 引数と dst 引数が交換されているため、シンボリックリンクの作成は失敗していました。

  • post_bootstrap() メソッドのバグを修正しました (Alexander Kukushkin)

    スーパーユーザーのパスワードが構成されていない場合、Patroni は post_init スクリプトの呼び出しに失敗し、そのためブートストラップ全体が失敗していました。

  • スタンバイ クラスターの pg_rewind に関する問題を修正しました (Alexander Kukushkin)

    スーパーユーザー名が postgres と異なる場合は、接続文字列にデータベース名が含まれていないため、スタンバイ クラスターの pg_rewind が失敗していました。

  • Etcd v3 による認証が明示的に失敗した場合のみ終了します。 (Alexander Kukushkin)

    起動時に Patroni は etcd クラスター トポロジの検出を実行し、必要に応じて認証を行います。 etcd サーバーの 1 つがアクセスできず、Patroni がこのサーバーで認証を実行しようとして、次のノードで再試行せずに失敗することが考えられます。

  • psutil cmdline() が空のリストを返す場合の処理 (Alexander Kukushkin)

    ゾンビプロセスは依然としてポストマスターの子ですが、cmdline() を持っていません。

  • PATRONI_KUBERNETES_USE_ENDPOINTS 環境変数をブール値として扱います。 (Alexander Kukushkin)

    そうしないと、環境経由で kubernetes.use_endpoints を無効にすることができなくなりました。

  • 同時エンドポイント更新エラーの処理を改善しました (Alexander Kukushkin)

    Patroni は現在のエンドポイント オブジェクトを明示的にクエリーし、現在のポッドがまだリーダー ロックを保持していることを確認して、更新を繰り返します。

バージョン 2.0.1

2020-10-01 リリース

新機能

  • less が利用できない場合、patronictl edit-config のページャーとして more を使用する (Pavel Golub)

    Windows では、more.com になります。それに加えて、requirements.txt では cdiff が ydiff に変更されましたが、patronictl は互換性のために両方をサポートしています。

  • raft bind_addr および password のサポートを追加しました (Alexander Kukushkin)

    raft.bind_addr は、NAT の背後で実行する場合に便利です。 raft.password はトラフィック暗号化を有効にします (cryptography モジュールが必要です)。

  • sslpassword 接続パラメータのサポートを追加しました (Kostiantyn Nemchenko)

    接続パラメーターは PostgreSQL 13 で導入されました。

安定性の向上

  • 一時停止時の動作を変更しました (Alexander Kukushkin)

    1. PGDATA ディレクトリが見つからない、または空の場合、Patroni は bootstrap メソッドを呼び出しません。
    2. Patroni は、一時停止中に sysid が一致しない場合には終了せず、警告をログに記録するだけです。
    3. Postgres がリカバリ中ではなく実行されている (書き込みを受け入れている) が、sysid が初期化キーと一致しない場合、ノードは一時停止モードでリーダー キーを取得しようとしません。

  • クラッシュ リカバリの実行時に master_start_timeout を適用します (Alexander Kukushkin)

    Postgres がリーダー ノードでクラッシュした場合、Patroni はシングル ユーザー モードで Postgres を起動することによってクラッシュ リカバリを実行します。クラッシュリカバリ中に、リーダーのロックが更新されます。クラッシュ リカバリが master_start_timeout 秒以内に終了しなかった場合、Patroni はクラッシュ リカバリを強制的に停止し、リーダー ロックを解放します。

  • urllib3 要件から secure エクストラを削除しました (Alexander Kukushkin)

    これを追加した唯一の理由は、Python 2.7 の ipaddress 依存関係でした。

バグ修正

  • Kubernetes.update_leader() のバグを修正しました。 (Alexander Kukushkin)

    リーダー オブジェクトの更新が失敗した場合、未処理の例外によりプライマリーの降格が妨げられていました。

  • RAFT 使用時のハングする patronictl を修正しました。 (Alexander Kukushkin)

    Patroni 構成で patronictl を使用する場合、self_addr を partner_addrs に追加すべきです。

  • get_guc_value() のバグを修正しました (Alexander Kukushkin)

    Patroni は、PostgreSQL 12 の restore_command の値の取得に失敗していたため、pg_rewind の欠落している WAL を取得できませんでした。

バージョン 2.0.0

2020-09-02 リリース

このバージョンでは、PostgreSQL 13 との互換性が強化され、複数の同期スタンバイのサポートが追加され、pg_rewind の処理が大幅に改善され、Etcd v3 のサポートと、純粋な RAFT (etcd、Consul、Zookeeper なし) 上の Patroni のサポートが追加され、オプションで pre_promote (フェンシング) スクリプトを呼び出すことが可能になります。

PostgreSQL 13 のサポート

  • PostgreSQL 13+ で standby_leader に昇格するときに on_reload を起動しないでください。 (Alexander Kukushkin)

    standby_leader に昇格する場合、primary_conninfo を変更し、ロールを更新して、Postgres をリロードします。 on_role_change と on_reload は実質的に相互に重複するため、Patroni は on_role_change のみを呼び出します。

  • gssencmode および channel_binding 接続パラメータのサポートを追加しました。 (Alexander Kukushkin)

    PostgreSQL 12 では gssencmode が、PostgreSQL 13 では channel_binding 接続パラメーターが導入され、postgresql.authentication セクションで定義されている場合はそれらを使用できるようになりました。

  • wal_keep_segments から wal_keep_size への名前変更を処理 (Alexander Kukushkin)

    構成に誤りがある場合 (13 では wal_keep_segments、古いバージョンでは wal_keep_size)、Patroni が自動的に構成を調整します。

  • 可能であれば、13 で pg_rewind を --restore-target-wal とともに使用してください (Alexander Kukushkin)

    PostgreSQL 13 では、Patroni が restore_command が構成されているかどうかを確認し、pg_rewind にそれを使用するように指示します。

新機能

  • BETABETA

    純粋な RAFT に Patroni のサポートを実装しました。 (Alexander Kukushkin)

    これにより、etcd、Consul、Zookeeper などのサードパーティの依存関係なしで Patroni を実行できるようになります。 HA の場合は、3 つの Patroni ノード、または Patroni を含む 2 つのノードと patroni_raft_controller を含む 1 つのノードを実行する必要があります。詳細については、ドキュメント を確認してください。

  • BETABETA

    gRPC ゲートウェイ経由で etcd v3 プロトコルのサポートを実装しました (Alexander Kukushkin)

    etcd 3.0 は 4 年以上前にリリースされており、etcd 3.4 では v2 がデフォルトで無効になっています。 v2 が etcd から完全に削除される可能性もあるため、etcd v3 のサポートを Patroni に実装しました。これを使用するには、Patroni 構成ファイルに etcd3 セクションを明示的に作成する必要があります。

  • 複数の同期スタンバイのサポート (Krishna Sarabu)

    これにより、複数の同期レプリカを含むクラスターを実行できます。同期レプリカの最大数は、新しいパラメータ synchronous_node_count によって制御されます。デフォルトでは 1 に設定されており、synchronous_mode が off に設定されている場合は効果がありません。

  • pre_promote スクリプトを呼び出す可能性を追加しました (Sergey Dudoladov)

    コールバックとは異なり、pre_promote スクリプトは、リーダー ロックを取得した後、Postgres をプロモートする前に同期的に呼び出されます。スクリプトが失敗するか、ゼロ以外の終了コードで終了すると、現在のノードはリーダー ロックを解放します。

  • 構成ディレクトリのサポートを追加しました (Floris van Nee)

    ディレクトリ内の YAML ファイルがアルファベット順にロードされ、適用されます。

  • PostgreSQL パラメータの高度な検証 (Alexander Kukushkin)

    特定のパラメーターが現在の PostgreSQL バージョンでサポートされていない場合、またはその値が正しくない場合、Patroni はパラメーターを完全に削除するか、値の修正を試みます。

  • プロモート後の強制チェックポイントが完了したらメインスレッドを起こします。 (Alexander Kukushkin)

    レプリカは、DCS のリーダーのメンバー キーを介してチェックポイントの指示を待っています。通常、キーは HA ループごとに 1 回だけ更新されます。メインスレッドを起こさないと、レプリカは必要以上に最大 loop_wait 秒長く待機する必要があります。

  • 9.6+ での pg_stat_wal_receiver ビューの使用 (Alexander Kukushkin)

    ビューには primary_conninfo と primary_slot_name の最新の値が含まれていますが、recovery.conf の内容は古い可能性があります。

  • Patroni 設定ファイルでの IPv6 アドレスの処理を改善しました (Mateusz Kowalski)

    IPv6 アドレスは角括弧で囲む必要がありますが、Patroni はプレーンなアドレスを取得することを期待していました。現在は両方の形式がサポートされています。

  • Consul service_tags 設定パラメータを追加しました (Robert Edström)

    これらは、ロード バランサーなどによる動的なサービス検出に役立ちます。

  • Zookeeper の SSL サポートを実装しました (Kostiantyn Nemchenko)

    kazoo>=2.6.0 が必要です。

  • カスタム ブートストラップ メソッドの no_params オプションを実装しました (Kostiantyn Nemchenko)

    これにより、wal-g、pgBackRest、およびその他のバックアップ ツールをシェル スクリプトにラップせずに呼び出すことができます。

  • 初期化に失敗した後に WAL とテーブルスペースを移動します (Feike Steenbergen)

    reinit を実行すると、Patroni は PGDATA だけでなく、シンボリックリンクされた WAL ディレクトリとテーブルスペースもすでに削除していました。 move_data_directory() メソッドは同様のジョブを実行します。つまり、WAL ディレクトリとテーブルスペースの名前を変更し、PGDATA 内のシンボリックリンクを更新します。

pg_rewind サポートの改善

  • タイムラインの発散チェックの改善 (Alexander Kukushkin)

    レプリカ上の再生位置がスイッチポイントを超えていない場合、または元のプライマリー上のチェックポイント レコードの終わりがスイッチポイントと同じである場合は、巻き戻す必要はありません。チェックポイント レコードの終わりを取得するために、pg_waldump を使用し、その出力を解析します。

  • pg_rewind がそれについて文句を言ったら、欠落している WAL を取得してみます。 (Alexander Kukushkin)

    pg_rewind に必要な WAL セグメントが pg_wal ディレクトリに存在しないため、pg_rewind が分岐点より前のチェックポイントの場所を見つけることができない場合があります。 PostgreSQL 13 pg_rewind からは、欠落している WAL を取得するために restore_command を使用できるようになりました。古い PostgreSQL バージョンの場合、Patroni は、失敗した巻き戻し試行のエラーを解析し、restore_command を独自に呼び出して、不足している WAL を取得しようとします。

  • スタンバイ クラスターで新しいタイムラインを検出し、必要に応じて巻き戻し/再初期化をトリガーします (Alexander Kukushkin)

    standby_cluster はプライマリー クラスターから切り離されているため、リーダーの選出やタイムラインの切り替えについてはすぐには認識されません。この事実を検出するために、standby_leader は pg_wal 内の新しい履歴ファイルを定期的にチェックします。

  • 履歴ログ出力を短縮して美しくしました (Alexander Kukushkin)

    Patroni が pg_rewind の必要性を判断しようとすると、プライマリーからの履歴ファイルの内容がログに書き込まれる可能性があります。履歴ファイルはフェイルオーバー/スイッチオーバーのたびに増大し、最終的には多くの行を占めるようになり、そのほとんどはあまり役に立ちません。 Patroni は、生データを表示する代わりに、現在のレプリカ タイムラインより前の 3 行とその後の 2 行のみを表示します。

K8s の改善

  • Kubernetes Python モジュールを削除します (Alexander Kukushkin)

    公式の Python Kubernetes クライアントには自動生成されたコードが多数含まれているため、非常に重くなっています。 Patroni は、K8s の API エンドポイントのほんの一部のみを使用しており、それらのサポートの実装は難しくありませんでした。

  • Kubernetes サービスをバイパスできるようにしました。 (Alexander Kukushkin)

    K8s で実行している場合、Patroni は通常、Kubernetes サービスを介して K8s API と通信します。そのアドレスは KUBERNETES_SERVICE_HOST 環境変数で公開されます。他のサービスと同様に、Kubernetes サービスは kube-proxy によって処理され、構成に応じてトラフィック ルーティングをユーザー空間プログラムまたは iptables に依存します。中間コンポーネントをスキップして K8s マスター ノードに直接接続すると、より適切な再試行戦略を実装でき、K8s マスター ノードがアップグレードされるときに Postgres を降格するリスクを軽減できます。

  • Patroni クラスターのすべてのポッドの HA ループを同期 (Alexander Kukushkin)

    そうしないと、障害検出時間が ttl から ttl + loop_wait に増加しました。

  • K8s のサブセット アドレスに references と nodename を設定する (Alexander Kukushkin)

    一部のロードバランサーはこの情報に依存しています。

  • update_leader() で発生する可能性のある競合状態を修正しました。 (Alexander Kukushkin)

    Patroni の外部でリーダー ConfigMapまたはエンドポイントの同時更新が行われると、update_leader() 呼び出しが失敗する可能性があります。この場合、Patroni は現在のノードがまだリーダー ロックを所有していることを再確認し、更新を繰り返します。

  • 存在しない構成へのパッチ適用を明示的に禁止します (Alexander Kukushkin)

    Kubernetes 以外の DCS では、cluster.config が None であるため、PATCH 呼び出しは例外で失敗しますが、Kubernetes では構成アノテーションが問題なく作成され、ブートストラップ終了後にブートストラップ構成を書き込むことができませんでした。

  • 一時停止する のバグを修正しました (Alexander Kukushkin)

    リーダー キーが存在しない場合、レプリカは primary_conninfo を削除し、Postgres を再起動していましたが、何も行わないはずです。

REST API の改善

  • ワーカー スレッドが開始されるまで TLS ハンドシェイクを延期します。 (Alexander Kukushkin、Ben Harris)

    TLS ハンドシェイクが API スレッドで実行され、クライアント側がデータを送信しなかった場合、API スレッドはブロックされました (DoS の危険があります)。

  • REST API で basic-auth をクライアント証明書とは独立してチェックする (Alexander Kukushkin)

    以前は、クライアント証明書のみが検証されていました。 2 つのチェックを独立して実行することは、完全に有効な使用例です。

  • OPTIONS リクエストの HTTP ヘッダーの後に CRLF を二重に書き込みます (Sergey Burladyan)

    HAProxy は 1 つの CRLF に満足していましたが、Consul ヘルスチェックでは接続の切断と予期しない EOF が発生したと報告されました。

  • GET /cluster で Zookeeper の古いメンバー情報が表示されていました (Alexander Kukushkin)

    エンドポイントは Patroni 内部クラスター ビューを使用していました。 Patroni 自体については問題は発生しませんでしたが、外部に公開する場合は、最新の情報、特にレプリケーション ラグを表示する必要があります。

  • スタンバイ クラスターのヘルスチェックを修正しました (Alexander Kukushkin)

    マスターの GET /standby-leader と standby_leader の GET /master が、誤って 200 で応答していました。

  • DELETE /switchover を実装 (Alexander Kukushkin)

    REST API 呼び出しは、スケジュールされたスイッチオーバーを削除します。

  • /readiness および /liveness エンドポイントを作成しました (Alexander Kukushkin)

    これらは、K8s サービスがラベル セレクターとともに使用されている場合に、サブセット アドレスから “unhealthy” ポッドを削除するのに役立つ可能性があります。

  • 強化された GET /replica および GET /async REST API ヘルスチェック (Krishna Sarabu、Alexander Kukushkin)

    チェックはオプションのキーワード ?lag=<max-lag> をサポートし、ラグが指定された値より小さい場合にのみ 200 で応答するようになりました。この機能を利用する場合、リーダー上の WAL 位置に関する情報は loop_wait 秒ごとにのみ更新されることに注意してください。

  • REST API 応答にユーザー定義の HTTP ヘッダーのサポートを追加しました (Yogesh Sharma)

    この機能は、リクエストがブラウザから行われる場合に役立つ可能性があります。

patronictl の改善

  • patronictl pause に存在しないリーダーを呼び出そうとしないでください (Alexander Kukushkin)

    K8s でリーダーのないクラスターを一時停止しているときに、patronictl はメンバー「None」にアクセスできないという警告を表示していました。

  • メンバー conn_url が欠落している場合の処理 (Alexander Kukushkin)

    K8s では、Patroni がまだ実行されていないため、ポッドに必要なアノテーションがない可能性があります。 patronictl が失敗していました。

  • ASCII クラスター トポロジを表示する機能を追加しました (Maxim Fedotov、Alexander Kukushkin)

    カスケード レプリケーションを使用してクラスターの概要を把握するのに非常に役立ちます。

  • patronictl flush switchover の実装 (Alexander Kukushkin)

    それ以前は、patronictl flush はスケジュールされた再起動のキャンセルのみをサポートしていました。

バグ修正

  • 既存の PGDATA を使用したクラスターのブートストラップ中に Attribute エラーが発生しました (Krishna Sarabu)

    /history キーを作成/更新しようとすると、Patroni は DCS でまだ作成されていない ClusterConfig オブジェクトにアクセスしていました。

  • Consul の例外処理を改善しました。 (Alexander Kukushkin)

    touch_member() メソッドの未処理の例外により、Patroni プロセス全体がクラッシュしました。

  • post_init スクリプトに対して synchronous_commit=local を強制します (Alexander Kukushkin)

    Patroni はユーザー (replication、rewind) を作成するときにすでにそれを行っていましたが、post_init の場合にそれが欠けていたのは見落としでした。その結果、スクリプトが内部で独自に実行していない場合、synchronous_mode のブートストラップを完了できませんでした。

  • Consul プール マネージャーの maxsize を増加しました (ponvenkates)

    デフォルトの size=1 では、いくつかの警告が生成されました。

  • Patroni は Postgres が実行中であると誤って報告していました (Alexander Kukushkin)

    たとえば、ディスク不足エラーにより Postgres がクラッシュした場合、状態は更新されませんでした。

  • 欠損値または空の値の代わりに * を pgpass に挿入します。 (Alexander Kukushkin)

    たとえば、standby_cluster.port が指定されていない場合、pgpass ファイルが正しく生成されていませんでした。

  • 特殊文字を使用したリーダー ノードでの物理レプリケーション スロットの作成をスキップします (Krishna Sarabu)

    名前に「-」などの特殊文字が含まれている場合 (“abc-us-1” など)、Patroni はリーダー ノードの休止スロット (slots が定義されている場合) を作成しているように見えました。

  • カスタム ブートストラップで存在しない pg_hba.conf を削除しないようにしました。 (Krishna Sarabu)

    カスタム ブートストラップ後に pg_hba.conf が pgdata ディレクトリの外にある場合、Patroni は失敗していました。

バージョン 1.6.5

2020-08-23 リリース

新機能

  • マスター停止タイムアウト (Krishna Sarabu)

    Postgres を停止するときに Patroni が待機できる秒数。 synchronous_mode が有効な場合にのみ有効です。 0 より大きい値に設定され、synchronous_mode が有効になっている場合、停止操作が master_stop_timeout で設定された値を超えて実行されている場合、Patroni はポストマスターに SIGKILL を送信します。永続性と可用性のトレードオフに応じて値を設定します。パラメーターが設定されていないか、正以外の値に設定されている場合、master_stop_timeout は効果がありません。

  • プライマリーの名前で永続的な物理スロットを作成しないでください。 (Alexander Kukushkin)

    レプリカが停止している間にプライマリーが WAL セグメントをリサイクルするのは一般的な問題です。これで、ノード数が固定され、名前が決して変更されない、静的クラスターに対する優れたソリューションが得られました。 slots 内のすべてのノードの名前をリストするだけで、ノードがダウンしている (DCS に登録されていない) ときにプライマリーがスロットを削除しないようにすることができます。

  • 構成バリデーターの初版 (Igor Yanchenko)

    Patroni 構成を検証するには、patroni --validate-config patroni.yaml を使用します。

  • タイムライン履歴の最大長を設定できるようになりました (Krishna Sarabu)

    Patroni は、フェイルオーバー/スイッチオーバーの履歴を DCS の /history キーに書き込みます。時間の経過とともにこのキーのサイズは大きくなりますが、ほとんどの場合、重要なのは最後の数行だけです。 max_timelines_history パラメーターを使用すると、DCS に保持されるタイムライン履歴アイテムの最大数を指定できます。

  • Kazoo 2.7.0 の互換性 (Danyal Prout)

    Kazoo の一部の非パブリック メソッドはシグネチャを変更しましたが、Patroni はそれらに依存していました。

patronictl の改善

  • メンバー タグを表示 (Kostiantyn Nemchenko、Alexander Kukushkin)

    タグはノードごとに個別に構成されており、タグの概要を簡単に把握する方法はありませんでした。

  • メンバーの出力を改善しました (Alexander Kukushkin)

    冗長なクラスター名は各行に表示されなくなり、テーブルのヘッダーにのみ表示されます。

$ patronictl list
+ Cluster: batman (6813309862653668387) +---------+----+-----------+---------------------+
|    Member   |      Host      |  Role  |  State  | TL | Lag in MB | Tags                |
+-------------+----------------+--------+---------+----+-----------+---------------------+
| postgresql0 | 127.0.0.1:5432 | Leader | running |  3 |           | clonefrom: true     |
|             |                |        |         |    |           | noloadbalance: true |
|             |                |        |         |    |           | nosync: true        |
+-------------+----------------+--------+---------+----+-----------+---------------------+
| postgresql1 | 127.0.0.1:5433 |        | running |  3 |       0.0 |                     |
+-------------+----------------+--------+---------+----+-----------+---------------------+

  • 設定ファイルが明示的に指定されているが見つからない場合は失敗します (Kaarel Moppel)

    以前は、patronictl は DEBUG メッセージのみを報告していました。

  • 初期化されていない K8s ポッドが patronictl を破壊する問題を解決しました。 (Alexander Kukushkin)

    Patroni は、K8s 上の特定のポッド アノテーションに依存しています。 Patroni ポッドの 1 つが停止または開始しているときは、有効なアノテーションがまだなく、patronictl が例外で失敗していました。

安定性の向上

  • K8s API サーバーへの LIST 呼び出しが失敗した場合、1 秒のバックオフを適用します (Alexander Kukushkin)

    これは主にログの氾濫を避けるために必要ですが、メインスレッドの枯渇を防ぐのにも役立ちます。

  • retry-after HTTP ヘッダーが K8s API によって返された場合に再試行します (Alexander Kukushkin)

    K8s API サーバーがリクエストで圧倒されると、再試行を要求されることがあります。

  • postmaster の環境から KUBERNETES_ 環境変数を削除する (Feike Steenbergen)

    KUBERNETES_ 環境変数は PostgreSQL には必要ありませんが、環境変数をポストマスターに公開すると、バックエンドや通常のデータベース ユーザー (pl/perl などを使用) にも公開されます。

  • 再初期化時にテーブルスペースをクリーンアップします (Krishna Sarabu)

    再初期化中に、Patroni は PGDATA のみを削除し、ユーザー定義のテーブルスペース ディレクトリを残していました。これにより、Patroni が再初期化でループする原因となります。この問題に対する以前の回避策は、カスタムブートストラップ スクリプトを実装することでした。

  • プロモートが行われた後に明示的に CHECKPOINT を実行します。 (Alexander Kukushkin)

    新しいプライマリーが pg_rewind で使用可能になるまでの時間を短縮するのに役立ちます。

  • Etcd メンバーのスマート更新 (Alexander Kukushkin)

    Patroni が etcd クラスターのすべてのメンバーでリクエストの実行に失敗した場合、Patroni は、次回再試行する前に、IP/ホストの変更について A または SRV レコードを再チェックします。

  • pg_controldata から欠損値をスキップします (Feike Steenbergen)

    PGDATA と一致しないバージョンのバイナリを使用しようとすると、値が欠落します。 Patroni はとにかく Postgres を起動しようとしますが、Postgres はメジャー バージョンが一致しないと通知し、エラーで中止されます。

バグ修正

  • 必要に応じて Consul の SSL 検証を無効にします (Julien Riou)

    urllib3 の特定のバージョン以降、SSL 検証を効果的に無効にするには、cert_reqs を明示的に ssl.CERT_NONE に設定する必要があります。

  • HA ループの各サイクルでレプリケーション接続を開かないようにしました。 (Alexander Kukushkin)

    回帰は 1.6.4 で導入されました。

  • 失敗したプライマリーで on_role_change コールバックを呼び出す (Alexander Kukushkin)

    場合によっては、仮想 IP が古いプライマリーに接続されたままになる可能性があります。回帰は 1.4.5 で導入されました。

  • pg_rewind が成功した後に postgres が開始された場合、巻き戻し状態をリセットします。 (Alexander Kukushkin)

    このバグの結果、Patroni は、手動でシャットダウンされた postgres を一時停止モードで起動していました。

  • recovery.conf をチェックするときに recovery_min_apply_delay を ms に変換します

    12 よりも古い PostgreSQL 上で recovery_min_apply_delay が構成されている場合、Patroni はレプリカを無期限に再起動していました。

  • PyInstaller の互換性 (Alexander Kukushkin)

    PyInstaller は、Python アプリケーションをスタンドアロンの実行可能ファイルにフリーズ (パッケージ化) します。 multiprocessing の fork ではなく spawn メソッドに切り替えたときに互換性が失われていました。

バージョン 1.6.4

2020-01-27 リリース

新機能

  • patronictl reinit の --wait オプションを実装しました (Igor Yanchenko)

    --wait オプションが使用されている場合、Patronictl は reinit が完了するまで待機します。

  • Windows サポートのさらなる改善 (Igor Yanchenko、Alexander Kukushkin)

    1. 統合テストに使用されるすべてのシェル スクリプトは Python で書き直されます
    2. pg_ctl kill は、非 posix システムで postgres を停止するために使用されます。
    3. unix ドメイン ソケットを使用しないでください

安定性の向上

  • unix_socket_directories と stats_temp_directory が存在することを確認してください (Igor Yanchenko)

    Patroni および Postgres の開始時に、unix_socket_directories および stats_temp_directory が存在することを確認するか、それらの作成を試行します。 Patroni は、作成に失敗した場合に終了します。

  • Patroni が書き込みアクセスできる場所に postgresql.pgpass が配置されていることを確認してください。 (Igor Yanchenko)

    書き込みアクセスがない場合、Patroni は例外で終了します。

  • Consul serfHealth チェックをデフォルトで無効にします (Kostiantyn Nemchenko)

    ネットワークに小さな問題が発生した場合でも、serfHealth が失敗すると、ノードに関連付けられたすべてのセッションが無効になります。したがって、リーダー キーは ttl よりもはるかに早く失われ、レプリカが不要に再起動され、場合によってはプライマリーが降格されます。

  • K8s API への接続に tcp キープアライブを構成 (Alexander Kukushkin)

    TTL 秒経過してもソケットから何も取得されない場合、ソケットは停止していると見なすことができます。

  • ユーザー作成時のパスワードのログ記録を回避します (Alexander Kukushkin)

    パスワードが拒否された場合、またはログ記録が冗長に構成されているか、まったく構成されていない場合、パスワードが postgres ログに書き込まれる可能性があります。これを回避するために、Patroni は、ユーザーの作成/更新を試行する前に、log_statement、log_min_duration_statement、および log_min_error_statement を安全な値に変更します。

バグ修正

  • カスケード レプリカで standby_cluster 構成の restore_command を使用します (Alexander Kukushkin)

    standby_leader は、この機能が存在した当初からすでに実行していました。レプリカで同じことを行わないと、スタンバイ リーダーに追いつけなくなる可能性があります。

  • スタンバイ クラスターが報告するタイムラインを更新 (Alexander Kukushkin)

    タイムライン切り替えの場合、スタンバイ クラスターはプライマリーから正しくレプリケートしていましたが、patronictl は古いタイムラインを報告していました。

  • custom_conf で特定の回復パラメータを定義できるようにしました。 (Alexander Kukushkin)

    レプリカでリカバリ パラメータの検証を行うとき、Patroni は、archive_cleanup_command、promote_trigger_file、recovery_end_command、recovery_min_apply_delay、および restore_command が Patroni 構成ではなく、postgresql.auto.conf または postgresql.conf 以外のファイルで定義されている場合、それらをスキップします。

  • 名前にピリオドが含まれる PostgreSQL パラメータの処理を改善しました。 (Alexander Kukushkin)

    このようなパラメーターは、単位が必ずしも文字列であるとは限らない拡張機能によって定義できます。値を変更すると、再起動が必要になる場合があります (pg_stat_statements.max など)。

  • シャットダウン時の例外処理を改善しました (Alexander Kukushkin)

    シャットダウン中、Patroni は DCS 内のステータスを更新しようとします。 DCS にアクセスできない場合は、例外が発生する可能性があります。例外処理が不足しているため、ロガー スレッドが停止できませんでした。

バージョン 1.6.3

2019-12-05 リリース

バグ修正

  • pg_rewind の実行時にパスワードを公開しないでください (Alexander Kukushkin)

    #1301 でバグが導入されました

  • postgresql.authentication で指定された接続パラメーターを pg_basebackup とカスタム レプリカ作成メソッドに適用 (Alexander Kukushkin)

    URL のような接続文字列に依存していたため、パラメーターは適用されませんでした。

バージョン 1.6.2

2019-12-05 リリース

新機能

  • patroni --version を実装 (Igor Yanchenko)

    Patroni の現在のバージョンを出力して終了します。

  • すべての http リクエストに user-agent http ヘッダーを設定します (Alexander Kukushkin)

    Patroni は、http プロトコルを介して Consul、etcd、および Kubernetes API と通信しています。特別に作成された user-agent (例: Patroni/1.6.2 Python/3.6.8 Linux) を使用すると、デバッグや監視に役立つ場合があります。

  • 例外トレースバックのログレベルを設定できるようにしました。 (Igor Yanchenko)

    log.traceback_level=DEBUG を設定すると、トレースバックは log.level=DEBUG の場合にのみ表示されます。デフォルトの動作は変わりません。

安定性の向上

  • 構成ファイルで必要なモジュールを検索するときに、すべての DCS モジュールをインポートしないようにしました。 (Alexander Kukushkin)

    たとえば、Zookeeper だけが必要な場合は、etcd、Consul、および Kubernetes のモジュールをインポートする必要はありません。これはメモリ使用量を削減し、INFO メッセージ Failed to import smth の問題を解決します。

  • Python requests モジュールを明示的な要件から削除しました (Alexander Kukushkin)

    これは重要な処理には使用されていませんでしたが、urllib3 の新しいバージョンがリリースされると多くの問題を引き起こしていました。

  • YAML 配列ではなくコンマ区切り文字列として記述された etcd.hosts の処理を改善しました。 (Igor Yanchenko)

    以前は、host1:port1, host2:port2 (カンマの後のスペース文字) 形式で記述すると失敗していました。

ユーザビリティの向上

  • patronictl の空のリストからメンバーを選択することをユーザーに強制しないでください (Igor Yanchenko)

    ユーザーが間違ったクラスター名を指定した場合、空のリストからメンバーを選択するように求めるのではなく、例外が発生します。

  • REST API がバインドできない場合のエラー メッセージをさらにわかりやすくしました。 (Igor Yanchenko)

    経験の浅いユーザーにとって、Python スタックトレースから何が問題なのかを特定するのは難しいかもしれません。

バグ修正

  • wal_buffers の計算を修正しました (Alexander Kukushkin)

    基本単位が 8 kB ブロックから PostgreSQL 11 のバイトに変更されました。

  • PostgreSQL 10+ でのみ primary_conninfo の passfile を使用する (Alexander Kukushkin)

    最新バージョンの libpq がインストールされていない限り、古いバージョンでは passfile が動作する保証はありません。

バージョン 1.6.1

2019-11-15 リリース

新機能

  • PATRONICTL_CONFIG_FILE 環境変数を追加しました (msvechla)

    これにより、環境から patronictl の --config-file 引数を構成できるようになります。

  • patronictl history の実装 (Alexander Kukushkin)

    フェイルオーバー/スイッチオーバーの履歴が表示されます。

  • pg_rewind を実行するときに PGOPTIONS で -c statement_timeout=0 を渡します (Alexander Kukushkin)

    これは、サーバー上の statement_timeout が小さな値に設定され、pg_rewind によって実行されたステートメントの 1 つがキャンセルされた場合から保護します。

  • PostgreSQL 構成でより低い値を許可する (Soulou)

    Patroni では、一部の PostgreSQL 構成パラメーターをハードコードされた値よりも小さく設定することができませんでした。許容される最小値が小さくなり、デフォルト値は変更されていません。

  • 証明書ベースの認証を許可する (Jonathan S. Katz)

    この機能により、スーパーユーザー、レプリケーション、リワインド アカウントの証明書ベースの認証が有効になり、ユーザーは接続する sslmode を指定できるようになります。

  • パスワードの代わりに primary_conninfo の passfile を使用します (Alexander Kukushkin)

    postgresql.conf に対する 600 権限の設定を回避できます。

  • 構成の変更に関係なく pg_ctl reload を実行します (Alexander Kukushkin)

    一部の構成ファイルが Patroni によって制御されていない可能性があります。誰かが REST API を介して、または SIGHUP を Patroni プロセスに送信することによってリロードを実行している場合、通常は Postgres もリロードされることが期待されます。以前は、Patroni 構成の postgresql セクションに変更がなかった場合、Postgres はリロードされませんでした。

  • primary_conninfo だけでなく、すべての回復パラメーターを比較します (Alexander Kukushkin)

    以前は、check_recovery_conf() メソッドは primary_conninfo が変更されたかどうかのみをチェックしており、他のすべての回復パラメーターは考慮されていませんでした。

  • 再起動せずにいくつかの回復パラメーターを適用できるようにしました (Alexander Kukushkin)

    PostgreSQL 12 以降、archive_cleanup_command、promote_trigger_file、recovery_end_command、および recovery_min_apply_delay のリカバリ パラメーターは再起動せずに変更できます。将来の Postgres リリースでは、このリストが拡張され、Patroni が自動的にサポートする予定です。

  • use_slots をオンラインで変更できるようにします (Alexander Kukushkin)

    以前は、Patroni を再起動し、スロットを手動で削除する必要がありました。

  • Postgres の起動時に、PATRONI_ 接頭辞が付いた環境変数のみを削除します (Cody Coons)

    これにより、さまざまな外部データ ラッパーの実行に関する多くの問題が解決されます。

安定性の向上

  • K8s API を使用する場合は LIST + WATCH を使用する (Alexander Kukushkin)

    これにより、オブジェクトの変更 (ポッド、エンドポイント/構成マップ) を効率的に受信できるようになり、K8s マスター ノードのストレスが軽減されます。

  • ブートストラップ中に PGDATA が空でない場合のワークフローを改善しました。 (Alexander Kukushkin)

    initdb ソース コードによると、lost+found と .dotfiles のみが存在する場合、PGDATA は空であると見なされる可能性があります。 Patroni も同じことを行います。 PGDATA が空ではなく、同時に pg_controldata の観点から無効な場合、Patroni はエラーを出して終了します。

  • すべての HA ループで高価な os.listdir() を呼び出すのを避けてください。 (Alexander Kukushkin)

    システムが IO ストレスにさらされている場合、os.listdir() の実行に数秒 (または数分) かかる可能性があり、Patroni の HA ループに悪影響を及ぼします。これにより、更新がないためにリーダー キーが DCS から消える可能性もあります。 PGDATA が空でないことを確認する、より優れた、より安価な方法があります。ここで、PGDATA に global/pg_control ファイルが存在するかどうかを確認します。

  • ロギングインフラストラクチャのいくつかの改善 (Alexander Kukushkin)

    以前は、ログ スレッドが daemon スレッドであったため、シャットダウン時に最後の数行のログが失われる可能性がありました。

  • Python 3.4+ で spawn マルチプロセッシング開始メソッドを使用する (Maciej Kowalczyk)

    Python の 問題 では、スレッド化とマルチプロセッシングがうまく組み合わせられないことが知られています。デフォルトのメソッド fork から spawn に切り替えることが推奨される回避策です。そうしないと、Postgres が実際には稼働しているにもかかわらず、ポストマスターの開始プロセスがハングし、Patroni が無期限に INFO: restarting after failure in progress を報告する可能性があります。

REST API の改善

  • REST API でクライアント証明書を確認できるようにしました (Alexander Kukushkin)

    verify_client が required に設定されている場合、Patroni はすべての REST API 呼び出しのクライアント証明書をチェックします。 optional に設定すると、すべての安全でない REST API エンドポイントに対してクライアント証明書がチェックされます。

  • Postgres が実行されていない場合、GET /replica ヘルス チェック リクエストの応答コード 503 を返します。 (Alexander Anikin)

    Postgres は、クライアント接続の受け入れを開始するまでの回復にかなりの時間を費やす可能性があります。

  • /history および /cluster エンドポイントを実装する (Alexander Kukushkin)

    /history エンドポイントは、DCS の history キーの内容を表示します。 /cluster エンドポイントには、すべてのクラスター メンバーと、保留中およびスケジュールされた再起動やスイッチオーバーなどのサービス情報が表示されます。

etcd サポートの改善

  • Etcd RAFT 内部エラー時に再試行 (Alexander Kukushkin)

    etcd ノードがシャットダウンされると、response code=300, data='etcdserver: server stopped' が送信されます。これにより、Patroni がプライマリーを降格させていました。

  • Etcd リクエストの再試行を早すぎて諦めないでください (Alexander Kukushkin)

    ネットワークに問題が発生すると、Patroni はすぐに etcd ノードのリストを使い果たし、retry_timeout 全体を使用せずに諦めてしまい、プライマリーが降格される可能性がありました。

バグ修正

  • pg_rewind ユーザーに実行権限を付与するときに synchronous_commit を無効にする (kremius)

    ブートストラップが synchronous_mode_strict: true で行われる場合、使用可能な同期スタンバイ ノードがないため、GRANT EXECUTE ステートメントは無期限に待機していました。

  • Python 3.7 のメモリ リークを修正 (Alexander Kukushkin)

    Patroni は ThreadingMixIn を使用して REST API リクエストを処理しており、Python 3.7 では、リクエストごとに生成されるスレッドがデフォルトで非デーモンになりました。

  • 非同期アクションの競合状態を修正しました (Alexander Kukushkin)

    停止した Postgres を回復しようとすると、patronictl reinit --force が上書きされる可能性がありました。これにより、basebackup の実行中に Patroni が Postgres を開始しようとしたという状況が発生しました。

  • postmaster_start_time() メソッドの競合状態を修正しました (Alexander Kukushkin)

    メソッドが REST API スレッドから実行される場合は、別のカーソル オブジェクトを作成する必要があります。

  • 名前に大文字が含まれている同期スタンバイが昇格されない問題を修正しました。 (Alexander Kukushkin)

    Postgres が application_name と synchronous_standby_names の値を比較するときに同じことを行っていたため、名前を小文字に変換しました。

  • 新しいプロセスを開始する前に、コールバックプロセスとともにすべての子を強制終了します。 (Alexander Kukushkin)

    そうしないと、bash でコールバックを実装することが難しくなり、最終的に 2 つのコールバックが同時に実行される状況が発生する可能性があります。

  • 「start failed」問題を修正しました (Alexander Kukushkin)

    特定の条件下では、Postgres が稼働しているにもかかわらず、Postgres 状態が「start failed」に設定されることがあります。

バージョン 1.6.0

2019-08-05 リリース

このバージョンでは、PostgreSQL 12 との互換性が追加され、PostgreSQL 11 以降でスーパーユーザーなしで pg_rewind を実行できるようになり、IPv6 サポートが有効になります。

新機能

  • Psycopg2 は要件から削除されたため、個別にインストールする必要があります。 (Alexander Kukushkin)

    2.8.0 から、psycopg2 は psycopg2 と psycopg2-binary という 2 つの異なるパッケージに分割され、ファイル システム上の同じ場所に同時にインストールできるようになりました。依存関係による地獄の問題を減らすために、ユーザーがインストール方法を選択できるようにしました。利用可能なオプションがいくつかあります。ドキュメント を参照してください。

  • PostgreSQL 12 との互換性 (Alexander Kukushkin)

    PostgreSQL 12 以降、recovery.conf はなくなり、以前のすべての回復パラメーターは GUC に変換されます。 ALTER SYSTEM SET primary_conninfo などから保護するために、Patroni は postgresql.auto.conf を解析し、そこからすべてのスタンバイ パラメーターとリカバリ パラメーターを削除します。 Patroni 構成には下位互換性が維持されます。たとえば、restore_command が GUC であるにもかかわらず、postgresql.recovery_conf.restore_command セクションで指定することができ、Patroni はそれを PostgreSQL 12 の postgresql.conf に書き込みます。

  • PostgreSQL 11 以降でスーパーユーザーなしで pg_rewind を使用できるようにします (Alexander Kukushkin)

    この機能を使用したい場合は、Patroni 構成ファイルの postgresql.authentication.rewind セクションで username および password を定義してください。既存のクラスターの場合は、ユーザーを手動で作成し、いくつかの関数に対する GRANT EXECUTE 権限を付与する必要があります。詳細については、PostgreSQL ドキュメント を参照してください。

  • レプリカの実際のprimary_conninfoと設定したい値を適切に比較するようにしました（Alexander Kukushkin）。

    既存のプライマリー/スタンバイ クラスターを Patroni によって管理されるクラスターに変換するときに、レプリカの再起動を回避できる場合があります。

  • IPv6 サポート (Alexander Kukushkin)

    大きな問題が 2 つありました。 Patroni REST API サービスは 0.0.0.0 でのみリッスンしており、api_url と conn_url で使用される IPv6 IP アドレスは正しく角括弧で囲まれていませんでした。

  • Kerberos サポート (Ajith Vilas、Alexander Kukushkin)

    Patroni 構成ファイルでパスワードを定義する代わりに、Postgres ノード間で Kerberos 認証を使用できるようになります。

  • pg_ident.conf の管理 (Alexander Kukushkin)

    この機能は pg_hba.conf と同様に機能します。postgresql.pg_ident が構成ファイルまたは DCS で定義されている場合、Patroni はその値を pg_ident.conf に書き込みますが、postgresql.parameters.ident_file が定義されている場合、Patroni は pg_ident が外部から管理されているものとみなし、ファイルを更新しません。

REST API の改善

  • /health エンドポイントを追加しました (Wilfried Roset)

    PostgreSQL が実行されている場合にのみ、HTTP ステータス コード 200 を返します。

  • /read-only および /read-write エンドポイントを追加しました (Julien Riou)

    /read-only エンドポイントにより、レプリカとプライマリー間で読み取りのバランスがとれます。 /read-write エンドポイントは、/primary、/leader、および /master のエイリアスです。

  • SSLContext を使用して、REST API ソケットをラップします。 (Julien Riou)

    ssl.wrap_socket() の使用は非推奨になりましたが、TLS 1.1 など、間もなく非推奨となるプロトコルもまだ許可されていました。

ロギングの改善

  • 2 ステップ ロギング (Alexander Kukushkin)

    すべてのログ メッセージは、最初にメモリ内のキューに書き込まれ、その後、別のスレッドから stderr またはファイルに非同期的にフラッシュされます。最大キュー サイズは制限されています (構成可能)。制限に達すると、Patroni はログを失い始めますが、HA ループをブロックするよりはまだマシです。

  • GET/OPTIONS API 呼び出しとレイテンシのデバッグ ログを有効にします (Jan Tomsa)

    これは、HAProxy、Consul、またはどのノードがプライマリー/レプリカであるかを決定するその他のツールによって実行されるヘルスチェックのデバッグに役立ちます。

  • Retry でキャッチされた例外をログに記録しました (Daniel Kucera)

    試行回数またはタイムアウトに達したときの最後の例外をログに記録します。 DCS への通信が失敗した場合に、いくつかの問題をデバッグするのに役立つことが期待されます。

patronictl の改善

  • スケジュールされたスイッチオーバーと再起動のためのダイアログを強化しました (Rafia Sabih)

    以前のダイアログでは、スケジュールされたアクションが考慮されていなかったため、誤解を招く恐れがありました。

  • 設定ファイルが存在するかどうかを確認します (Wilfried Roset)

    指定されたファイル名が存在しない場合は、黙って無視するのではなく (誤解を招く可能性があります)、構成ファイルについて詳しく説明してください。

  • EDITOR のフォールバック値を追加 (Wilfried Roset)

    EDITOR 環境変数が定義されていない場合、patronictl edit-config は PatroniCtlException で失敗していました。新しい戦略は、まず editor を試し、次に vi を試すことです (vi はほとんどのシステムで利用できるはずです)。

Consul サポートの改善

  • Consul 整合性モードの指定を許可します (Jan Tomsa)

    整合性モードの詳細については、ここ を参照してください。

  • SIGHUP で Consul 設定を再ロード (Cameron Daniel Kucera、Alexander Kukushkin)

    これは、誰かが token の値を変更する場合に特に便利です。

バグ修正

  • スイッチオーバー/フェイルオーバーの特殊なケースを修正しました (Sharoon Thomas)

    REST API にアクセスできず、フォールバックとして DCS を使用している場合、変数 scheduled_at は未定義である可能性があります。

  • カスタム ブートストラップ中に pg_hba.conf でローカルホストへの信頼をオープンします (Alexander Kukushkin)

    以前は unix_socket に対してのみ開かれていたため、多くのエラーが発生していました: FATAL: no pg_hba.conf entry for replication connection from host "127.0.0.1", user "replicator"

  • 前のリーダーが先行している場合でも、同期ノードは健全であるとみなします (Alexander Kukushkin)

    プライマリーが DCS へのアクセスを失った場合、Postgres を読み取り専用で再起動しますが、他のノードが REST API を介して古いプライマリーに依然としてアクセスできる可能性があります。このような状況により、古いプライマリーが同期スタンバイよりも先に進んだ WAL 位置を報告していたため、同期スタンバイが昇格しませんでした。

  • スタンバイ クラスターのバグ修正 (Alexander Kukushkin)

    standby_leader にアクセスできない場合にスタンバイ クラスターでレプリカをブートストラップできるようにするほか、いくつかのマイナーな修正を加えました。

バージョン 1.5.6

2019-08-03 リリース

新機能

  • プロキシのセットを介した etcd クラスターとの連携をサポート (Alexander Kukushkin)

    etcd クラスターに直接アクセスできず、プロキシのセットを介してのみアクセスできる場合があります。この場合、Patroni は etcd トポロジ検出を実行せず、プロキシ ホストを介したラウンドロビンのみを実行します。動作は etcd.use_proxies によって制御されます。

  • ノード上のロールが変更されたときのコールバックの動作が変更されました。 (Alexander Kukushkin)

    ロールが master または standby_leader から replica に、または replica から standby_leader に変更された場合、on_restart コールバックは呼び出されなくなり、on_role_change コールバックが優先されます。

  • postgres の起動方法を変更する (Alexander Kukushkin)

    それ自体を実行する代わりに multiprocessing.Process を使用し、multiprocessing.Pipe を使用してポストマスター PID を Patroni プロセスに送信します。以前はパイプを使用していたため、ポストマスター プロセスの stdin が閉じられた状態になっていました。

バグ修正

  • スタンバイ リーダーの REST API によって返された役割を修正 (Alexander Kukushkin)

    standby_leader ではなく、誤って replica を返していました。

  • コールバックを強制終了できなかった場合は終了を待ちます。 (Julien Tachoires)

    Patroni には、sudo で実行されているコールバック スクリプトを終了するための十分な権限がありません。この終了処理の失敗により、新しいコールバックがキャンセルされていました。実行中のスクリプトを強制終了できなかった場合、Patroni は終了するまで待機し、次のコールバックを実行します。

  • dcs.get_cluster メソッドにかかるロック時間を短縮しました (Alexander Kukushkin)

    ロックが保持されているため、DCS の遅延が REST API ヘルス チェックに影響し、誤検知が発生していました。

  • pg_wal/pg_xlog がシンボリックリンクである場合の PGDATA のクリーニングを改善しました。 (Julien Tachoires)

    この場合、Patroni はターゲット ディレクトリからファイルを明示的に削除します。

  • os.path.relpath の不要な使用を削除します (Ants Aasma)

    これは作業ディレクトリを解決できることに依存するため、後にファイルシステムからリンク解除されるディレクトリで Patroni が起動された場合には失敗します。

  • Etcd と通信するときに SSL バージョンを強制しません。 (Alexander Kukushkin)

    何らかの理由で、debian および ubuntu の python3-etcd はパッケージの最新バージョンに基づいていないため、etcd v3 でサポートされていない TLSv1 を強制します。この問題は Patroni 側で解決しました。

バージョン 1.5.5

2019-02-15 リリース

このバージョンでは、以前のマスターの自動再初期化の可能性が導入され、patronictl listの出力が改善され、多くのバグが修正されています。

新機能

  • PATRONI_ETCD_PROTOCOL、PATRONI_ETCD_USERNAME、PATRONI_ETCD_PASSWORD 環境変数のサポートを追加しました (Étienne M)

    以前は、構成ファイル内でのみ、または PATRONI_ETCD_URL の一部としてのみ構成できましたが、必ずしも便利ではありませんでした。

  • 以前のマスターを自動的に再初期化できるようにしました (Alexander Kukushkin)

    pg_rewind が無効になっているか使用できない場合、タイムラインが分岐するため、元のマスターが新しいレプリカとして起動できない可能性があります。この場合、それを修正する唯一の方法は、データ ディレクトリを消去して再初期化することです。この動作は、postgresql.remove_data_directory_on_diverged_timelines を設定することで変更できます。これが設定されると、Patroni はデータ ディレクトリを消去し、元のマスターを自動的に再初期化します。

  • patronictl listのタイムラインに関する情報を表示 (Alexander Kukushkin)

    古いレプリカを検出するのに役立ちます。それに加えて、ポート値がデフォルトでない場合、または同じホスト上で複数のメンバーが実行されている場合、Host には「:{port}」が含まれます。

  • $SCOPE-config エンドポイントに関連付けられたヘッドレス サービスを作成します (Alexander Kukushkin)

    “config” エンドポイントは、クラスター全体の Patroni および Postgres 構成、履歴ファイル、そして最後に最も重要な initialize キーに関する情報を保持します。 Kubernetes マスター ノードが再起動またはアップグレードされると、サービスのないエンドポイントが削除されます。ヘッドレス サービスにより、削除されなくなります。

バグ修正

  • リーダー監視ブロッキングクエリーの読み取りタイムアウトを調整しました。 (Alexander Kukushkin)

    Consul ドキュメントによると、実際の応答タイムアウトは、同時要求のウェイクアップ時間を分散するために、指定された最大待機時間にランダムな少量の追加待機時間を加えることによって増加します。最大 wait / 16 時間の追加時間が最大期間に追加されます。この場合、大きい方に応じて wait / 15 または 1 秒を追加します。

  • レプリケーション プロトコル経由で postgres に接続する場合は、常に replication=1 を使用します。 (Alexander Kukushkin)

    Postgres 10 以降、pg_hba.conf の database=replication を含む行は、パラメーター replication=database を使用した接続を受け入れません。

  • WAL 専用スタンバイ クラスターの場合は、primary_conninfo を recovery.conf に書き込まないでください。 (Alexander Kukushkin)

    standby_cluster 構成で host も port も定義されていないにもかかわらず、Patroni は primary_conninfo を recovery.conf に入れていましたが、これは役に立たず、多くのエラーを生成していました。

バージョン 1.5.4

2019-01-15 リリース

このバージョンでは、柔軟なロギングが実装され、多くのバグが修正されています。

新機能

  • ロギング インフラストラクチャの改善 (Alexander Kukushkin、Lucas Capistrant、Alexander Anikin)

    ロギング構成は、環境変数からだけでなく、Patroni 構成ファイルからも構成できます。構成を更新してリロードを実行するか、SIGHUP を Patroni プロセスに送信することで、実行時にロギング構成を変更できるようになります。デフォルトでは、Patroni はログを stderr に書き込みますが、ログをファイルに直接書き込み、特定のサイズに達したときにローテーションすることが可能になりました。これに加えて、カスタム日付形式のサポートと、各 Python モジュールのログ レベルを微調整する機能が追加されました。

  • リーダー選挙中に現在のタイムラインを考慮できるようにします (Alexander Kukushkin)

    現在、既知の最新のタイムラインに載っていないにもかかわらず、ノードが自身を最も健全なノードであるとみなしている可能性があります。場合によっては、そのようなノードの昇格を避けたいことがあります。これは、check_timeline パラメーターを true に設定することで実現できます (デフォルトの動作は変更されません)。

  • スーパーユーザー資格情報の要件の緩和

    Libpq を使用すると、ユーザー名もパスワードも明示的に指定せずに接続を開くことができます。状況に応じて、pgpass ファイルまたは pg_hba.conf のtrust 認証方式のいずれかに依存します。 pg_rewind も libpq を使用しているため、同じように動作します。

  • Consul のサービス登録とチェック間隔を環境変数で設定できる機能を実装しました (Alexander Kukushkin)

    Consul でのサービスの登録は 1.5.0 に追加されましたが、これまでは patroni.yaml を介してのみ有効にすることができました。

安定性の向上

  • カスタム ブートストラップ中に archive_mode をオフに設定します (Alexander Kukushkin)

    クラスターが完全に機能するまでは、WAL と履歴ファイルのアーカイブは避けたいと考えています。カスタム ブートストラップに pg_upgrade が含まれる場合、これは非常に役立ちます。

  • 起動時にグローバル設定をロードするときに 5 秒のバックオフを適用します (Alexander Kukushkin)

    Patroni の起動直後に DCS に大量のリクエストを送りつけるのを避けるのに役立ちます。

  • シャットダウン時に生成されるエラー メッセージの量を削減しました (Alexander Kukushkin)

    それらは無害ですが、かなり迷惑で、時には恐ろしいものでした。

  • 作成時に recovery.conf の rw 権限を明示的に保護します (Lucas Capistrant)

    このファイルにはレプリケーション ユーザーとパスワードが含まれているため、patroni/postgres ユーザー以外はこのファイルを読み取れないようにします。

  • HTTPServer 例外をロガーにリダイレクトしました (Julien Riou)

    デフォルトでは、このような例外は通常のログを混乱させて標準出力に記録されていました。

バグ修正

  • pg_ctl プロセスの stdout への stderr パイプを削除しました (Cody Coons)

    メインの Patroni プロセスから stderr を継承すると、すべての Postgres ログをすべての Patroni ログとともに表示できるようになります。 Patroni および Postgres ログは標準ツール (docker logs、kubectl など) を使用して使用できるため、これはコンテナー環境で非常に役立ちます。それに加えて、この変更により、postgres がいくつかの警告を標準エラー出力に書き込むときに Patroni がポストマスター PID をキャッチできないというバグが修正されます。

  • Consul サービス チェック登録解除タイムアウトを Go 時間形式で設定します (Pavel Kirillov)

    時間単位を明示しないと、サービスの登録が失敗していました。

  • standby_cluster クラスター構成のチェックを緩める (Dmitry Dolgov、Alexander Kukushkin)

    有効な値として文字列のみを受け入れていたため、ポートを整数として指定したり、create_replica_methods をリストとして指定したりすることはできませんでした。

バージョン 1.5.3

2018-12-03 リリース

互換性とバグ修正のリリース。

  • Python3 で Zookeeper に対して実行するときの安定性を向上 (Alexander Kukushkin)

    loop_wait の変更により、Patroni が Zookeeper から切断され、再接続できなくなりました。

  • postgres 9.3 との互換性の破損を修正しました (Alexander Kukushkin)

    9.3 は replication=‘database’ を理解できないため、レプリケーション接続を開くときは、replication=1 を指定する必要があります。

  • HA ループごとに少なくとも 1 回は Consul セッションを更新し、Consul セッション例外の処理を改善しました。 (Alexander Kukushkin)

    ローカル Consul エージェントを再起動すると、ノードに関連するすべてのセッションが無効になります。セッション更新を時間通りに呼び出さず、セッション エラーを適切に処理しなかったことが、プライマリーの降格を引き起こしていました。

バージョン 1.5.2

2018-11-26 リリース

互換性とバグ修正のリリース。

  • kazoo-2.6.0 との互換性 (Alexander Kukushkin)

    リクエストが適切なタイムアウトで実行されることを確認するために、Patroni は python-kazoo モジュールの create_connection メソッドを再定義します。 kazoo の直近のリリースでは、create_connection メソッドの呼び出し方法が少し変更されました。

  • Consul クラスターがリーダーを失った場合の Patroni クラッシュを修正しました。 (Alexander Kukushkin)

    クラッシュは touch_member メソッドの不正な実装が原因で発生していました。このメソッドはブール値を返すべきであり、例外を発生させるべきではありません。

バージョン 1.5.1

2018-11-01 リリース

このバージョンでは、永続的なレプリケーション スロットのサポートが実装され、pgBackRest のサポートが追加され、いくつかのバグが修正されています。

新機能

  • 永続レプリケーション スロット (Alexander Kukushkin)

    永続的なレプリケーション スロットはフェイルオーバー/スイッチオーバーでも保持されます。つまり、新しいプライマリー上の Patroni は、プロモートの実行直後に構成済みのレプリケーション スロットを作成します。スロットは patronictl edit-config を使用して構成できます。初期設定は bootstrap.dcs で行うこともできます。

  • pgbackrest サポートを追加 (Yogesh Sharma)

    pgBackrest は既存の $PGDATA フォルダーに復元できます。これにより、最後のバックアップ以降変更されていないファイルがスキップされるため、迅速な復元が可能になります。この機能をサポートするために、新しいパラメーター keep_data が導入されました。追加の例については、レプリカ作成方法 セクションを参照してください。

バグ修正

バージョン 1.5.0

2018-09-20 リリース

このバージョンでは、Patroni HA クラスターがスタンバイ モードで動作できるようにし、Windows での実行に対する実験的なサポートが導入され、Consul に PostgreSQL サービスを登録するための新しい構成パラメーターが提供されます。

新機能

  • スタンバイ クラスター (Dmitry Dolgov)

    1 つ以上の Patroni ノードは、プライマリー クラスターと並行して (つまり、別のデータセンター内で) 実行されるスタンバイ クラスターを形成でき、プライマリー クラスターのマスターから複製するスタンバイ ノードで構成されます。スタンバイ クラスター内のすべての PostgreSQL ノードはレプリカです。これらのレプリカの 1 つはリモート マスターから直接レプリケートすることを選択し、他のレプリカは、その選出されたレプリカからカスケード方式でレプリケートします。この機能の詳細な説明といくつかの構成例については、ここで を参照してください。

  • Consul にサービスを登録する (Pavel Kirillov、Alexander Kukushkin)

    Consul 構成 の register_service パラメーターが有効な場合、ノードは scope という名前と master、replica、または standby-leader のタグを持つサービスを登録します。

  • 実験的 Windows サポート (Pavel Golub)

    今後、Patroni を Windows で実行できるようになりますが、Windows のサポートは新しく、対応する Linux ほど実際のテストは受けていません。フィードバックをお待ちしております。

patronictl の改善

  • patronictl -k/–insecure フラグを追加し、restapi cert をサポートしました。 (Wilfried Roset)

    以前は、REST API が自己署名証明書によって保護されていた場合、patronictl はそれらを検証できませんでした。その検証を無効にする方法はありませんでした。証明書検証を完全にスキップするように patronictl を構成したり、構成の ctl: セクションで CA とクライアント証明書を提供したりできるようになりました。

  • patronictl switchover/failover出力から nofailover タグを持つメンバーを除外します (Alexander Anikin)

    以前は、patronictl を介して対話型スイッチオーバーまたはフェイルオーバーを実行するときに、これらのメンバーが候補として誤って提案されていました。

安定性の向上

  • pg_controldata のキーと値以外の出力行を解析しないようにしました。 (Alexander Anikin)

    特定の状況下では、pg_controldata はコロン文字のない行を出力します。これにより、pg_controldata 出力を解析する Patroni コードでエラーが発生し、実際の問題が隠蔽されてしまいます。多くの場合、このような行は、通常の出力の前に、つまりバイナリのメジャー バージョンが PostgreSQL データ ディレクトリのバージョンと一致しない場合に、pg_controldata によって示される警告として出力されます。

  • リーダー選挙中のエラー メッセージにメンバー名を追加しました (Jan Mussler)

    リーダーの選出中、Patroni はクラスターのすべての既知のメンバーに接続し、そのステータスを要求します。このようなステータスは Patroni ログに書き込まれ、メンバーの名前も含まれます。以前は、メンバーにアクセスできない場合、エラー メッセージにはその名前が示されず、URL のみが含まれていました。

  • レプリケーション スロットの作成時に WAL 位置をすぐに予約します (Alexander Kukushkin)

    9.6 以降、pg_create_physical_replication_slot 関数は追加のブール値パラメーター immediately_reserve を提供します。これがデフォルトでもある false に設定されている場合、スロットは最初のクライアント接続を受信するまで WAL 位置を予約しないため、スロットの作成と最初のクライアント接続の間の時間枠でクライアントが必要とする一部のセグメントが失われる可能性があります。

  • 厳密な同期レプリケーションのバグを修正しました。 (Alexander Kukushkin)

    synchronous_mode_strict: true で実行すると、場合によっては、Patroni が * を synchronous_standby_names に置き、ほとんどのレプリケーション接続の同期状態を potential に変更します。以前は、Patroni は、async 状態の同期候補のみを考慮するため、このような状況では同期候補を選択できませんでした。

バージョン 1.4.6

2018-08-14 リリース

バグ修正と安定性の向上

このリリースでは、非マスター ノードに対して Patroni API /master エンドポイントが 200 を返すという重大な問題が修正されています。これはレポートの問題であり、実際のスプリット ブレインではありませんが、特定の状況下ではクライアントが読み取り専用ノードに誘導される可能性があります。

  • 降格時に is_leader ステータスをリセット (Alexander Kukushkin、Oleksii Kliukin)

    降格されたクラスター メンバーが、/master API 呼び出しにコード 200 を返さなくなることを確認します。

  • 新しい “cluster_unlocked” フィールドを API 出力に追加しました (Dmitry Dolgov)

    このフィールドは、クラスターでマスターが実行されているかどうかを示します。これは、レプリカの 1 つ以外の他のノードをクエリーできない場合に使用できます。

バージョン 1.4.5

2018-08-03 リリース

新機能

  • 新しい postgres 構成を適用する際のロギングを改善しました (Don Seiler)

    Patroni は、変更されたパラメータ名と値をログに記録します。

  • Python 3.7 の互換性 (Christoph Berg)

    async は python3.7 の予約キーワードです。

  • メンバーがシャットダウンされたときに、DCS の状態を “stopped” に設定します (Tony Sorrentino)

    これにより、メンバーの状態が「patronictl list」コマンドの “stopped” として表示されます。

  • 古いpostmaster.pidが実行中のプロセスと一致する場合に記録されるメッセージを改善しました（Ants Aasma）

    以前のメッセージは極めてわかりにくいものでした。

  • patronictl reload機能を実装します (Don Seiler)

    それまでは、REST API を呼び出すか、SIGHUP シグナルを Patroni プロセスに送信することによってのみ構成をリロードできました。

  • レプリカとして開始するときにcontroldataからいくつかのパラメーターを取得して適用します (Alexander Kukushkin)

    グローバル構成で設定される max_connections およびその他のパラメーターの値は、プライマリーで実際に使用される値よりも低い場合があります。この問題が発生すると、レプリカは起動できないため、手動で修正する必要があります。 Patroni は、pg_controldata から値を読み取って適用し、postgres を起動して pending_restart フラグを設定することで、これを処理します。

  • 設定されている場合、postgresの起動時にLD_LIBRARY_PATHを使用します。 (Chris Fraser)

    Postgres を起動するとき、Patroni は、PATH、LC_ALL、および LANG 環境変数が設定されている場合はそれらを渡していました。現在は LD_LIBRARY_PATH でも同じことを行っています。誰かが PostgreSQL を標準以外の場所にインストールすると役立つはずです。

  • create_replica_method の名前を create_replica_methods に変更しました。 (Dmitry Dolgov)

    それが実際には配列であることを明確にするためです。下位互換性のために古い名前も引き続きサポートされています。

バグ修正と安定性の向上

  • 一時停止モードで pg_rewind に関連するレプリカ起動条件を修正しました (Oleksii Kliukin)

    以前に pg_rewind を実行したレプリカを起動しないようにしてください。

  • update_lock が成功した場合にのみ、200 をマスター ヘルスチェックに応答します。 (Alexander Kukushkin)

    DCS がパーティション化されている場合に、以前の (降格された) マスター上で Patroni が自身をマスターとして報告しないようにします。

  • 新しい consul モジュールとの互換性を修正しました (Alexander Kukushkin)

    v1.1.0 から、python-consul は内部 API を変更し、クエリー パラメーターを渡すために dict の代わりに list を使用し始めました。

  • シャットダウン中に Patroni REST API スレッドからの例外をキャッチします (Alexander Kukushkin)

    これらのキャッチされなかった例外により、シャットダウン時に PostgreSQL が実行され続けました。

  • Postgres がマスターとして実行されている場合にのみクラッシュ回復を行うようにしました。 (Alexander Kukushkin)

    pg_controldata が ‘in production’、‘shutting down’、または ‘in crash recovery’ を報告することを要求します。それ以外の場合はすべて、クラッシュからの回復は必要ありません。

  • 構成エラーの処理を改善しました (Henning Jacobs、Alexander Kukushkin)

    Patroni 構成ファイルを更新し、SIGHUP を Patroni プロセスに送信することで、実行時に多くのパラメーター (restapi.listen を含む) を変更することができます。この修正により、一部のパラメーターが無効な値を受け取った場合に、‘restapi’ スレッドから不明瞭な例外が排除されます。

バージョン 1.4.4

2018-05-22 リリース

安定性の向上

  • poll_failover_result の競合状態を修正しました (Alexander Kukushkin)

    これはフェイルオーバーにもスイッチオーバーにも直接影響しませんでしたが、まれに、元のリーダーがロックを解放したときに成功を報告するのが早すぎて、‘Failed over to “desired-node”’ の代わりに ‘Failed over to “None”’ というメッセージが生成されることがありました。

  • Postgres パラメータ名を大文字と小文字を区別しないように扱います。 (Alexander Kukushkin)

    Postgres パラメーターのほとんどには snake_case 名が付いていますが、この規則には DateStyle、IntervalStyle、TimeZone の 3 つの例外があります。 Postgres は、これらのパラメーターが異なる大文字・小文字で記述されている場合 (例: timezone = ‘some/tzn’) でも受け入れます。ただし、Patroni は、pg_settings でこれらのパラメーター名の大文字と小文字を区別しない一致を見つけることができず、結果としてそのようなパラメーターを無視しました。

  • 実行中のpostgresにアタッチし、クラスターが初期化されていない場合、開始を中止します。 (Alexander Kukushkin)

    Patroni は、すでに実行中の Postgres インスタンスにそれ自体をアタッチできます。レプリカ上で Patroni を起動する前に、マスター ノードで Patroni の実行を開始することが不可欠です。

  • patronictl scaffold の動作を修正しました (Alexander Kukushkin)

    JSON でエンコードされた文字列の代わりに dict オブジェクトを touch_member に渡します。 DCS 実装がエンコードを処理します。

  • 一時停止中にリーダーキーの更新に失敗した場合にマスターを降格しません。 (Alexander Kukushkin)

    メンテナンス中、DCS は読み取り要求には応答し続けながら、書き込み要求は失敗し始める可能性があります。この場合、Patroni は、DCS のリーダー ロックの更新に失敗した後、Postgres マスター ノードを読み取り専用モードに設定していました。

  • Patroni が新しいポストマスター プロセスを認識したときにレプリケーション スロットを同期するようになりました。 (Alexander Kukushkin)

    Postgres が再起動された場合、Patroni はレプリケーション スロットのリストが期待どおりであることを確認する必要があります。

  • 一時停止から復帰した後に sysid を確認し、レプリケーション スロットを同期します (Alexander Kukushkin)

    maintenance モード中に、データ ディレクトリが完全に書き換えられる可能性があるため、Database system identifier がまだクラスターに属しており、レプリケーション スロットが Patroni の期待と同期していることを確認する必要があります。

  • 停止中の Postgres を、ポストマスター ロック ファイルが残るデータ ディレクトリで起動できない場合がある問題を修正しました。 (Alexander Kukushkin)

    ポストマスター ロック ファイルから PID の再利用を検出します。 Docker コンテナーで Patroni および Postgres を実行すると、このような問題が発生する可能性が高くなります。

  • DCS が誤ってワイプされた場合の保護を強化しました (Alexander Kukushkin)

    Patroni には、このような場合にフェイルオーバーを防ぐためのロジックが多数組み込まれています。すべてのキーを元に戻すこともできます。ただし、この変更が行われるまでは、/config キーを誤って削除すると、HA ループの 1 サイクルの一時停止モードがオフになっていました。

  • 無効なシステム ID に遭遇した場合に終了しない (Oleksii Kliukin)

    クラスター システム ID が空の場合、または検証チェックに合格しない場合は終了しないでください。その場合、クラスターの再初期化が必要になる可能性が高くなります。結果メッセージにそれを記載してください。 Patroni を終了しないでください。終了すると再初期化ができなくなります。

Kubernetes 1.10+ との互換性

  • 空のサブセットのチェックを追加しました (Cody Coons)

    Kubernetes 1.10.0+ は、[] ではなく None に設定された Endpoints.subsets を返すようになりました。

Bootstrap の改善

  • recovery.conf の削除をオプションにします (Brad Nicholson)

    bootstrap.<custom_bootstrap_method_name>.keep_existing_recovery_conf が定義され、True に設定されている場合、Patroni は既存の recovery.conf ファイルを削除しません。これは、適切な recovery.conf を生成する pgBackRest などのツールを使用してバックアップからブートストラップする場合に便利です。

  • basebackup 組み込みメソッドへのオプションを許可します (Oleksii Kliukin)

    カスタム レプリカ作成メソッドの定義方法と同様に、構成内で basebackup セクションを定義することで、組み込みの Basebackup メソッドにオプションを提供できるようになりました。違いは、basebackup セクションで受け入れられる形式にあります。pg_basebackup は --key=value オプションと --key オプションの両方を受け入れるため、セクションの内容は、キーと値のペアの辞書、または 1 要素の辞書や単独のキー (値を受け入れないオプションの場合) から成るリスト のいずれかになります。追加の例については、レプリカ作成方法 セクションを参照してください。

バージョン 1.4.3

2018-03-05 リリース

ロギングの改善

  • ログ レベルを環境変数から設定できるようにしました (Andy Newton、Keyvan Hedayati)

    PATRONI_LOGLEVEL - 一般的なログ レベルを設定します。 PATRONI_REQUESTS_LOGLEVEL - すべての HTTP リクエスト (例: Kubernetes API 呼び出し) のログ レベルを設定します。可能なログ レベルの名前を取得するには、Python ロギングのドキュメント のドキュメントを参照してください。

安定性の向上とバグ修正

  • 監視がタイムアウトしたときに etcd クラスター トポロジを再検出しないようにしました。 (Alexander Kukushkin)

    etcd 構成にホストが 1 つだけあり、そのホストにアクセスできない場合、Patroni はクラスター トポロジの検出を開始しましたが、決して成功しませんでした。代わりに、次の利用可能なノードに切り替える必要があります。

  • カスタム ブートストラップの後に bootstrap.pg_hba の内容を pg_hba.conf に書き込みます (Alexander Kukushkin)

    initdb を使用した通常のブートストラップと同様に動作するようになりました。

  • シングル ユーザー モードはユーザー入力を待機していて終了しませんでした (Alexander Kukushkin)

    回帰は https://github.com/patroni/patroni/pull/576 で導入されました

バージョン 1.4.2

2018-01-30 リリース

patronictl の改善

  • スケジュールされたフェイルオーバーの名前をスケジュールされたスイッチオーバーに変更しました (Alexander Kukushkin)

    フェイルオーバー機能とスイッチオーバー機能はバージョン 1.4 で分離されましたが、patronictl list は依然として Scheduled switchover ではなく Scheduled failover を報告していました。

  • 保留中の再起動に関する情報を表示する (Alexander Kukushkin)

    一部の構成変更を適用するには、postgres を再起動する必要がある場合があります。 Patroni は、REST API と、ノードのステータスを DCS に書き込むときに、すでにそのヒントを提供していましたが、それを表示する簡単な方法はありませんでした。

  • show-config が設定ファイルの cluster_nameで動作するようにしました。 (Alexander Kukushkin)

    patronictl edit-config と同様に機能します。

安定性の向上

  • ブートストラップ中に pg_controldata を呼び出さないようにします。 (Alexander Kukushkin)

    initdb またはカスタム ブートストラップ中に、pgdata は空ではないが、pg_control がまだ書き込まれていない時間帯があります。このような場合、pg_controldata 呼び出しはエラー メッセージとともに失敗していました。

  • psutil から発生した例外を処理するようになりました。 (Alexander Kukushkin)

    cmdline は、cmdline() メソッドが呼び出されるたびに読み取られて解析されます。検査対象のプロセスがすでに消滅している場合もあり、その場合は NoSuchProcess が発生します。

Kubernetes サポートの改善

  • k8s API からのエラーを飲み込まない (Alexander Kukushkin)

    Kubernetes API の呼び出しは、さまざまな理由で失敗する可能性があります。場合によっては、そのような呼び出しを再試行する必要がありますが、他の場合には、エラー メッセージと例外スタック トレースを記録する必要があります。ここでの変更は、Kubernetes 権限の問題のデバッグに役立ちます。

  • Kubernetes サンプル Dockerfile を更新して、master ブランチから Patroni をインストールします (Maciej Szulik)

    それまでは feature/k8s を使用していましたが、これは時代遅れになりました。

  • k8s で Patroni を実行するために適切な RBAC を追加しました (Maciej Szulik)

    クラスターのポッドに割り当てられるサービス アカウント、必要な権限のみを保持するロール、およびサービス アカウントとロールを接続するロールバインディングを追加します。

バージョン 1.4.1

2018-01-17 リリース

patronictl の修正

  • フェイルオーバー先のメンバーの推奨リストに現在のリーダーを表示しません。 (Alexander Kukushkin)

    patronictl failoverは、クラスター内にリーダーがある場合でも機能する可能性があるため、フェイルオーバー先のメンバーのリストから除外する必要があります。

  • patronictl switchoverを古い Patroni API と互換性のあるものにします (Alexander Kukushkin)

    POST /switchover REST API 呼び出しがステータス コード 501 で失敗した場合、/failover エンドポイントに対して再度実行されます。

バージョン 1.4

2018-01-10 リリース

このバージョンでは、Kubernetes を DCS として使用するためのサポートが追加されており、etcd、Zookeeper、または Consul を追加展開することなく、Kubernetes でクラウドネイティブ エージェントとして Patroni を実行できるようになります。

アップグレードのお知らせ

pip 経由で Patroni をインストールすると、(etcd、Zookeeper、Consul または Kubernetes のライブラリ、または AWS のサポートなど) の依存関係が取り込まれなくなります。それらを有効にするには、pip install 'patroni[etcd,kubernetes]' のように、pip install コマンドで明示的にリストする必要があります。

Kubernetes のサポート

Kubernetes ベースの DCS を実装します。エンドポイントのメタデータは、構成とリーダー キーを保存するために使用されます。ポッド定義内のメタデータ フィールドは、メンバー関連のデータを保存するために使用されます。エンドポイントの使用に加えて、Patroni は ConfigMaps をサポートします。この機能の詳細については、ドキュメントの Kubernetes 章 を参照してください。

安定性の向上

  • ポストマスタープロセスを別のオブジェクトに分解します (Ants Aasma)

    このオブジェクトは、pid と開始時刻を介して実行中のポストマスター プロセスを識別し、ポストマスターが Patroni の知らないうちに再起動されたとき、または postgres ディレクトリがファイル システムから消えたときの状況の検出 (および解決) を簡素化します。

  • HA サイクルの各ループで Patroni によって発行される SELECT の量を最小限に抑えます。 (Alexander Kukushkin)

    HA ループの反復ごとに、Patroni はリカバリ ステータスと絶対 WAL 位置を知る必要があります。今後、Patroni はこの情報を取得するために、レプリカ上で 2 つ、マスター上で 3 つではなく、単一の SELECT のみを実行します。

  • ロックを保持している場合にのみ、シャットダウン時にリーダー キーを削除します (Ants Aasma)

    無条件の削除により、不要で誤解を招く例外が生成されていました。

patronictl の改善

  • patronictl にversion コマンドを追加 (Ants Aasma)

    インストールされている Patroni のバージョンと、実行中の Patroni インスタンスのバージョン (クラスター名が指定されている場合) が表示されます。

  • patronictl コマンドの一部で、cluster_name 引数をオプションで指定できるようにしました (Alexander Kukushkin、Ants Aasma)

    patronictl が scope が定義された通常の Patroni 構成ファイルを使用している場合に機能します。

  • スケジュールされたスイッチオーバーとメンテナンス モードに関する情報を表示します (Alexander Kukushkin)

    それ以前は、この情報は Patroni ログから、または DCS から直接のみ取得できました。

  • patronictl reinit を改善 (Alexander Kukushkin)

    Patroni が他のアクション、つまり postgres を開始しようとしてビジー状態のときに、patronictl reinit が続行を拒否することがありました。 patronictl には、このような長時間実行アクションをキャンセルするコマンドが提供されておらず、唯一の (危険な) 回避策はデータ ディレクトリを手動で削除することでした。 reinit の新しい実装は、再初期化を続行する前に、他の長時間実行アクションを強制的にキャンセルします。

  • patronictl pause および patronictl resume に --wait フラグを実装しました (Alexander Kukushkin)

    要求されたアクションがクラスター内のすべてのノードによって承認されるまで、patronictl は待機します。このような動作は、DCS のすべてのノードに対して pause フラグを公開し、REST API を介して実現されます。

  • patronictl failover を patronictl switchover に名前変更します (Alexander Kukushkin)

    以前の failover は、実際にはスイッチオーバーのみが可能でした。リーダーのいないクラスターでは実行を拒否していました。

  • patronictl failover の動作を変更しました (Alexander Kukushkin)

    リーダーがない場合でも機能しますが、その場合は新しいリーダーとなるノードを明示的に指定する必要があります。

タイムラインと履歴に関する情報の公開

  • 現在のタイムラインを DCS および API 経由で公開します (Alexander Kukushkin)

    クラスターの各メンバーの現在のタイムラインに関する情報を保存します。この情報は API 経由でアクセスでき、DCS に保存されます。

  • プロモーション履歴を DCS の /history キーに保存します (Alexander Kukushkin)

    さらに、対応するプロモーションのタイムスタンプで強化されたタイムライン履歴を DCS の /history キーに保存し、プロモートごとに更新します。

同期および非同期レプリカを取得するためのエンドポイントを追加する

  • 新しい /sync および /async エンドポイントを追加します (Alexander Kukushkin、Oleksii Kliukin)

これらのエンドポイント (/synchronous および /asynchronous としてもアクセス可能) は、それぞれ同期レプリカと非同期レプリカに対してのみ 200 を返します (noloadbalance としてマークされたものを除く)。

etcd に対して複数のホストを許可する

  • Etcd 設定に新しい hosts パラメータを追加しました。 (Alexander Kukushkin)

    このパラメーターには、実行中の etcd クラスター メンバーのリストを検出して設定するために使用されるホストの初期リストが含まれている必要があります。作業中に何らかの理由で、この検出されたホストのリストが使い果たされた場合 (そのリストに使用可能なホストがない場合)、Patroni は hosts パラメーターから初期リストに戻ります。

バージョン 1.3.6

2017-11-10 リリース

安定性の向上

  • postgres が実行されているかどうかを確認するときに、プロセスの開始時間を確認します。 (Ants Aasma)

    postmaster.pid をクリーンアップしないクラッシュの後は、同じ pid を持つ新しいプロセスが存在する可能性があり、その結果 is_running() の誤検出が発生し、あらゆる種類の不正な動作につながります。

  • データ ディレクトリを失った場合、ブートストラップの前に PostgreSQL をシャットダウンします (ainlolcat)

    マスター上のデータ ディレクトリが強制的に削除されると、postgres プロセスがしばらくの間生きたままになり、元のマスターの代わりに作成されたレプリカの起動や複製が妨げられることがあります。この修正により、Patroni はポストマスター PID とその開始時刻をキャッシュし、対応するデータ ディレクトリが削除された後も古いポストマスターがまだ実行されている場合に備えて古いポストマスターを終了できるようになります。

  • postgres マスターが停止した場合にシングル ユーザー モードでクラッシュ リカバリを実行します。 (Alexander Kukushkin)

    postgres が正常にシャットダウンされていない場合、すぐにスタンバイとして起動するのは安全ではなく、pg_rewind も実行できません。シングル ユーザー クラッシュ リカバリは、pg_rewind が有効になっている場合、または現時点でマスターが存在しない場合にのみ開始されます。

Consul の改善

  • Consul のデータセンター構成を提供できるようにします (Vilius Okockis、Alexander Kukushkin)

    それまでは、Patroni は常に、それが実行されているホストのデータセンターと通信していました。

  • 常に X-Consul-Token http ヘッダーでトークンを送信します (Alexander Kukushkin)

    consul.token が Patroni 構成で定義されている場合、常に「X-Consul-Token」http ヘッダーで送信されます。 python-consul モジュールは、Consul REST API との「一貫性」を保とうとするもので、Consul REST API は セッション API のクエリー パラメーターとしてトークンを受け入れませんが、「X-Consul-Token」ヘッダーでは引き続き機能します。

  • 指定された値が可能な最小値より小さい場合、セッション TTL を調整します。 (Stas Fomin、Alexander Kukushkin)

    Patroni 構成で提供される TTL が、Consul でサポートされる最小値よりも小さい場合があります。その場合、Consul エージェントは新しいセッションの作成に失敗します。セッションがないと、Patroni は Consul KV ストアにメンバー キーとリーダー キーを作成できず、クラスターが異常な状態になります。

その他の改善点

  • 環境変数 PATRONI_LOGFORMAT を使用してカスタム ログ形式を定義します (Stas Fomin)

    システム ロガーによってすでに追加されている場合 (通常は Patroni がサービスとして実行されている場合)、Patroni ログ内のタイムスタンプやその他の同様のフィールドを無効にすることができます。

バージョン 1.3.5

2017-10-12 リリース

バグ修正

  • データ ディレクトリが削除された場合はロールを ‘uninitialized’ に設定します。 (Alexander Kukushkin)

    ノードがマスターとして実行されている場合、フェイルオーバーが妨げられていました。

安定性の向上

  • postgres を起動しようとして失敗した場合は、シングルユーザー モードで postmaster を実行してみてください。 (Alexander Kukushkin)

    通常、このような問題は、マスターとして実行されているノードが終了し、タイムラインが分岐したときに発生します。 recovery.conf に restore_command が定義されている場合、postgres が起動を中止し、制御データが変更されないままになる可能性が非常に高くなります。 正常にシャットダウンされていることを前提とする pg_rewind を使用できなくなります。

Consul の改善

  • セッション作成時にヘルスチェックを指定できるようにしました。 (Alexander Kukushkin)

    指定しない場合、Consul は「serfHealth」を使用します。これにより、孤立したマスターを迅速に検出できるようになります。一方で、Patroni が短いネットワーク遅延を許容できなくなります。

バグ修正

  • Python 3 のウォッチドッグを修正 (Ants Aasma)

    ioctl() 呼び出しインターフェースの誤解。 mutable=False の場合、fcntl.ioctl() は実際に arg バッファを返します。 int と str の比較でエラーが返されなかったため、これは Python2 で誤って機能しました。エラー報告は実際には、Python2 では IOError を、Python3 では OSError を発生させることによって行われます。

バージョン 1.3.4

2017-09-08 リリース

Consul のさまざまな改善

  • Consul トークンをヘッダーとして渡す (Andrew Colin Kissa)

    ヘッダーは、トークンを Consul API に渡すための推奨される方法になりました。

  • Consul の高度な構成 (Alexander Kukushkin)

    scheme、token、クライアント証明書および CA 証明書を指定できます (詳細 )。

  • python-consul-0.7.1 以降との互換性 (Alexander Kukushkin)

    新しい python-consul モジュールはいくつかのメソッドのシグネチャを変更しました

  • 「Could not take out TTL lock」メッセージがログに記録されていませんでした。 (Alexander Kukushkin)

    重大なバグではありませんが、適切なログが記録されていないと、問題が発生した場合の調査が複雑になります。

quote_ident を使用して synchronous_standby_names を引用する

  • synchronous_standby_names を postgresql.conf に書き込むときは、その値を引用符で囲む必要があります。 (Alexander Kukushkin)

    正しく引用符で囲まれていない場合、PostgreSQL は事実上同期レプリケーションを無効にし、動作を継続します。

一時停止状態に関するさまざまなバグ修正。主にウォッチドッグに関連します。 (Alexander Kukushkin)

  • ウォッチドッグがアクティブでない場合はキープアライブを送信しない
  • 一時停止モードでウォッチドッグをアクティブ化しないでください
  • 一時停止モードで正しい postgres 状態を設定する
  • postgres が停止している場合は、API からクエリーを実行しないでください

バージョン 1.3.3

2017-08-04 リリース

バグ修正

  • 同期レプリケーションは、synchronous_mode_strict がオンになっている場合でも、昇格直後に無効になりました。 (Alexander Kukushkin)
  • バックアップからのリストア後にpg_ident.confが存在しない場合、空のファイルを作成するようにしました（Alexander Kukushkin）。
  • pg_hba.conf で postgres だけでなくすべてのデータベースにアクセスできるようになりました (Franco Bellagamba)

バージョン 1.3.2

2017-07-31 リリース

バグ修正

  • patronictl edit-config が ZooKeeper では動作しませんでした。 (Alexander Kukushkin)

バージョン 1.3.1

2017-07-28 リリース

バグ修正

  • _MemberStatus の変更により、API 経由の フェイルオーバーが機能しませんでした。 (Alexander Kukushkin)

バージョン 1.3

2017-07-27 リリース

バージョン 1.3 では、カスタム ブートストラップの可能性が追加され、pg_rewind のサポートが大幅に改善され、同期モードのサポートが強化され、patronictl に構成編集が追加され、Linux でウォッチドッグ サポートが実装されます。さらに、これは PostgreSQL 10 で正しく動作する最初のバージョンです。

アップグレードのお知らせ

新しいバージョンの Patroni との互換性に関する既知の問題はありません。バージョン 1.2 からの構成は変更せずに機能するはずです。新しいパッケージをインストールして Patroni を再起動する (PostgreSQL が再起動する) か、最初に Patroni を 一時停止モード に入れてからクラスター内のすべてのノードで Patroni を再起動する (一時停止モードの Patroni は PostgreSQL の停止/開始を試行しません) ことによって、最後に一時停止モードから再開することでアップグレードできます。

カスタムブートストラップ

  • クラスターのブートストラップのプロセスを構成可能にしました (Alexander Kukushkin)

    クラスター内の最初のノードを初期化するときに、initdb の代わりにカスタム ブートストラップ スクリプトを許可します。ブートストラップ コマンドは、クラスターの名前とデータ ディレクトリへのパスを受け取ります。結果として得られるクラスターはリカバリを実行するように構成でき、バックアップからブートストラップしてポイントインタイムリカバリを実行できるようになります。この機能の詳細については、ドキュメントページ を参照してください。

よりスマートな pg_rewind サポート

  • 現在のマスターとのタイムラインの違いを見て、pg_rewind を実行するかどうかを決定します。 (Alexander Kukushkin)

    以前は、Patroni には、pg_rewind をトリガーする一連の固定条件がありました。つまり、元のマスターを起動するとき、指定されたノードへのスイッチオーバー時にクラスター内の他のすべてのノードで pg_rewind を実行するとき、または nofailover タグを持つレプリカが存在するときです。これらすべてのケースに共通するのは、一部のレプリカが新しいマスターよりも (WAL 位置が) 先行している可能性があるということです。場合によっては、pg_rewind が何も行わなかったり、必要なときに実行されなかったりする場合もありました。この限られたルールのリストに依存する代わりに、Patroni でマスターとレプリカの WAL 位置を (ストリーミング レプリケーション プロトコルを使用して) 比較し、レプリカに巻き戻しが必要かどうかを確実に判断します。

同期レプリケーションモード厳密

  • 厳密モードを追加して同期レプリケーションのサポートを強化しました (James Sewell、Alexander Kukushkin)

    通常、synchronous_mode が有効で、マスターにレプリカが接続されていない場合、Patroni はマスターを書き込みに使用できる状態に保つために同期レプリケーションを無効にします。 synchronous_mode_strict オプションはこれを変更します。このオプションが設定されている場合、Patroni はレプリカが不足していても同期レプリケーションを無効にせず、マスターへのデータ書き込みを行うすべてのクライアントを事実上ブロックします。自動フェイルオーバーによるデータ損失を防止する同期モードの保証に加えて、ストリクト モードでは、各書き込みが 2 つのノードに永続的に保存されるか、クラスター内にノードが 1 つしかない場合には完全に書き込みが行われないことが保証されます。

patronictl を使用した構成編集

  • patronictl に構成編集を追加しました (Ants Aasma、Alexander Kukushkin)

    DCS に保存されている動的クラスター構成を編集する機能を patronictl に追加します。コマンドラインからのパラメーター/値の指定、$EDITOR の呼び出し、または yaml ファイルからの構成の適用のいずれかをサポートします。

Linux ウォッチドッグのサポート

  • Linux のウォッチドッグ サポートを実装します (Ants Aasma)

    Patroni が実行されていない、または応答していない (高負荷などの理由で) ノードを再起動するために、Linux ソフトウェア ウォッチドッグをサポートします。Linux ソフトウェア ウォッチドッグは、応答しないノードを再起動します。 Patroni 構成のwatchdog セクションから、使用するウォッチドッグ デバイス (デフォルトでは /dev/watchdog) とモード (on、automatic、off) を構成できます。詳細については、ウォッチドッグのドキュメント から入手できます。

PostgreSQL 10 のサポートを追加

  • Patroni は、これまでにリリースされた PostgreSQL 10 のすべてのベータ版と互換性があり、リリースされる予定の PostgreSQL 10 とも互換性があると予想されます。

PostgreSQL 関連の軽微な改善

  • Patroni 構成ファイルまたは DCS の動的構成を介して pg_hba.conf を定義します (Alexander Kukushkin)

    構成の postgresql セクションの pg_hba サブセクションで pg_hba.conf の内容を定義できるようにします。これにより、複数のノードでの pg_hba.conf の管理が簡素化されます。すべてのノードにログインして手動で変更し、構成をリロードする代わりに、DCS で一度だけ定義すればよいためです。

    定義すると、このセクションの内容は現在の pg_hba.conf を完全に置き換えます。 hba_file PostgreSQL パラメータが設定されている場合、Patroni はこれを無視します。

  • UNIX ソケットを介したローカル PostgreSQL クラスターへの接続をサポートしました (Alexander Kukushkin)

    Patroni 構成の postgresql セクションに use_unix_socket オプションを追加します。 true に設定され、PostgreSQL unix_socket_directories オプションが空でない場合、Patroni はその最初の値を使用してローカル PostgreSQL クラスターに接続できます。 unix_socket_directories が定義されていない場合、Patroni はそのデフォルト値を想定し、PostgreSQL 接続文字列内の host パラメーターを完全に省略します。

  • リロード時のスーパーユーザーおよびレプリケーション資格情報の変更をサポートしました (Alexander Kukushkin)

  • PostgreSQL データ ディレクトリ外への構成ファイルの保存をサポート (@jouir)

    新しい構成 postgresql 構成ディレクティブ config_dir を追加します。デフォルトはデータ ディレクトリであり、Patroni によって書き込み可能である必要があります。

バグ修正と安定性の向上

  • EtcdEventIndexCleared および EtcdWatcherCleared 例外を処理します (Alexander Kukushkin)

    無駄な再試行を回避することで、etcd によって監視操作が終了された場合の回復が高速化されます。

  • Etcd 障害時にスピンするエラーを削除し、ログ スパムを削減します (Ants Aasma)

    2 回目以降の etcd 接続失敗時に、すぐに再試行してスタック トレースをログに出力することは避けてください。

  • PostgreSQL プロセスをフォークするときにロケール変数をエクスポートする (Oleksii Kliukin)

    NLS で構築された PostgreSQL の英語以外のロケールでの postmaster became multithreaded during startup 致命的エラーを回避します。

  • レプリケーション スロットを削除する際の追加チェック (Alexander Kukushkin)

    場合によっては、Patroni は、WAL 送信者によってレプリケーション スロットを削除できなくなります。

  • PostgreSQL 命名規則に準拠するために、レプリケーション スロット名を 63 (NAMEDATALEN - 1) 文字に切り詰めます (Nick Scott)

  • Patroni から PostgreSQL クラスターに対して余分な接続が開かれるという競合状態を修正しました。 (Alexander Kukushkin)

  • ノードが空のデータ ディレクトリで再起動するときにリーダー キーを解放します (Alex Kerney)

  • リーダーなしでブートストラップを実行するときに非同期エグゼキュータをビジーに設定します。 (Alexander Kukushkin)

    これを行わないと、Patroni はクラスター内にリーダーが存在する必要のないブートストラップ メソッドによってブートストラップされながら通常の業務を続行したため、ノードが別のクラスターに属していることを示すエラーが発生する可能性がありました。

  • WAL-E レプリカ作成方法を改善しました (Joar Wandborg、Alexander Kukushkin)。

    • WAL-E ベース バックアップを解析するときに csv.DictReader を使用し、スペースで区切られた日付と時刻を持つ ISO 日付を受け入れます。
    • 復元する WAL の量を見積もるために、レプリカから現在の WAL 位置を取得することをサポートします。以前は、コードはマスター ノードでのみ利用可能なシステム情報関数を呼び出すために使用されていました。

バージョン 1.2

2016-12-13 リリース

このバージョンでは、同期レプリケーションの処理が大幅に改善され、起動プロセスとフェイルオーバーの信頼性が向上し、PostgreSQL 9.6 サポートが追加され、多くのバグが修正されています。さらに、これらのリリース ノートを含むドキュメントは https://patroni.readthedocs.io に移動されました。

同期レプリケーション

  • 同期レプリケーションのサポートを追加します。 (Ants Aasma)

    新しい構成変数 synchronous_mode を追加します。有効にすると、Patroni は synchronous_standby_names を管理し、利用可能な正常なスタンバイがあるときは常に同期レプリケーションを有効にします。同期モードが有効な場合、Patroni はマスター障害時に同期レプリケーションを行っていたスタンバイにのみ自動的にフェイルオーバーします。これは事実上、そのような場合にユーザーに表示されるトランザクションが失われないことを意味します。詳細な説明と実装の詳細については、機能ドキュメント を参照してください。

信頼性の向上

  • PostgreSQL が 100% 正常でない場合は、leader optime キーに保存されているリーダーの位置を更新しないでください。リーダーキーの更新に失敗した場合は直ちに降格します。 (Alexander Kukushkin)

  • 新しいレプリカをクローンするためのソース候補のリストから異常なノードを除外します。 (Alexander Kukushkin)

  • Etcd の場合と同様に、Consul の再試行およびタイムアウト戦略を実装します。 (Alexander Kukushkin)

  • --dcs と --config-file を patronictl のすべてのオプションに適用します。 (Alexander Kukushkin)

  • すべての postgres パラメータを postgresql.conf に書き込みます。 (Alexander Kukushkin)

    これにより、Patroni によって構成された PostgreSQL を pg_ctl だけで起動できます。

  • 構成にユーザーが存在しない場合の例外を回避します。 (Kirill Pushkin)

  • 異常なクラスターの一時停止を許可します。この修正が行われる前は、一時停止を実行しようとしたノードが異常な場合、patronictl は中断していました。 (Alexander Kukushkin)

  • リーダー監視機能を改善します。 (Alexander Kukushkin)

    以前は、レプリカは常にリーダー キーを監視していました (タイムアウトになるかリーダー キーが変更されるまでスリープ状態でした)。この変更により、レプリカの PostgreSQL が running 状態にある場合のみ監視され、PostgreSQL の停止/起動または再起動の場合は監視されません。

  • SIGCHLD を PID 1 として処理するときに競合状態が発生するのを避けてください。 (Alexander Kukushkin)

    以前は、Patroni 内の同じプロセスが新しいプロセスを生成し、そこから SIGCHLD を処理していたため、Docker コンテナー内で実行すると競合状態が発生する可能性がありました。この変更では、Patroni に fork/execs を使用し、元の PID 1 プロセスに子からのシグナルの処理を任せます。

  • WAL-E 復元を修正します。 (Oleksii Kliukin)

    以前の WAL-E リストアでは、マスターとの協議を完全に回避するために no_master フラグが使用されていたため、Patroni は常に pg_basebackup ではなく WAL からのリストアを選択していました。この変更により、no_master の元の意味に戻ります。つまり、マスターが実行されていない場合、レプリケーション方法として Patroni WAL-E リストアが選択される可能性があります。後者は、メソッドに渡された接続文字列を調べることによってチェックされます。さらに、再試行メカニズムがより堅牢になり、他の細かい点も処理されます。

  • 非同期 DNS リゾルバー キャッシュを実装します。 (Alexander Kukushkin)

    DNS が一時的に利用できない場合 (たとえば、ノードが受信する過剰なトラフィックが原因で) 失敗することを避けてください。

  • 開始状態とマスター開始タイムアウトを実装します。 (Ants Aasma、Alexander Kukushkin)

    以前は、pg_ctl はタイムアウトを待ってから、PostgreSQL が実行中であるとみなして処理を続行していました。これにより、PostgreSQL が実際には実行されていないのにリストに実行中として表示され、競合状態が発生して、フェイルオーバー、クラッシュ リカバリ、またはフェイルオーバーによって中断されたクラッシュ リカバリと巻き戻しのミスが発生しました。この変更により、master_start_timeout パラメーターが追加され、メインの HA ループに新しい状態 (starting) が導入されます。 master_start_timeout が 0 の場合、マスターがクラッシュしたときにフェイルオーバー候補が存在するとすぐにフェイルオーバーします。それ以外の場合、Patroni はマスター上で PostgreSQL を開始しようとした後、タイムアウトの間待機します。有効期限が切れると、可能であればフェイルオーバーされます。手動フェイルオーバー要求は、マスターのクラッシュ中にタイムアウト期限が切れる前であっても受け付けられます。

    timeout パラメーターを restart API エンドポイントおよび patronictl に導入します。これが設定され、再起動にタイムアウトよりも長い時間がかかると、PostgreSQL は異常とみなされ、他のノードがリーダー ロックを取得できるようになります。

  • 一時停止モードでの pg_rewind の動作を修正しました。 (Ants Aasma)

    Patroni が巻き戻しが必要であると考えているが巻き戻しができない場合 (つまり、pg_rewind が存在しない場合)、一時停止モードでの不必要な再起動を回避します。 pg_rewind 関連の Patroni 構成セクションに superuser 認証が欠落している場合、superuser (デフォルトの OS ユーザー) のデフォルトの libpq 値にフォールバックします。

  • コールバックの実行をシリアル化します。新しいコールバックが実行されようとしているときに、同じタイプの前のコールバックを強制終了します。コールバックの実行時にゾンビ プロセスが生成される問題を修正します。 (Alexander Kukushkin)

  • リーダー キーが DCS に設定されているにもかかわらず、このリーダー キーへの更新が失敗する場合は、以前のマスターを昇格させないでください。 (Alexander Kukushkin)

    これにより、現在のマスターが etcd および「一貫性のない読み取り」を許可する他の DCS の少数のノードとともにパーティション化されている場合にその役割を維持し続けるという問題が回避されます。

その他

  • ブートストラップに post_init 構成オプションを追加します。 (Alejandro Martínez)

    Patroni は、initdb を実行し、新しいクラスターに対して PostgreSQL を起動した直後に、このオプションのスクリプト引数を呼び出します。このスクリプトは、superuser を使用する接続 URL を受け取ります。パスワードが指定されている場合、Patroni はそのパスワードを含む .pgpass ファイルを指すように PGPASSFILE を設定します。スクリプトが失敗すると、Patroni の初期化も失敗します。これは、新しいユーザーを追加したり、新しいクラスターに拡張機能を作成したりする場合に便利です。

  • PostgreSQL 9.6 サポートを実装します。 (Alexander Kukushkin)

    wal_level = replica を hot_standby の同義語として使用し、これらの wal_level 値を切り替えるときに pending_restart フラグを回避します。 (Alexander Kukushkin)

ドキュメントの改善

  • Patroni メイン ループワークフロー図 を追加します。 (Alejandro Martínez、Alexander Kukushkin)

  • README を改善し、Helm チャートとリリース ノートへのリンクを追加しました。 (Lauri Apple)

  • Patroni ドキュメントを Read the Docs に移動します。最新のドキュメントは https://patroni.readthedocs.io で入手できます。 (Oleksii Kliukin)

    さまざまなデバイス (スマートフォンを含む) からドキュメントを簡単に表示し、検索できるようにします。

  • パッケージをセマンティック バージョニングに移動します。 (Oleksii Kliukin)

    Patroni は、小規模だが重大なバグ修正に関する新しいマイナー バージョンのリリースを回避するために、major.minor.patch バージョン スキーマに従います。すべてのパッチを含むマイナー バージョンのリリース ノートのみを公開します。

バージョン 1.1

2016-09-07 リリース

このリリースでは、一時停止モードを導入することで Patroni クラスターの管理が改善され、スケジュールされた再起動と条件付き再起動によるメンテナンスが改善され、etcd または Zookeeper との Patroni の対話の回復力が向上し、patronictl が大幅に強化されています。

アップグレードのお知らせ

1.0 より前のリリースからアップグレードする場合は、1.0 リリース ノートで資格情報と構成形式の変更についてお読みください。

一時停止モード

  • 一時停止モードを導入して、Patroni を PostgreSQL インスタンスの管理から一時的に切り離します (Murat Kabilov、Alexander Kukushkin、Oleksii Kliukin)。

    以前は、PostgreSQL を終了せずに、SIGKILL シグナルを Patroni に送信して停止する必要がありました。新しい一時停止モードは、Patroni を終了せずに、クラスター全体で Patroni を PostgreSQL から切り離します。これは、Pacemaker のメンテナンス モードに似ています。 Patroni は引き続き DCS のメンバー キーとリーダー キーを更新しますが、プロセス内で PostgreSQL サーバーを起動、停止、再起動することはありません。いくつかの例外があります。たとえば、手動フェイルオーバー、再初期化、再起動は引き続き許可されます。 この機能の詳細な説明 を参照できます。

さらに、patronictl は、一時停止モードを切り替えるための新しい pause および resume コマンドをサポートしています。

スケジュールされた再起動と条件付きの再起動

  • 再起動 API コマンドに条件を追加します (Oleksii Kliukin)

    この変更により、再起動を行うために検証できるいくつかの条件が追加され、Patroni の再起動が強化されます。条件には、PostgreSQL ロールがマスターまたはレプリカの場合の再起動、PostgreSQL バージョン番号の確認、構成変更を適用するために再起動が必要な場合のみの再起動などがあります。

  • スケジュールされた再起動を追加 (Oleksii Kliukin)

    将来の再起動をスケジュールできるようになりました。スケジュールされた再起動はノードごとに 1 つだけサポートされます。スケジュールされた再起動が必要なくなった場合は、クリアすることができます。スケジュールされた再起動と条件付き再起動の組み合わせがサポートされているため、たとえば、夜間にスケジュールされたマイナー PostgreSQL アップグレードが可能になり、管理スクリプトに postgres 固有のロジックを追加することなく、古いマイナー バージョンを実行しているインスタンスのみを再起動できます。

  • patronictl に条件付きおよびスケジュールされた再起動のサポートを追加しました (Murat Kabilov)。

    patronictl restart は、いくつかの新しいオプションをサポートします。スケジュールされたアクションを消去するための patronictl flush コマンドもあります。

堅牢な DCS インタラクション

  • loop_wait に応じて Kazoo タイムアウトを設定します (Alexander Kukushkin)

    当初、ping_timeout および connect_timeout の値は、ネゴシエートされたセッション タイムアウトから計算されました。 Patroni の loop_waitは考慮されていませんでした。その結果、1 回の再試行にセッション タイムアウトよりも長い時間がかかり、Patroni がロックを解放して降格する必要が生じる可能性があります。

    この変更により、ping と接続のタイムアウトがloop_wait の値の半分に設定され、接続の問題の検出が高速化され、ロックが失われる前に接続試行を再試行するのに十分な時間が残されました。

  • 元のリクエストが成功した後にのみ etcd トポロジを更新するようになりました。 (Alexander Kukushkin)

    クライアントに認識されている etcd トポロジの更新を、元のリクエストが完了するまで延期します。クラスター トポロジを取得するときは、etcd クラスター内の既知のノード数に応じて再試行タイムアウトを実装します。これにより、クライアントは最新のノードのリストを取得するよりも、リクエストの結果を取得することを優先します。

    どちらの変更も、ネットワークの問題に直面した場合でも、Patroni から DCS への接続をより堅牢にします。

patronictl、監視および構成

  • API 経由でストリーミング レプリカに関する情報を返します (Feike Steenbergen)

    以前は、(接続の問題などにより) 変更のストリーミングに失敗した PostgreSQL インスタンスについて Patroni をクエリーする信頼できる方法はありませんでした。この変更により、pg_stat_replication の内容が /patroni エンドポイント経由で公開されます。

  • patronictl scaffold コマンドを追加 (Oleksii Kliukin)

    etcd にクラスター構造を作成するコマンドを追加します。クラスターはユーザー指定の sysid とリーダーを使用して作成され、リーダー キーとメンバー キーの両方が永続化されます。このコマンドは、レプリカのみで構成される Patroni クラスターが Patroni を認識しない外部マスター ノードから複製される、いわゆるマスターレス構成を作成するのに役立ちます。その後、リーダー キーを削除し、Patroni ノードの 1 つをプロモートし、元のマスターを Patroni ベースの HA クラスターに置き換えます。

  • 構成オプション bin_dir を追加して、PostgreSQL バイナリを見つけます (Ants Aasma)

    Linux ディストリビューションが複数の PostgreSQL バージョンの同時インストールをサポートしている場合、PostgreSQL バイナリの場所を明示的に指定できると便利です。

  • custom_conf を使用して構成ファイルのパスを上書きできるようにする (Alejandro Martínez)

    Patroni によって管理されないカスタム構成ファイルのパスを許可します (詳細 )。

バグ修正とコードの改善

  • Patroni を PostgreSQL 10 以降の新しいバージョンのスキーマと互換性のあるものにします (Feike Steenbergen)

    PostgreSQL バージョンに基づいて条件付き再起動を行う場合、Patroni が 2 桁のバージョン番号を理解していることを確認してください。

  • pkgutil を使用して DCS モジュールを検索します (Alexander Kukushkin)

    DCS モジュールを見つけるためにディレクトリを手動で走査する代わりに、専用の Python モジュールを使用します。

  • Patroni を開始するときに常に on_start コールバックを呼び出します。 (Alexander Kukushkin)

    以前は、Patroni は、正しいロールですでに実行中のノードにアタッチするときにコールバックを呼び出しませんでした。コールバックはクライアント接続のルーティングによく使用されるため、接続ルーティング スキームで実行中のノードを登録できなくなる可能性があります。この修正により、Patroni は、既に実行中のノードに接続している場合でも on_start コールバックを呼び出します。

  • アクティブなレプリケーション スロットを削除しないでください (Murat Kabilov、Oleksii Kliukin)

    マスター上のアクティブな物理レプリケーション スロットをドロップしないようにします。いずれにせよ、PostgreSQL はそのようなスロットを削除できません。この変更により、Patroni 以外の管理対象レプリカ/コンシューマーをマスター上で実行できるようになります。

  • PostgreSQL インスタンスの起動中に Patroni 接続を閉じます。 (Alexander Kukushkin)

    PostgreSQL ノードの起動時に、Patroni が以前のすべての接続を強制的に閉じます。 postmaster が SIGKILL で強制終了された場合に、以前の接続が再利用されるという罠を回避します。

  • メンバー名からスロット名を構築するときに無効な文字を置換します (Ants Aasma)

    スロットの命名規則に準拠していないスタンバイ名によってスロットの作成やスタンバイの起動が失敗しないようにしてください。スロット名のダッシュをアンダースコアに置き換え、スロット名に使用できない他のすべての文字を Unicode コードポイントに置き換えます。

バージョン 1.0

2016-07-05 リリース

このリリースでは、HA クラスター全体の PostgreSQL および Patroni 構成パラメーターを動的に変更できるグローバル動的構成が導入されています。また、多数のバグ修正も提供されます。

アップグレードのお知らせ

v0.90 以下からアップグレードする場合は、必ずマスターより前にすべてのレプリカをアップグレードしてください。レプリケーション資格情報が DCS に保存されなくなったため、古いレプリカは新しいマスターに接続できなくなります。

動的構成

  • 動的グローバル構成の実装 (Alexander Kukushkin)

    新しい REST API エンドポイント /config を導入して、HA クラスター全体 (マスターとすべてのレプリカ) に対してグローバルに設定する必要がある PostgreSQL および Patroni 構成パラメーターを提供します。これらのパラメーターは DCS で設定され、多くの場合、PostgreSQL または Patroni を中断することなく適用できます。 Patroni は、一部の値で PostgreSQL の再起動が必要な場合に、API を介して表示される “pending restart” と呼ばれる特別なフラグを設定します。その場合、API を介して手動で再起動を発行する必要があります。

    Patroni に SIGHUP を送るか /reload に POST リクエストを送ると、構成ファイルが再読み取りされます。

    変更できるパラメータと、異なる構成ソースを処理する順序の詳細については、Patroni 構成 を参照してください。

    構成ファイルの形式は v0.90 から 変更されました。 Patroni は依然として古い設定ファイルと互換性がありますが、ブートストラップ パラメータを利用するには変更する必要があります。ユーザーは、動的構成ドキュメントページ を参照して更新することをお勧めします。

より柔軟な構成*

  • postgresql 構成と、Patroni が接続するデータベース名を構成可能にする (Misja Hoebe)

    database および config_base_name 構成パラメーターを導入します。特に、Patroni を PipelineDB および他の PostgreSQL フォークで実行できるようになります。

  • 環境経由で一部の Patroni 設定パラメータを設定できるように実装しました (Alexander Kukushkin)

    これらには、スコープ、ノード名、名前空間、およびシークレットが含まれており、動的環境 (つまり、Kubernetes) での Patroni の実行が容易になります。詳細については、サポートされている環境変数 を参照してください。

  • 組み込みの Patroni Docker コンテナを更新して、環境ベースの構成を活用します (Feike Steenbergen)。

  • Patroni docker イメージに Zookeeper サポートを追加しました (Alexander Kukushkin)

  • Zookeeper と Exhibitor の構成オプションを分割する (Alexander Kukushkin)

  • patronictl が構成を読み取るために Patroni のコードを再利用するようにしました。 (Alexander Kukushkin)

    これにより、patronictl は環境ベースの構成を利用できるようになります。

  • primary_conninfo でアプリケーション名をノード名に設定しました (Alexander Kukushkin)

    これにより、特定のノードの同期レプリケーションの識別と構成が簡素化されます。

安定性、セキュリティ、使いやすさの向上

  • sysid をリセットし、バックアップの復元の進行中に pg_controldata を呼び出さないようにしました。 (Alexander Kukushkin)

    この変更により、バックアップからのこのノードの長時間の初期化中に Patroni API ヘルス チェックによって生成されるノイズの量が減少します。

  • pg_rewind のいくつかのコーナーケースを修正しました (Alexander Kukushkin)

    ソースクラスターがマスターではない場合は、pg_rewind を実行しないでください。

    さらに、新しいパラメータ remove_data_directory_on_rewind_failure が true に設定されていない限り、巻き戻しが失敗したときにデータ ディレクトリを削除しないでください。デフォルトでは false です。

  • DCS のレプリケーション接続文字列からパスワードを削除します。 (Alexander Kukushkin)

    以前は、Patroni は常に、DCS の Postgres URL からのレプリケーション資格情報を使用していました。これは、Patroni 構成から資格情報を取得するように変更されました。シークレット (レプリケーション ユーザー名とパスワード) は DCS で公開されなくなりました。

  • 降格呼び出し周りの非同期機構を修正しました。 (Alexander Kukushkin)

    Demote は、DCS インタラクションをブロックすることなく、完全に非同期で実行されるようになりました。

  • 認証ヘッダーが設定されている場合、patronictl が、常に認証ヘッダーを送信するようにしました。 (Alexander Kukushkin)

    これにより、Patroni がそれらに対する承認を必要とするように構成されている場合、patronictl は “protected” リクエストを発行 (つまり、再起動または再初期化) することができます。

  • SystemExit 例外を正しく処理します (Alexander Kukushkin)

    SIGTERM を受信したときに Patroni が適切に停止しない問題を回避します。

  • confd 用のサンプル HAProxy テンプレート (Alexander Kukushkin)

    confd を使用して、DCS の Patroni 状態から HAProxy 構成を生成し、動的に変更します。

  • ドキュメントを改善および再構成して、新規ユーザーにとってより使いやすいものにします (Lauri Apple)

  • API は、pg_ctl stop の実行中に role=master を報告する必要があります。 (Alexander Kukushkin)

    特にクラスター停止の場合、コールバック呼び出しの信頼性が高まります。さらに、pg_ctl_timeout オプションを導入して、pg_ctl を介した開始、停止、再起動の呼び出しのタイムアウトを設定します。

  • etcd の再試行ロジックを修正しました。 (Alexander Kukushkin)

    再試行をより予測可能かつ堅牢にします。

  • Zookeeper コードの短いネットワーク障害に対する回復力を高めます (Alexander Kukushkin)

    接続タイムアウトを減らして、Zookeeper の接続試行の頻度を増やします。

バージョン 0.90

2016-04-27 リリース

このリリースでは、Consul のサポートが追加され、新しい noloadbalance タグが含まれ、clonefrom タグの動作が変更され、pg_rewind 処理が改善され、patronictl 制御プログラムが改善されます。

Consul のサポート

  • Consul サポートの実装 (Alexander Kukushkin)

    Patroni は、etcd と Zookeeper に加えて、Consul に対して実行されます。接続パラメータは YAML ファイルで構成できます。

新しいタグと改良されたタグ

  • noloadbalance タグを実装する (Alexander Kukushkin)

    このタグにより、Patroni は常にレプリカがロード バランサーで利用できないことを返すようになります。

  • clonefrom タグの実装を変更 (Alexander Kukushkin)

    以前は、clonefrom にノード名を指定する必要があり、タグ付きレプリカは特定のノードからクローンを作成するよう強制されていました。新しい実装では、clonefrom はブール型タグになります。これが true に設定されている場合、レプリカは他のレプリカのクローン元の候補になります。複数の候補が存在する場合、レプリカはランダムに 1 つを選択します。

安定性とセキュリティの向上

  • 数多くの信頼性の向上 (Alexander Kukushkin)

    いくつかの偽のエラー メッセージを削除し、フェイルオーバーの安定性を向上させ、DCS からのデータの読み取り、シャットダウン、以前のリーダーの降格、および再接続に関するいくつかの特殊なケースに対処します。

  • システム スクリプトを改善して、Patroni の子が停止中に殺されないようにする (Jan Keirse、Alexander Kukushkin)

    以前は、Patroni を停止すると、systemd も PostgreSQL にシグナルを送信していました。 Patroni も PostgreSQL を単独で停止しようとしたため、別のシャットダウン要求 (スマート シャットダウン、その後の高速シャットダウン) が送信されることになりました。その結果、レプリカの切断が早すぎて、元のマスターが降格後に再参加できなくなりました。 Alexander による事前調査をもとに Jan によって修正されました。

  • 元のマスターがレプリカとして再参加する前に pg_rewind を呼び出すことができなかったいくつかのケースを排除しました (Oleksii Kliukin)

    以前は、前のマスターがクラッシュした場合にのみ pg_rewind を呼び出していました。 pg_rewind がシステムに存在する限り、元のマスターに対して常に pg_rewind を実行するようにこれを変更します。これにより、レプリカが最新の変更を取得する前にマスターがシャットダウンされた場合 (つまり、“smart” シャットダウン中) が修正されます。

  • 単体テストと受け入れテストに対する数多くの改善により、特に Zookeeper と Consul のサポートが可能になりました (Alexander Kukushkin)。

  • Travis CI を高速化し、Zookeeper (Exhibitor) および Consul に対するテスト実行のサポートを実装します (Alexander Kukushkin)

    単体テストと受け入れテストはどちらも、各コミットまたはプルリクエストで etcd、Zookeeper、Consul に対して自動的に実行されます。

  • Patroni から PostgreSQL コマンドを呼び出す前に環境変数をクリアします (Feike Steenbergen)

    これにより、Patroni によって管理される PostgreSQL クラスターに接続することによってシステム環境変数が読み取られる可能性が回避されます。

構成と制御の変更

  • patronictl と Patroni 構成を統合 (Feike Steenbergen)

    patronictl は、Patroni 自体と同じ構成ファイルを使用できます。

  • Patroni が環境変数から構成を読み取れるようにします (Oleksii Kliukin)

    これにより、Patroni の構成の自動生成や、異なるソースからの単一の構成のマージが簡素化されます。

  • API によって返される情報にデータベース システム識別子を含めます (Feike Steenbergen)

  • 利用可能なすべての DCS に delete_cluster を実装します (Alexander Kukushkin)

    patronictl で etcd 以外の DCS のサポートを有効にします。

バージョン 0.80

2016-03-14 リリース

このリリースでは、カスケードレプリケーション のサポートが追加され、スケジュールされたフェイルオーバー を提供することで Patroni 管理が簡素化されます。新しいリリースに移行するために、古いバージョンの Patroni (特に 0.78) をこのバージョンと組み合わせて使用する場合があります。スケジュールされたフェイルオーバーとカスケード レプリケーション関連の機能は、Patroni 0.80 以降でのみ動作することに注意してください。

カスケードレプリケーション

  • patroni ノードの replicatefrom タグと clonefrom タグのサポートを追加 (Oleksii Kliukin)。

replicatefrom タグを使用すると、レプリカはマスターに限らず任意のノードをソースとして使用できます。 clonefrom は、最初のバックアップでも同じことを行います。これらを組み合わせることで、Patroni はカスケード レプリケーションを完全にサポートできるようになります。

  • 実行中のレプリケーション接続がなくてもレプリカを初期化するためのレプリケーション メソッドの実行サポートを追加しました (Oleksii Kliukin)。

これは、S3 または FTP に保存されているスナップショットからレプリカを作成する場合に便利です。レプリケーション接続の実行を必要としないレプリケーション メソッドでは、yaml 設定で no_master: true を指定する必要があります。レプリケーション接続が存在する場合、これらのスクリプトは引き続き順番に呼び出されます。

Patronictl、API、DCS の改善

  • スケジュールされたフェイルオーバーを実装します (Feike Steenbergen)。

    patronictl または API 呼び出しを使用して、将来の特定の時刻にフェイルオーバーが発生するようにスケジュールできます。

  • patronictl に dbuser および password パラメーターのサポートを追加しました (Feike Steenbergen)。

  • PostgreSQL バージョンをヘルス チェック出力に追加します (Feike Steenbergen)。

  • patronictl での Zookeeper のサポートを改善しました (Oleksandr Shulgin)

  • python-etcd 0.4.3 に移行 (Alexander Kukushkin)

構成

  • Patroni 用のサンプル システム構成スクリプトを追加します (Jan Keirse)。
  • DB 接続の構成ファイルで指定されたスーパーユーザー名が無視される Patroni の問題を修正しました (Alexander Kukushkin)。
  • Patroni によって起動されたポストマスター用に別のセッション ID とプロセス グループを作成することで、CTRL-C の処理を修正しました (Alexander Kukushkin)。

テスト

  • Patroni を実行する実際のシナリオをチェックするために、behave による受け入れテストを追加 (Alexander Kukushkin、Oleksii Kliukin)。

    テストは、behave コマンドを使用して手動で開始できます。また、プル リクエストやコミット後に自動的に起動されます。

    一部の古いバージョンのリリース ノートは、プロジェクトの github ページ にあります。

20 - 貢献ガイドライン

貢献のワークフロー、サポート窓口、開発ガイドライン。

チャット

質問がある場合、対話形式のトラブルシューティング支援が必要な場合、他のPatroniユーザーと話したい場合は、PostgreSQL Slack の#patroni チャンネルに参加してください。

バグの報告

バグを報告する前に、必ず最新のPatroniバージョンで再現することを確認してください。また、Issueトラッカー に同じ問題がすでに報告されていないかも再確認してください。

テストの実行

behaveテストを実行するための要件：

  1. contrib モジュールを含むPostgreSQLパッケージをインストールする必要があります。
  2. PostgreSQLのバイナリーをPATHから利用できなければなりません。PATH=/usr/lib/postgresql/11/bin:$PATH python -m behaveなどの方法でパスに追加する必要がある場合があります。
  3. 外部DCS（etcd、Consul、Zookeeperなど）を使用してテストする場合は、パッケージをインストールし、それぞれのサービスを起動して、localhostのデフォルトポートで暗号化も保護もされていない接続を受け付ける必要があります。etcdやConsulでは、バイナリーがPATHから利用できれば、behaveテストスイートがサービスを起動できます。

依存関係をインストールします。

# You may want to use Virtualenv or specify pip3.
pip install -r requirements.txt
pip install -r requirements.dev.txt

すべての依存関係をインストールしたら、各種テストスイートを実行できます。

# You may want to use Virtualenv or specify python3.

# Run flake8 to check syntax and formatting:
python setup.py flake8

# Run the pytest suite in tests/:
python setup.py test

# Moreover, you may want to run tests in different scopes for debugging purposes,
# the -s option include print output during test execution.
# Tests in pytest typically follow the pattern: FILEPATH::CLASSNAME::TESTNAME.
pytest -s tests/test_api.py
pytest -s tests/test_api.py::TestRestApiHandler
pytest -s tests/test_api.py::TestRestApiHandler::test_do_GET

# Run the behave (https://behave.readthedocs.io/en/latest/) test suite in features/;
# modify DCS as desired (raft has no dependencies so is the easiest to start with):
DCS=raft python -m behave

toxによるテスト

toxのテストを実行するためにインストールが必要な依存関係は、Pythonを除けば一つだけです。

pip install "tox>=4"

Dockerを使用するbehaveテストを実行する場合は、Dockerもインストールする必要があります。

tox.iniのTox構成には、次のタスクを実行するための「環境」があります。

  • lint: flake8によるPythonコードのlint
  • test: pytestによる、利用可能なすべてのPythonインタープリターの単体テスト。TTYを検出した場合はHTMLレポートを、それ以外はXMLレポートを生成する
  • dep: pipdeptreeによるパッケージ依存関係の競合の検出
  • type: pyrightによる静的な型チェック
  • black: blackによるコード整形
  • docker-build: behave環境で使用するDockerイメージのビルド
  • docker-cmd: 上記イメージでの任意のコマンドの実行
  • docker-behave-etcd: 上記イメージでのbehaveテスト用のtoxの実行
  • py*behave: 利用可能なPythonインタープリターによるbehaveの実行（Dockerは使用しないが、Dockerコンテナー内でもこれが呼び出される）
  • docs: sphinxによるドキュメントのビルド

toxの実行

デフォルトの環境一覧であるdep、lint、test、docsを実行するには、次を実行するだけです。

tox

test環境は、ラベルtestで実行できます。

tox -m test

Dockerでのbehaveテストは、ラベルbehaveで実行できます。

tox -m behave

同様に、docsにはdocsラベルがあります。

その他の環境は、それぞれの環境名で実行できます。

tox -e lint
tox -e py39-test-lin

factorsを使用して、環境一覧の一部を選択することもできます。たとえば、Python 3.10のすべての環境を実行する場合は、次のようにします。

tox -f py310

これは、次に示す環境をすべて実行することと同じです。

$ tox -l -f py310
py310-test-lin
py310-test-mac
py310-test-win
py310-type-lin
py310-type-mac
py310-type-win
py310-behave-etcd-lin
py310-behave-etcd-win
py310-behave-etcd-mac
py310-behave-etcd3-lin
py310-behave-etcd3-win
py310-behave-etcd3-mac

tox（>=v4）では、次のようにして構成済みのすべての環境の組み合わせを一覧表示できます。

tox l

アクティブなターミナルでtoxを実行している場合、test環境とdocs環境は、ジョブ完了時に出力されたHTMLファイルを開こうとします。これは、その環境をローカルで実行する開発者の利便性を目的としています。Macではopen、Linuxではxdg-openの実行を試みます。別のコマンドを使用するには、環境変数OPEN_CMDにコマンド名またはパスを設定してください。この手順に失敗しても、実行全体が失敗することはありません。この機能を無効にするには、環境変数OPEN_CMDに何もしないコマンドである:を設定します。

OPEN_CMD=: tox -m docs

Behaveテスト

-m behaveによるBehaveテストでは、PG_MAJORバージョン12から18に基づくDockerイメージをビルドしてから、すべてのbehaveテストを実行します。実行にかなりの時間がかかる場合があるため、対象を特定のPostgresバージョンや、特定の機能群、ステップに限定したい場合もあります。

Postgresのバージョンを指定するには、依存するイメージのビルド環境の完全な名前を指定し、その後にbehave環境名を指定します。たとえば、Postgres 14を使用する場合は次のようにします。

tox -e pg14-docker-build,pg14-docker-behave-etcd-lin

一方、特定の機能をテストする場合は、behaveに位置引数を渡せます。次の例では、すべてのPostgresバージョンでwatchdogのbehave機能テストシナリオを実行します。

tox -m behave -- features/watchdog.feature

もちろん、この二つを組み合わせることもできます。

プルリクエストによる貢献

  1. リポジトリをフォークし、コードの変更を開発してテストします。
  2. 変更をユーザードキュメントに反映します。
  3. 変更の目的を明確に説明したプルリクエストを送信します。必要に応じて既存のIssueへのリンクを記載します。

プルリクエストには、できるだけ早くフィードバックをお送りします。

Patroniの開発を楽しんでください ;-)