他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 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

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

ストリーミングレプリケーションを初期化するために、フロントエンドは開始メッセージにてreplicationパラメータを送信します。 ブール値のtrue(またはonyes1)がバックエンドに対して、SQL文ではなく小規模なレプリケーションコマンド群を発行できるようになる、物理レプリケーションのwalsenderモードに入るように伝えます。

replicationパラメータに対する値としてdatabaseを渡すことは、dbnameパラメータで指定されたデータベースに接続して、バックエンドにロジカルレプリケーションのwalsendeモードに入ることを指示します。 ロジカルレプリケーションwalsenderモードでは、以下に示すレプリケーションコマンドを通常のSQLコマンドと同様に実行できます。

物理レプリケーション、ロジカルレプリケーションいずれかのwalsenderモードでは、簡易問い合わせプロトコルのみ使用できます。

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

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

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

log_replication_commandsが有効であるとき、サーバログにレプリケーションコマンドが記録されます。

レプリケーションモードで受け付けられるコマンドは以下の通りです。

IDENTIFY_SYSTEM

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

systemid (text)

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

timeline (int4)

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

xlogpos (text)

現在のWALの吐き出し位置です。 ストリーミングを開始できる先行書き込みログの既知の位置を得る際に有用です。

dbname (text)

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

SHOW name

実行時パラメータの現在の設定を送信するようサーバに要求します。 これはSQLコマンドSHOWと同等です。

name

実行時パラメータの名前です。 利用できるパラメータは第20章に記述されています。

TIMELINE_HISTORY tli

tliのタイムラインのため、サーバにタイムライン履歴ファイルの送付を要求します。 サーバは2列単一行の結果セットを返します。 フィールドにはtextの印が付けられていますが、実際には符号化変換なしの生のバイトが返ります。

filename (text)

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

content (text)

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

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT ] }

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

slot_name

作成するスロット名。 有効なレプリケーションスロット名でなければならない。 (27.2.6.1を参照)。

output_plugin

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

TEMPORARY

このレプリケーションスロットが一時スロットであることを指定します。 一時スロットはディスクに保存されず、エラー発生時またはセッション終了時に自動的に削除されます。

RESERVE_WAL

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

EXPORT_SNAPSHOT
NOEXPORT_SNAPSHOT
USE_SNAPSHOT

論理スロットの初期化時に作成されたスナップショットの処理について決定します。 デフォルトのEXPORT_SNAPSHOTはスナップショットが他のセッションで利用できるようエクスポートします。 このオプションはトランザクションの内側で使用することはできません。 USE_SNAPSHOTはこのコマンドを実行している現在のトランザクションでスナップショットを利用します。 このオプションはトランザクション内で使用しなければならず、CREATE_REPLICATION_SLOTがそのトランザクション内で実行される最初のコマンドでなければなりません。 最後に、NOEXPORT_SNAPSHOTは論理デコーディングで通常通りにスナップショットを使用するだけで、他には何もしません。

このコマンドへの応答として、サーバは以下のフィールドを含む1行の結果集合を送信します。

slot_name (text)

新しく作成されたレプリケーションスロットの名前です。

consistent_point (text)

スロットが一貫性のある状態になった時点のWAL位置です。 これが、このスロット上でストリーミングを開始できる最も早い場所となります。

snapshot_name (text)

このコマンドでエクスポートされるスナップショットの識別子です。 スナップショットは、この接続上で新しいコマンドが実行されるか、レプリケーション接続が閉じられるまで有効です。 作成されたのが物理スロットの場合はNULLになります。

output_plugin (text)

新しく作成されたレプリケーションスロットが使用する出力プラグインの名前です。 作成されたのが物理スロットの場合はNULLになります。

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モード全体をスキップします。

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

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ですが、すべてのレプリケーションスロットのcatalog_xminは除きます。 この値と次のcatalog_xminがいずれも0なら、この接続ではホットスタンバイのフィードバックはもう送信されないという通知として扱われます。 後でゼロでないメッセージによりフィードバック機構を再開することができます。

