バージョンごとのドキュメント一覧

pg_createsubscriber

pg_createsubscriber <refpurpose>convert a physical replica into a new logical replica</refpurpose> — 物理レプリカを新しい論理レプリカに変換する

概要

pg_createsubscriber [option...] { -d | --database }dbname { -D | --pgdata }datadir { -P | --publisher-server }connstr

説明

<title>Description</title>

<application>pg_createsubscriber</application> creates a new logical replica from a physical standby server. All tables in the specified database are included in the logical replication setup. A pair of publication and subscription objects are created for each database. It must be run at the target server. pg_createsubscriberは、物理スタンバイサーバから新しい論理レプリカを作成します。 指定されたデータベース内のすべてのテーブルが論理レプリケーション設定に含まれます。 各データベースに対して、パブリケーションとサブスクリプションのオブジェクトのペアが作成されます。 ターゲットサーバで実行する必要があります。

After a successful run, the state of the target server is analogous to a fresh logical replication setup. The main difference between the logical replication setup and <application>pg_createsubscriber</application> is how the data synchronization is done. <application>pg_createsubscriber</application> does not copy the initial table data. It does only the synchronization phase, which ensures each table is brought up to a synchronized state. 実行が成功した後のターゲットサーバの状態は、新しいロジカルレプリケーションセットアップに似ています。 ロジカルレプリケーションセットアップとpg_createsubscriberの間の主な差は、データ同期化が行われる方法です。 pg_createsubscriberは初期テーブルデータをコピーしません。 各テーブルが同期化された状態になることを保証する同期化フェーズのみを行います。

<application>pg_createsubscriber</application> targets large database systems because in logical replication setup, most of the time is spent doing the initial data copy. Furthermore, a side effect of this long time spent synchronizing data is usually a large amount of changes to be applied (that were produced during the initial data copy), which increases even more the time when the logical replica will be available. For smaller databases, <link linkend="logical-replication-row-filter-initial-data-sync"> initial data synchronization</link> is recommended. pg_createsubscriberは大きなデータベースシステムを対象としています。 これは、ロジカルレプリケーションセットアップではほとんどの時間が最初のデータコピーに費やされるためです。 さらに、データの同期に費やされるこの長い時間の副作用は、通常、適用される変更が大きな量になること(最初のデータコピー中に生成されたもの)であり、これは、ロジカルレプリカが利用可能になるまでの時間をさらに増加させます。 小規模なデータベースの場合は、初期データ同期化をお勧めします。

オプション

<title>Options</title>

<application>pg_createsubscriber</application> accepts the following command-line arguments: pg_createsubscriberは、以下のコマンドライン引数を受け付けます。

-d dbname
--database=dbname

The name of the database in which to create a subscription. Multiple databases can be selected by writing multiple <option>-d</option> switches. サブスクリプションを作成するデータベースの名前。 複数の-dスイッチを記述することによって、複数のデータベースを選択できます。

-D directory
--pgdata=directory

The target directory that contains a cluster directory from a physical replica. 物理レプリカのクラスタディレクトリを含むターゲットディレクトリ。

-n
--dry-run

Do everything except actually modifying the target directory. ターゲットディレクトリを実際に更新する以外はすべてのことを行います。

-p port
--subscriber-port=port

The port number on which the target server is listening for connections. Defaults to running the target server on port 50432 to avoid unintended client connections. ターゲットサーバが接続をリスニングするポート番号。 デフォルトでは、ターゲットサーバはポート50432で実行され、意図しないクライアント接続を回避します。

-P connstr
--publisher-server=connstr

The connection string to the publisher. For details see <xref linkend="libpq-connstring"/>. パブリッシャへの接続文字列。 詳細は32.1.1を参照してください。

-s dir
--socketdir=dir

The directory to use for postmaster sockets on target server. The default is current directory. ターゲットサーバ上のpostmasterソケットに使用するディレクトリ。 デフォルトは現在のディレクトリです。

-t seconds
--recovery-timeout=seconds

The maximum number of seconds to wait for recovery to end. Setting to 0 disables. The default is 0. リカバリーが終了するまでの最大待ち時間(秒)。 0に設定すると無効になります。 デフォルトは0です。

-U username
--subscriber-username=username

The user name to connect as on target server. Defaults to the current operating system user name. ターゲット・サーバに接続するためのユーザ名。 デフォルトは、現在のオペレーティングシステムユーザ名です。

-v
--verbose

