他のバージョンの文書9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

51.3. ストリーミングレプリケーションプロトコル

ストリーミングレプリケーションを初期化するために、フロントエンドは開始メッセージにてreplicationパラメータを送信します。 ブール値のtrueがバックエンドに対して、SQL文ではなく小規模なレプリケーションコマンド群を発行できるようになる、walsenderモードに入るように伝えます。 walsenderモードでは簡易問い合わせプロトコルのみを使用することができます。 log_replication_commandsが有効であれば、レプリケーションコマンドはサーバログにログが残ります。 databaseを値として渡すことにより、 dbnameパラメータに指定したデータベースに接続することをwalsenderに教えます。 それにより、そのデータベースからの論理的レプリケーションとして使用する接続が可能となります。

レプリケーションコマンドをテストするために、replicationオプションを含む接続文字列を使用して、psqlまたは他のlibpqによるレプリケーション接続を作成できます。 例を示します。

psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"

しかし、物理的レプリケーションのためにpg_receivexlogを使用し、論理的レプリケーションのためpg_recvlogicalを使用すれば、もっと有用なことが多いです。

walsenderモードで受け付けられるコマンドは以下の通りです。

IDENTIFY_SYSTEM

サーバに自身を識別することを要求します。 サーバは以下の4つのフィールドを持つ単一行の結果セットをもって応答します。

systemid (text)

クラスタを識別する一意なシステム識別子です。 これを使用してスタンバイを初期化するために使用するベースバックアップが同じクラスタに由来していることを検査することができます。

timeline (int4)

現在のタイムラインIDです。 同様にスタンバイがマスタと一貫性を持つことを検査するために使用されます。

xlogpos (text)

現在のxlogの吐き出し位置です。 ストリーミングを開始できるトランザクションログの既知の位置を得る際に有用です。

dbname (text)

接続したデータベース名またはNULLです。

TIMELINE_HISTORY tli

tliのタイムラインのため、サーバにタイムライン履歴ファイルの送付を要求します。 サーバは2列単一行の結果セットを返します。

filename (text)

タイムライン履歴ファイル名、例えば00000002.history

content (bytea)

ライムライン履歴ファイルの内容

CREATE_REPLICATION_SLOT slot_name { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin }

物理的または論理的レプリケーションスロットを作成します。 レプリケーションスロットの詳細は26.2.6. レプリケーションスロットを参照。

slot_name

作成するスロット名。 有効なレプリケーションスロット名でなければならない。 (26.2.6.1. レプリケーションスロットへの問い合わせと操作を参照)。

output_plugin

ロジカルデコーディングに使用される出力プラグイン名。 (47.6. ロジカルデコーディングの出力プラグインを参照)。

RESERVE_WAL

この物理的レプリケーションスロットが直ちにWALを予約することを指定します。 そうでなければ、WALはストリーミングレプリケーションクライアントからの接続に応じてだけ予約されます。

START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ]

サーバに対して、WALのストリーミングをXXX/XXX WAL時点から開始するよう指示します。 TIMELINEオプションが指定された場合、ストリーミングはtliのタイムラインから開始されます。 そうでなければ、サーバの現在のタイムラインが選択されます。 サーバが、例えば、要求されたWALの断片がすでに回収されているなど、エラーを返すことがありえます。 成功時サーバはCopyBothResponseメッセージで応答し、フロントエンドに対するWALストリームを開始します。

slot_nameを経由してスロット名が提供された場合、それはレプリケーションの進行として更新されます。 それによってサーバは、どのWALセグメントがまだスタンバイに必要か、hot_standby_feedbackのトランザクションはどれか、を感知します。

最新ではなくて、サーバの過去のタイムラインをクライアントが要求した場合、サーバは要求された開始時点から他のタイムラインに切り替えるまでの、全てのWALストリームを送付します。 クライアントが旧タイムラインの終点のストリームを要求した場合、サーバはCOPYモードに入らずにCommandCompleteをすぐに応答します。

最新でないタイムラインの全てのWALストリームを送付した後、サーバはCOPYモードを出ることによりストリームを終了します。 クライアントもCOPYモードを出ることにより承認した場合、サーバは2列単一行の結果セットを送付し、サーバにある次のタイムラインを示します。 最初の列は次のタイムラインID(int8型)であり、次の列は切り替えたXLOGの位置(text型)です。 通常切り替えた位置はWALストリームの終点ですが、昇格する前に再実行されなかった旧タイムラインからWALを送付するというまれな場合もあります。 最後に、サーバはCommandCompleteメッセージを送付し、新規のコマンドを受理できるようになります。