Int32

スタンバイのグローバルのxmin xidのエポックです。

Int32

スタンバイのすべてのレプリケーションスロットのcatalog_xminの最小値です。 スタンバイ上にcatalog_xminが存在しない、あるいはホットスタンバイのフィードバックが無効化されている場合は0に設定します。

Int32

スタンバイのcatalog_xmin xidのエポックです。

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

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

CopyBothResponse内部のメッセージは、2つのCommandCompleteメッセージを含めてSTART_REPLICATION ... PHYSICALの記述と同じ書式です。

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

SLOT slot_name

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

XXX/XXX

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

option_name

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

option_value

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

DROP_REPLICATION_SLOT slot_name [ WAIT ]

レプリケーションスロットを削除し、サーバ側で準備した資源を解放します。 このスロットが、walsenderが接続しているデータベース以外のデータベースで作成された論理スロットの場合、このコマンドは失敗します。

slot_name

削除するスロット名。

WAIT

このオプションを使用すると、スロットが使用中の時に、スロットの使用が終わるまでコマンドを待機させます。 デフォルトの動作ではエラーを発生させます。

BASE_BACKUP [ LABEL 'label' ] [ PROGRESS ] [ FAST ] [ WAL ] [ NOWAIT ] [ MAX_RATE rate ] [ TABLESPACE_MAP ] [ NOVERIFY_CHECKSUMS ] [ MANIFEST manifest_option ] [ MANIFEST_CHECKSUMS checksum_algorithm ]

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

LABEL 'label'

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

PROGRESS

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

FAST

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

WAL

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

NOWAIT

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

MAX_RATE rate

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

TABLESPACE_MAP

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

NOVERIFY_CHECKSUMS

デフォルトでは、チェックサムが有効である場合、ベースバックアップ中にチェックサムが検証されます。 NOVERIFY_CHECKSUMSを指定すると、この検証を無効にします。

MANIFEST manifest_option

このオプションをyesまたはforce-encodeの値で設定すると、バックアップマニフェストが作成され、バックアップとともに送信されます。 マニフェストは、含まれる可能性のあるWALファイルを除きバックアップ内に存在するすべてのファイルのリストです。 また、サイズ、最終更新時刻、オプションでファイル毎のチェックサムも格納します。 force-encodeの値は、全てのファイル名を強制的に16進数でエンコーディングします。 それ以外の場合、このタイプのエンコードは、名前が非UTF-8オクテットシーケンスであるファイルに対してのみ実行されます。 force-encodeは、主にテスト目的で使用されており、バックアップマニュフェストを読み取るクライアントがこのケースを処理できることを確認するために使用されます。 以前のリリースとの互換性を保つため、デフォルトは、MANIFEST 'no'です。

MANIFEST_CHECKSUMS checksum_algorithm

バックアップマニュフェストに含まれている各ファイルに適用するチェックサムアルゴリズムを指定します。 現在使用可能なアルゴリズムは、NONECRC32CSHA224, SHA256SHA384SHA512です。 デフォルトはCRC32Cです。

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

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

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

spcoid (oid)

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

spclocation (text)

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

size (int8)

進行状況の報告が要求された場合は、テーブル空間の概算容量です(キロバイト(1024バイト)単位)。 要求されていない場合はNULLです。

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

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

  • postmaster.pid

  • postmaster.opts

  • pg_internal.init(複数のディレクトリに在ります)

  • PostgreSQLサーバの操作中に作成される種々の一時ファイルおよびディレクトリで、pgsql_tmpで始まるすべてのファイルおよびディレクトリ、および一時リレーション。

  • ログを取らないリレーション。ただし、リカバリでログを取らないリレーションの再作成に必要なinitフォークは除かれない。

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

  • pg_dynshmempg_notifypg_replslotpg_serialpg_snapshotspg_stat_tmppg_subtransは(それがシンボリックリンクであったとしても)空のディレクトリとしてコピーされます。

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

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