ストリーミングレプリケーションを初期化するために、フロントエンドは開始メッセージにてreplication
パラメータを送信します。
ブール値のtrue
(またはon
、yes
、1
)がバックエンドに対して、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メッセージのペイロード、は以下の書式のどれかを含みます。
メッセージをWALデータとして識別します。
このメッセージ内のWALの開始点。
サーバ上の現在のWAL終了点。
転送時点でのサーバのシステム時刻。 2000年1月1日午前0時からのマイクロ秒。
n
WALデータストリームの断片。
単一のWALレコードが2つのXLogDataメッセージに分かれることはありません。 しかしWALレコードがWALページ境界を跨る場合、継続レコードを用いてすでに分割されていますので、ページ境界で分割することができます。 言い換えると、先頭の主WALレコードとその継続レコードは、別のXLogDataメッセージとして分かれることがありえます。
このメッセージを送信元キープアライブとして識別します。
サーバ上の現在のWAL終端。
転送時点でのサーバのシステム時刻。 2000年1月1日午前0時からのマイクロ秒。
タイムアウトによる切断を避けるため、クライアントがこのメッセージに即時に応答するべき方法の1つ。 0またはその他
以下のメッセージ書式の1つ(およびCopyDataメッセージのペイロード中のもの)を使用して、受理プロセスは送信者にいつでも応答できます。
メッセージを受信側の状態更新として識別します。
スタンバイにおいて受信しディスクに書き込まれた最終WALバイト+1の場所。
スタンバイにおいてディスクに吐き出された最終WALバイト+1の場所。
スタンバイにおいて適用された最終WALバイト+1の場所。
転送時点でのクライアントのシステム時刻。 2000年1月1日午前0時からのマイクロ秒。
値が1の場合、このメッセージにすぐ応答するように、クライアントはサーバへ要求します。 この方法は、接続がまだ保持されているか検査するために、サーバへのピング送信として使用できます。
メッセージをホットスタンバイのフィードバックメッセージとして識別します。
転送時点でのクライアントのシステム時刻。 2000年1月1日午前0時からのマイクロ秒
スタンバイの現在のグローバルのxminですが、すべてのレプリケーションスロットのcatalog_xminは除きます。 この値と次のcatalog_xminがいずれも0なら、この接続ではホットスタンバイのフィードバックはもう送信されないという通知として扱われます。 後でゼロでないメッセージによりフィードバック機構を再開することができます。
スタンバイのグローバルのxmin xidのエポックです。
スタンバイのすべてのレプリケーションスロットのcatalog_xminの最小値です。 スタンバイ上にcatalog_xminが存在しない、あるいはホットスタンバイのフィードバックが無効化されている場合は0に設定します。
スタンバイのcatalog_xmin xidのエポックです。
START_REPLICATION
SLOT
slot_name
LOGICAL
XXX/XXX
[ ( option_name
[ option_value
] [, ...] ) ]
サーバに対して、XXX/XXX
WAL時点から、論理的レプリケーションの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
バックアップマニュフェストに含まれている各ファイルに適用するチェックサムアルゴリズムを指定します。
現在使用可能なアルゴリズムは、NONE
、CRC32C
、SHA224
, SHA256
、SHA384
、SHA512
です。
デフォルトは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_default
、pg_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_dynshmem
、pg_notify
、pg_replslot
、pg_serial
、pg_snapshots
、pg_stat_tmp
、pg_subtrans
は(それがシンボリックリンクであったとしても)空のディレクトリとしてコピーされます。
シンボリックリンク(上記で列挙したディレクトリは除きます)や特殊デバイスファイルなど、通常のファイルとディレクトリ以外のものは省略されます。
(pg_tblspc
中のシンボリックリンクは保持されます。)
サーバ上の基盤となるファイルシステムがサポートする場合、所有者、グループ、ファイルのモードが設定されます。