WALデータはCopyDataメッセージ群として送信されます。 (これにより他の情報を混在させることができます。 具体的にはサーバはストリーム開始後に失敗が起きた場合にErrorResponseメッセージを送信することができます。) サーバからクライアントへの各CopyDataメッセージのペイロード、は以下の書式のどれかを含みます。

XLogData (B)

Byte1('w')

メッセージをWALデータとして識別します。

Int64

このメッセージ内のWALの開始点。

Int64

サーバ上の現在のWAL終了点。

Int64

転送時点でのサーバのシステム時刻。 2000年1月1日午前0時からのマイクロ秒。

Byten

WALデータストリームの断片。

単一のWALレコードが2つのXLogDataメッセージに分かれることはありません。 しかしWALレコードがWALページ境界を跨る場合、継続レコードを用いてすでに分割されていますので、ページ境界で分割することができます。 言い換えると、先頭の主WALレコードとその継続レコードは、別のXLogDataメッセージとして分かれることがありえます。

プライマリキープアライブメッセージ(B)

Byte1('k')

このメッセージを送信元キープアライブとして識別します。

Int64

サーバ上の現在のWAL終端。

Int64

転送時点でのサーバのシステム時刻。 2000年1月1日午前0時からのマイクロ秒。

Byte1

タイムアウトによる切断を避けるため、クライアントがこのメッセージに即時に応答するべき方法の1つ。 0またはその他

以下のメッセージ書式の1つ(およびCopyDataメッセージのペイロード中のもの)を使用して、受理プロセスは送信者にいつでも応答できます。

スタンバイ状態の更新(F)

Byte1('r')

メッセージを受信側の状態更新として識別します。

Int64

スタンバイにおいて受信しディスクに書き込まれた最終WALバイト+1の場所。

Int64

スタンバイにおいてディスクに吐き出された最終WALバイト+1の場所。

Int64

スタンバイにおいて適用された最終WALバイト+1の場所。

Int64

転送時点でのクライアントのシステム時刻。 2000年1月1日午前0時からのマイクロ秒。

Byte1

値が1の場合、このメッセージにすぐ応答するように、クライアントはサーバへ要求します。 この方法は、接続がまだ保持されているか検査するために、サーバへのピング送信として使用できます。

ホットスタンバイフィードバックメッセージ(F)

Byte1('h')

メッセージをホットスタンバイのフィードバックメッセージとして識別します。

Int64

転送時点でのクライアントのシステム時刻。 2000年1月1日午前0時からのマイクロ秒

Int32

スタンバイの現在のxminです。 もはやホットスタンバイフィードバックがこの接続では送信されないという通知を、スタンバイが送信している場合、この値は0でしょう。 後ほど、0でないメッセージがフィードバック機構を再び開始します。

Int32

スタンバイの現在のエポックです。

START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ]

サーバに対して、XXX/XXXWAL時点から、論理的レプリケーションのWALストリームを開始するよう指示します。 例えば、要求されたWALがすでに回収された場合、サーバはエラーを返します。 サーバが、例えば、要求されたWALセクションがすでに回収されている場合、エラーを返すことがありえます。 成功時サーバはCopyBothResponseメッセージで応答し、フロントエンドに対するWALストリームを開始します。

CopyBothResponse内部のメッセージは、START_REPLICATION ... PHYSICALの記述と同じ書式です。

選択されたスロットに関連した出力プラグインは、出力ストリームの処理に使用されます。

SLOT slot_name

ストリームを変更したスロット名。 このパラメータは必須であり、LOGICALモードにおいてCREATE_REPLICATION_SLOTによって作成された、実在する論理的レプリケーションスロットに対応しなければなりません。

XXX/XXX

ストリームを開始するWAL時点。

option_name

レプリケーションスロットのロジカルデコーディング出力プラグインに渡すオプション名。

option_value

オプションの値。 文字列定数の形式。

DROP_REPLICATION_SLOT slot_name

レプリケーションスロットを削除し、サーバ側で準備した資源を解放します。 実行中の接続に現在スロットが使用中の場合、このコマンドは失敗します。

slot_name

削除するスロット名。

BASE_BACKUP [ LABEL 'label' ] [ PROGRESS ] [ FAST ] [ WAL ] [ NOWAIT ] [ MAX_RATE rate ] [ TABLESPACE_MAP ]

サーバにベースバックアップのストリーミングを始めるよう指示します。 システムはバックアップが開始される前に自動的にバックアップモードになり、バックアップが完了した時に取り出されます。 以下のオプションを受け付けることができます。