Enables verbose mode. This will cause <application>pg_createsubscriber</application> to output progress messages and detailed information about each step to standard error. Repeating the option causes additional debug-level messages to appear on standard error. 冗長モードを有効にします。 これによりpg_createsubscriberは進捗メッセージと各ステップの詳細情報を標準エラーに出力します。 オプションを繰り返すと、追加のデバッグレベルメッセージが標準エラーに出力されます。

--config-file=filename

Use the specified main server configuration file for the target data directory. <application>pg_createsubscriber</application> internally uses the <application>pg_ctl</application> command to start and stop the target server. It allows you to specify the actual <filename>postgresql.conf</filename> configuration file if it is stored outside the data directory. ターゲットデータディレクトリ用に指定されたメインサーバの設定ファイルを使用します。 pg_createsubscriberは、内部的にpg_ctlコマンドをスタートに使用し、ターゲットサーバを起動、停止します。 データディレクトリ外に保存されている場合は、実際のpostgresql.conf設定ファイルを指定できます。

--publication=name

The publication name to set up the logical replication. Multiple publications can be specified by writing multiple <option>&#45;-publication</option> switches. The number of publication names must match the number of specified databases, otherwise an error is reported. The order of the multiple publication name switches must match the order of database switches. If this option is not specified, a generated name is assigned to the publication name. 論理レプリケーションを設定するパブリケーション名。 複数の--publicationスイッチを指定することで、複数のパブリケーションを指定できます。 パブリケーション名の数は、指定されたデータベースの数と一致する必要があります。 一致しない場合、エラーが報告されます。 パブリケーション名のスイッチの順序は、データベースのスイッチの順序と一致する必要があります。 このオプションを指定しない場合、生成された名前がパブリケーション名に割り当てられます。

--replication-slot=name

The replication slot name to set up the logical replication. Multiple replication slots can be specified by writing multiple <option>&#45;-replication-slot</option> switches. The number of replication slot names must match the number of specified databases, otherwise an error is reported. The order of the multiple replication slot name switches must match the order of database switches. If this option is not specified, the subscription name is assigned to the replication slot name. 論理レプリケーションを設定するレプリケーションスロット名。 複数の--replication-slotスイッチを書くことで、複数のレプリケーションスロットを指定できます。 パブリケーションスロット名の数は、指定されたデータベースの数と一致する必要があります。 一致しない場合、エラーが報告されます。 複数のレプリケーションスロット名スイッチの順序は、データベーススイッチの順序と一致する必要があります。 このオプションを指定しない場合、サブスクリプション名がレプリケーションスロット名に割り当てられます。

--subscription=name

The subscription name to set up the logical replication. Multiple subscriptions can be specified by writing multiple <option>&#45;-subscription</option> switches. The number of subscription names must match the number of specified databases, otherwise an error is reported. The order of the multiple subscription name switches must match the order of database switches. If this option is not specified, a generated name is assigned to the subscription name. 論理レプリケーションを設定するサブスクリプション名。 複数の--subscriptionスイッチを指定することで、複数のサブスクリプションを指定できます。 サブスクリプション名の数は、指定されたデータベースの数と一致する必要があります。 一致しない場合、エラーが報告されます。 複数のサブスクリプション名スイッチの順序は、データベーススイッチの順序と一致する必要があります。 このオプションを指定しない場合、生成された名前がサブスクリプション名に割り当てられます。

-V
--version

Print the <application>pg_createsubscriber</application> version and exit. pg_createsubscriberのバージョンを出力して終了します。

-?
--help

Show help about <application>pg_createsubscriber</application> command line arguments, and exit. pg_createsubscriberコマンドライン引数についてのヘルプを表示し、終了します。

注釈

<title>Notes</title>

前提条件

<title>Prerequisites</title>

There are some prerequisites for <application>pg_createsubscriber</application> to convert the target server into a logical replica. If these are not met, an error will be reported. The source and target servers must have the same major version as the <application>pg_createsubscriber</application>. The given target data directory must have the same system identifier as the source data directory. The given database user for the target data directory must have privileges for creating <link linkend="sql-createsubscription">subscriptions</link> and using <link linkend="pg-replication-origin-advance"><function>pg_replication_origin_advance()</function></link>. pg_createsubscriberがターゲットサーバを論理レプリカに変換するためには、いくつかの前提条件があります。 これらの条件が満たされない場合、エラーが報告されます。 ソースサーバとターゲットサーバはpg_createsubscriberと同じメジャーバージョンでなければなりません。 指定されたターゲットデータディレクトリは、ソースデータディレクトリと同じシステム識別子を持つ必要があります。 指定されたターゲットデータディレクトリのデータベースユーザは、サブスクリプションの作成pg_replication_origin_advance()を使用するための権限を持たなければなりません。

The target server must be used as a physical standby. The target server must have <xref linkend="guc-max-replication-slots"/> and <xref linkend="guc-max-logical-replication-workers"/> configured to a value greater than or equal to the number of specified databases. The target server must have <xref linkend="guc-max-worker-processes"/> configured to a value greater than the number of specified databases. The target server must accept local connections. ターゲットサーバは、物理スタンバイとして使用する必要があります。 ターゲットサーバのmax_replication_slotsmax_logical_replication_workersは、指定されたデータベースの数以上の値に設定されている必要があります。 ターゲットサーバのmax_worker_processesは、指定されたデータベースの数以上の値に設定されている必要があります。 ターゲットサーバは、ローカル接続を受け入れる必要があります。

The source server must accept connections from the target server. The source server must not be in recovery. The source server must have <xref linkend="guc-wal-level"/> as <literal>logical</literal>. The source server must have <xref linkend="guc-max-replication-slots"/> configured to a value greater than or equal to the number of specified databases plus existing replication slots. The source server must have <xref linkend="guc-max-wal-senders"/> configured to a value greater than or equal to the number of specified databases and existing WAL sender processes. ソースサーバはターゲットサーバからの接続を受け入れなければなりません。 ソースサーバはリカバリ状態であってはなりません。 ソースサーバはwal_levellogicalにする必要があります。 ソースサーバは、指定されたデータベースの数に既存のレプリケーションスロットを加えた値以上にmax_replication_slotsを設定する必要があります。 ソースサーバは、指定されたデータベースの数と既存のWAL送信プロセス以上の値にmax_wal_sendersを設定する必要があります。

警告

<title>Warnings</title>

If <application>pg_createsubscriber</application> fails after the target server was promoted, then the data directory is likely not in a state that can be recovered. In such case, creating a new standby server is recommended. ターゲットサーバの昇格後にpg_createsubscriberが失敗した場合、データディレクトリはリカバリ可能な状態ではない可能性が高いです。 このような場合は、新しいスタンバイサーバを作成することをお勧めします。

<application>pg_createsubscriber</application> usually starts the target server with different connection settings during transformation. Hence, connections to the target server should fail. pg_createsubscriberは通常、変換中に異なる接続設定でターゲットサーバを起動します。 したがって、ターゲットサーバへの接続は失敗するはずです。

Since DDL commands are not replicated by logical replication, avoid executing DDL commands that change the database schema while running <application>pg_createsubscriber</application>. If the target server has already been converted to logical replica, the DDL commands might not be replicated, which might cause an error. DDLコマンドは論理レプリケーションではレプリケートされないため、pg_createsubscriberの実行中にデータベーススキーマを変更するDDLコマンドは実行しないでください。 ターゲットサーバがすでに論理レプリカに変換されている場合、DDLコマンドはレプリケートされない可能性があり、エラーが発生する可能性があります。

If <application>pg_createsubscriber</application> fails while processing, objects (publications, replication slots) created on the source server are removed. The removal might fail if the target server cannot connect to the source server. In such a case, a warning message will inform the objects left. If the target server is running, it will be stopped. 処理中にpg_createsubscriberが失敗した場合、ソースサーバ上に作成されたオブジェクト(パブリケーション、レプリケーションスロット)は削除されます。 ターゲットサーバがソースサーバに接続できない場合、削除は失敗する可能性があります。 このような場合、警告メッセージが残されたオブジェクトを通知します。 ターゲットサーバが実行中の場合は、停止されます。

If the replication is using <xref linkend="guc-primary-slot-name"/>, it will be removed from the source server after the logical replication setup. レプリケーションがprimary_slot_nameを使用している場合、論理レプリケーション設定後にソースサーバから削除されます。

If the target server is a synchronous replica, transaction commits on the primary might wait for replication while running <application>pg_createsubscriber</application>. ターゲットサーバが同期レプリカの場合、pg_createsubscriberの実行中にプライマリでのトランザクションコミットがレプリケーションを待つことがあります。