LABEL 'label'

バックアップのラベルを設定します。 指定がない場合、base backupというバックアップラベルが使用されます。 ラベルについての引用符付け規則は、standard_conforming_stringsを有効にした場合の標準SQLの文字列の規則と同じです。

PROGRESS

進行状況の報告を生成するために必要な情報を要求します。 これは、ストリームが完了するまでにどのくらいかかるかを計算するために使用することができる、各テーブル空間のヘッダ内の概算容量を返送します。 これは、転送を始める前のすべてのファイルサイズを1度数え上げることで計算されます。 これ自体が性能に与える悪影響があるかもしれません。 特に最初のデータがストリームされるまでにより多くの時間がかかる可能性があります。 データベースファイルはバックアップの間変更される可能性がありますので、容量は概算に過ぎず、概算時と実ファイルを送信するまでの間に増減される可能性があります。

FAST

高速チェックポイントを要求します。

WAL

バックアップ内に必要なWALセグメントを含めます。 ベースディレクトリtarファイルのpg_xlogディレクトリにある、バックアップの開始から終了までのすべてのファイルが含まれます。

NOWAIT

デフォルトでは、バックアップは必要な最終WALセグメントがアーカイブされるまで待機します。 ログアーカイブが有効でない場合は警告が発せられます。 NOWAITにより、必要なログが利用できるようになったことを確認することをクライアント側の責任として、この待機や警告が無効になります。

MAX_RATE rate

サーバからクライアントへ転送する単位時間当たりの最大データ容量を制限します(絞ります)。 予期される単位はkB/s(キロバイト/秒)です。 このオプションが指定された場合、値はゼロまたは32 kB以上1 GB以下でなければなりません。 ゼロが渡されるかオプションが指定されない場合、転送の制約は課されません。

TABLESPACE_MAP

ディレクトリpg_tblspcにあるシンボリックリンクに関する情報をtablespace_mapという名前のファイルに含めます。 テーブル空間マップファイルには、ディレクトリpg_tblspc/に存在する各シンボリックリンクの名前とそのシンボリックリンクのフルパスが含まれています。

バックアップを開始する時、サーバはまず2つの通常の結果セットを送信し、続けて1つ以上のCopyResponse結果を送信します。

最初の通常の結果セットには、1行2列という形でバックアップの開始位置が含まれます。 最初の列にはXLogRecPtr書式の開始位置が、2番目の列には対応するタイムラインIDが含まれます。

2番目の通常の結果セットには各テーブル空間に付き1行を持ちます。 この行のフィールドは以下の通りです。

spcoid (oid)

テーブル空間のOIDです。 ベースディレクトリの場合はNULLです。

spclocation (text)

テーブル空間ディレクトリのフルパスです。 ベースディレクトリの場合はNULLです。

size (int8)

進行状況報告が要求された場合は、テーブル空間の概算容量です。 要求されていない場合はNULLです。

2番目の通常の結果セットの後、1つ以上のCopyResponse結果が送信されます。 主データディレクトリ用に1つ、pg_defaultpg_global以外の追加のテーブル空間ごとに1つ送信されます。 CopyResponse結果内のデータは、テーブル空間の内容のtar形式(POSIX 1003.1-2008標準で規定されたustar交換形式に従う)ダンプです。 ただし標準で規定された最後の2つのゼロブロックは省略されています。 このtarデータが終わった後、最終の通常結果セットが送信されます。 結果セットには、開始位置と同じ書式のバックアップのWAL終了位置が含まれます。

データディレクトリと各テーブル空間のtarアーカイブには、そのディレクトリ内のファイルがPostgreSQLファイルかそのディレクトリに追加された他のファイルかに関係なく、すべて含まれます。 以下に除かれるファイルを示します。

  • postmaster.pid

  • postmaster.opts

  • PostgreSQLサーバの操作中に、種々の一時ファイルが作成されます。

  • サブディレクトリを含むpg_xlog。 バックアップがwalファイルを含めて実行される場合、合成された版のpg_xlogが含まれます。 これにはバックアップが動作するために必要なファイルのみが含まれ、残りの内容は含まれません。

  • pg_replslotが空ディレクトリとしてコピーされます。

  • 通常のファイルとディレクトリ以外のもの、シンボリックリンクや特殊なデバイスファイルは省略されます。 (pg_tblspc中のシンボリックリンクは保持されます。)

サーバ上の基盤となるファイルシステムがサポートする場合、所有者、グループ、ファイルのモードが設定されます。