<application>pg_createsubscriber</application> sets up logical replication with two-phase commit disabled. This means that any prepared transactions will be replicated at the time of <command>COMMIT PREPARED</command>, without advance preparation. Once setup is complete, you can manually drop and re-create the subscription(s) with the <link linkend="sql-createsubscription-params-with-two-phase"><literal>two_phase</literal></link> option enabled. pg_createsubscriberは二相コミットを無効にしてロジカルレプリケーションを設定します。 これは、準備されたトランザクションが事前の準備なしにCOMMIT PREPAREDの時点で複製されることを意味します。 セットアップが完了したら、two_phaseオプションを有効にしてサブスクリプションを手動で削除し、再作成することができます。

<application>pg_createsubscriber</application> changes the system identifier using <application>pg_resetwal</application>. It would avoid situations in which the target server might use WAL files from the source server. If the target server has a standby, replication will break and a fresh standby should be created. pg_createsubscriberpg_resetwalを使用してシステム識別子を変更します。 これは、ターゲットサーバがソースサーバからのWALファイルを使用する可能性がある状況を回避します。 ターゲットサーバにスタンバイがある場合、レプリケーションが中断され、新しいスタンバイを作成する必要があります。

どうやって動くのか

<title>How It Works</title>

The basic idea is to have a replication start point from the source server and set up a logical replication to start from this point: 基本的な考え方は、ソースサーバからレプリケーションの開始ポイントを設定し、このポイントから開始する論理レプリケーションをセットアップすることです。

  1. Start the target server with the specified command-line options. If the target server is already running, <application>pg_createsubscriber</application> will terminate with an error. 指定したコマンドラインオプションでターゲットサーバを起動します。 ターゲットサーバがすでに実行中の場合、pg_createsubscriberはエラーで終了します。

  2. Check if the target server can be converted. There are also a few checks on the source server. If any of the prerequisites are not met, <application>pg_createsubscriber</application> will terminate with an error. ターゲットサーバを変換できるかどうかをチェックします。 ソースサーバに対してもいくつかのチェックが行われます。 前提条件のいずれかが満たされていない場合、pg_createsubscriberはエラーで終了します。

  3. Create a publication and replication slot for each specified database on the source server. Each publication is created using <link linkend="sql-createpublication-params-for-all-tables"><literal>FOR ALL TABLES</literal></link>. If <option>publication-name</option> option is not specified, it has the following name pattern: <quote><literal>pg_createsubscriber_%u_%x</literal></quote> (parameter: database <parameter>oid</parameter>, random <parameter>int</parameter>). If <option>replication-slot-name</option> is not specified, the replication slot has the following name pattern: <quote><literal>pg_createsubscriber_%u_%x</literal></quote> (parameters: database <parameter>oid</parameter>, random <parameter>int</parameter>). These replication slots will be used by the subscriptions in a future step. The last replication slot LSN is used as a stopping point in the <xref linkend="guc-recovery-target-lsn"/> parameter and by the subscriptions as a replication start point. It guarantees that no transaction will be lost. ソースサーバ上の指定されたデータベースごとに、パブリケーションとレプリケーションスロットを作成します。 各パブリケーションはFOR ALL TABLESを使用して作成されます。 publication-nameオプションが指定されていない場合、次の名前パターンになります。 pg_createsubscriber_%u_%x(パラメータ: データベースoid、ランダムint)。replication-slot-nameが指定されない場合、レプリケーションスロットは次の名前パターンになります。 pg_createsubscriber_%u_%x(パラメータ: データベースoid、ランダムint)。 これらのレプリケーション スロットは、今後の手順でサブスクリプションによって使用されます。 最後のレプリケーションスロットLSNは、recovery_target_lsnパラメータの停止点として、また、サブスクリプションによってレプリケーション開始点として使用されます。 これにより、トランザクションが失われることがなくなります。

  4. Write recovery parameters into the target data directory and restart the target server. It specifies an LSN (<xref linkend="guc-recovery-target-lsn"/>) of the write-ahead log location up to which recovery will proceed. It also specifies <literal>promote</literal> as the action that the server should take once the recovery target is reached. Additional <link linkend="runtime-config-wal-recovery-target">recovery parameters</link> are added to avoid unexpected behavior during the recovery process such as end of the recovery as soon as a consistent state is reached (WAL should be applied until the replication start location) and multiple recovery targets that can cause a failure. This step finishes once the server ends standby mode and is accepting read-write transactions. If <option>&#45;-recovery-timeout</option> option is set, <application>pg_createsubscriber</application> terminates if recovery does not end until the given number of seconds. ターゲットデータディレクトリにリカバリパラメータを書き込み、ターゲット・サーバを再起動します。 リカバリが進行するまでの先行書き込みログの場所のLSN(recovery_target_lsn)を指定します。 また、リカバリ対象に到達した時点でサーバが取るべきアクションとしてpromoteを指定します。 整合性のある状態に到達したらすぐにリカバリを終了する(WALはレプリケーション開始位置まで適用されるべきです)、複数のリカバリターゲットが障害を引き起こす可能性があるなど、リカバリプロセス中の予期しない動作を回避するために、リカバリパラメータが追加されます。 このステップは、サーバがスタンバイモードを終了し、読み取り/書き込みトランザクションを受け入れると完了します。 --recovery-timeoutオプションが設定されている場合、指定された秒数が経過するまでリカバリが終了しない場合、pg_createsubscriberは終了します。

  5. Create a subscription for each specified database on the target server. If <option>subscription-name</option> is not specified, the subscription has the following name pattern: <quote><literal>pg_createsubscriber_%u_%x</literal></quote> (parameters: database <parameter>oid</parameter>, random <parameter>int</parameter>). It does not copy existing data from the source server. It does not create a replication slot. Instead, it uses the replication slot that was created in a previous step. The subscription is created but it is not enabled yet. The reason is the replication progress must be set to the replication start point before starting the replication. ターゲットサーバ上の指定した各データベースに対してサブスクリプションを作成します。 subscription-nameが指定されない場合、サブスクリプションは次の名前パターンになります。 pg_createsubscriber_%u_%x(パラメータ: データベースoid、ランダムint)。 ソースサーバから既存のデータをコピーしません。 レプリケーションスロットは作成されません。 代わりに、前の手順で作成したレプリケーションスロットを使用します。 サブスクリプションは作成されましたが、まだ有効ではありません。 これは、レプリケーションを開始する前に、レプリケーションの進行状況をレプリケーション開始点に設定する必要があるためです。

  6. Drop publications on the target server that were replicated because they were created before the replication start location. It has no use on the subscriber. レプリケーション開始位置より前に作成されていたために複製された、ターゲットサーバ上のパブリケーション削除します。 これはサブスクライバ側では使用されません。

  7. Set the replication progress to the replication start point for each subscription. When the target server starts the recovery process, it catches up to the replication start point. This is the exact LSN to be used as a initial replication location for each subscription. The replication origin name is obtained since the subscription was created. The replication origin name and the replication start point are used in <link linkend="pg-replication-origin-advance"><function>pg_replication_origin_advance()</function></link> to set up the initial replication location. 各サブスクリプションのレプリケーション開始点にレプリケーションの進行状況を設定します。 ターゲットサーバがリカバリプロセスを開始すると、レプリケーションの開始時点まで追いつきます。 これは、各サブスクリプションの初期レプリケーションの場所として使用される正確なLSNです。 サブスクリプションが作成されたため、レプリケーションオリジン名が取得されます。 レプリケーションオリジン名とレプリケーション開始点は、pg_replication_origin_advance()で初期レプリケーション場所を設定するために使用されます。

  8. Enable the subscription for each specified database on the target server. The subscription starts applying transactions from the replication start point. ターゲットサーバ上の指定した各データベースのサブスクリプションを使用可能にします。 サブスクリプションは、レプリケーション開始ポイントからトランザクションを適用し始めます。

  9. If the standby server was using <xref linkend="guc-primary-slot-name"/>, it has no use from now on so drop it. スタンバイサーバがprimary_slot_nameを使用していた場合、それは今後は使用されないので削除します。

  10. If the standby server contains <link linkend="logicaldecoding-replication-slots-synchronization">failover replication slots</link>, they cannot be synchronized anymore, so drop them. スタンバイサーバにフェイルオーバーレプリケーションスロットがある場合、もはや同期できないので削除します。

  11. Update the system identifier on the target server. The <xref linkend="app-pgresetwal"/> is run to modify the system identifier. The target server is stopped as a <command>pg_resetwal</command> requirement. ターゲットサーバのシステム識別子を更新します。 pg_resetwalが実行され、システム識別子が変更されます。 pg_resetwalの必要条件なので、ターゲットサーバは停止されます。

<title>Examples</title>

To create a logical replica for databases <literal>hr</literal> and <literal>finance</literal> from a physical replica at <literal>foo</literal>: fooでの物理レプリカからデータベースhrfinanceの論理レプリカを作成するには、次のようにします。

$ pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance

関連項目

<title>See Also</title> pg_basebackup