Usage ===== このセクションでは、pglogicalレプリケーション拡張機能の基本的な使用法について説明します。 クイックセットアップ -------------------- 最初に、論理デコードをサポートするようにPostgreSQLサーバーを適切に構成する必要があります。 :: wal_level = logical max_worker_processes = 10 # one per database needed on provider node # one per node needed on subscriber node max_replication_slots = 10 # one per node needed on provider node max_wal_senders = 10 # one per node needed on provider node shared_preload_libraries = pglogical PostgreSQL 9.5+これは9.4では動作しませんを使用しており、最後/最初の更新の勝利で競合解決を処理する場合 :ref:`Conflicts ` を参照してください、この追加オプションをpostgresql.confに追加できます。 :: track_commit_timestamp = on # needed for last/first update wins conflict resolution # property available in PostgreSQL 9.5+ ``pg_hba.conf`` は、ローカルホストからの論理レプリケーション接続を許可する必要があります。 PostgreSQL 9.6までは、論理レプリケーション接続は\ ``pg_hba.conf`` の\ ``replication`` キーワードを使用して管理されていました。 PostgreSQL 10以降では、論理レプリケーション接続は、プロバイダーデータベースへの通常の接続として\ ``pg_hba.conf`` によって処理されます。 次に、\ ``pglogical`` 拡張機能をすべてのノードにインストールする必要があります。 :: CREATE EXTENSION pglogical; PostgreSQL 9.4を使用する場合、\ ``pglogical_origin`` 拡張機能もそのノードにインストールする必要があります。 :: CREATE EXTENSION pglogical_origin; 次に、プロバイダーノードを作成します。 :: SELECT pglogical.create_node( node_name := provider1, dsn := host=providerhost port=5432 dbname=db ); ``public`` スキーマのすべてのテーブルを\ ``default`` レプリケーションセットに追加します。 :: SELECT pglogical.replication_set_add_all_tables(default, ARRAY[public]); オプションで、追加のレプリケーションセットを作成し、テーブルを追加することもできます。 :ref:`レプリケーションセット <レプリケーションセット>` を参照してください。 通常、サブスクライブする前にレプリケーションセットを作成して、単一の初期トランザクションでの初期レプリケーションセットアップ中にすべてのテーブルが同期されるようにすることをお勧めします。ただし、大規模なデータベースのユーザーは、代わりに、より適切な制御のためにそれらをインクリメンタルに作成することを希望する場合があります。 プロバイダーノードがセットアップされると、サブスクライバーはそれにサブスクライブできます。最初にサブスクライバノードを作成する必要があります。 :: SELECT pglogical.create_node( node_name := subscriber1, dsn := host=thishost port=5432 dbname=db ); そして最後に、サブスクライバーノードで、バックグラウンドで同期とレプリケーションプロセスを開始するサブスクリプションを作成できます。 :: SELECT pglogical.create_subscription( subscription_name := subscription1, provider_dsn := host=providerhost port=5432 dbname=db ); SELECT pglogical.wait_for_subscription_sync_complete(subscription1); ベースバックアップを使用してサブスクライバノードの作成 ------------------------------------------------------ SQLレベルのノードとサブスクリプションの作成に加えて、pglogicalは、 ``pg_basebackup`` でプロバイダーのクローンを作成し、pglogicalサブスクライバーとして起動することによるサブスクライバーの作成もサポートしています。これは、 ``pglogical_create_subscriber`` ツールを使用して実行されます。 ``--help`` 出力を参照してください。 ``pglogical.create_subscription`` のデータ同期オプションとは異なり、このクローンはレプリケーションセットを無視し、すべてのデータベースのすべてのテーブルをコピーします。ただし、多くの場合、特に高帯域幅リンクでは、はるかに高速です。 ノード管理 ---------- SQLインターフェイスを使用して、ノードを動的に追加および削除できます。 - ``pglogical.create_node(node_name name, dsn text)`` ノードを作成します。 パラメーター - ``node_name`` -新しいノードの名前、データベースごとに1つのノードのみが許可されます - ``dsn`` -ノードへの接続文字列、プロバイダーであるノードの場合、これは外部から到達可能である必要があります - ``pglogical.drop_node(node_name name, ifexists bool)`` pg論理ノードを削除します。 パラメーター - ``node_name`` -既存のノードの名前 - ``ifexists`` -trueの場合、サブスクリプションが存在しない場合にエラーはスローされません、デフォルトはfalse - ``pglogical.alter_node_add_interface(node_name name, interface_name name, dsn text)`` ノードにインターフェイスを追加します。 ノードが作成されると、そのインタフェースも\ ``create_node`` で指定された\ ``dsn`` とノードと同じ名前で作成されます。このインターフェイスを使用すると、さまざまな接続文字列を使用して代替インターフェイスを既存のノードに追加できます。 パラメーター - ``node_name`` -既存のノードの名前 - ``interface_name`` -追加する新しいインターフェイスの名前 - ``dsn`` -新しいインターフェイスに使用されるノードへの接続文字列 - ``pglogical.alter_node_drop_interface(node_name name, interface_name name)`` 既存のインターフェイスをノードから削除します。 パラメーター - ``node_name`` - 既存のノードの名前 - ``interface_name`` - 既存のインターフェイスの名前 サブスクリプション管理 ---------------------- - ``pglogical.create_subscription(subscription_name name, provider_dsn text, replication_sets text[], synchronize_structure boolean, synchronize_data boolean, forward_origins text[], apply_delay interval)`` 現在のノードからプロバイダーノードへのサブスクリプションを作成します。コマンドはブロックせず、アクションを開始するだけです。 パラメーター - ``subscription_name`` -サブスクリプションの名前、一意である必要があります - ``provider_dsn`` -プロバイダーへの接続文字列 - ``replication_sets`` -サブスクライブするレプリケーションセットの配列、これらは既に存在する必要があります、デフォルトは”{default,default_insert_only,ddl_sql}” - ``synchronize_structure`` -指定しますプロバイダーからサブスクライバーに構造を同期する場合、デフォルトfalse - ``synchronize_data`` -プロバイダーからサブスクライバーにデータを同期するかどうかを指定します、デフォルトtrue - ``forward_origins`` -転送するオリジン名の配列、現在サポートされている値のみが空の配列であり、変更を転送しないプロバイダーノードで発生したものではないこれはノード間の双方向レプリケーションに役立ちます、または「{all}」つまり起点が何であるかに関係なくすべての変更をレプリケートします。デフォルトは「{all}」 - ``apply_delay`` -レプリケーションをどれだけ遅延するか、デフォルトは0秒です - ``force_text_transfer`` - プロバイダーにテキストを使用してすべての列をレプリケートするように強制します表現速度は遅くなりますが、サブスクライバでレプリケートされた列の型を変更するために使用される場合があります、デフォルトはfalseです ``subscription_name`` は、レプリケーション接続によって\ ``application_name`` として使用されます。これは、\ ``pg_stat_replication`` モニタリングビューに表示されることを意味します。 pglogicalが :ref:`Synchronous Replication ` セットアップの一部として使用される場合、\ ``synchronous_standby_names`` で使用することもできます。 ``pglogical.wait_for_subscription_sync_complete(sub_name)`` を使用して、サブスクリプションが非同期でレプリケートを開始し、必要なスキーマおよび/またはデータの同期を完了するまで待機します。 - ``pglogical.drop_subscription(subscription_name name, ifexists bool)`` サブスクリプションを切断し、カタログから削除します。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``ifexists`` -trueの場合、サブスクリプションが存在しない場合にエラーはスローされません、デフォルトはfalse - ``pglogical.alter_subscription_disable(subscription_name name, immediate bool)`` サブスクリプションを無効にし、プロバイダーから切断します。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``immediate`` -trueの場合、サブスクリプションはすぐに停止されます。それ以外の場合、現在のトランザクションの終了時にのみ停止されます。デフォルトはfalse - ``pglogical.alter_subscription_enable(subscription_name name, immediate bool)`` 無効なサブスクリプションを有効にします。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``immediate`` -trueの場合、サブスクリプションはすぐに開始されます。それ以外の場合、現在のトランザクションの終了時にのみ開始されます。デフォルトはfalse - ``pglogical.alter_subscription_interface(subscription_name name, interface_name name)`` 別のインターフェイスを使用してプロバイダーノードに接続するようにサブスクリプションを切り替えます。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``interface_name`` -現在のプロバイダーノードの既存のインターフェイスの名前 - ``pglogical.alter_subscription_synchronize(subscription_name name, truncate bool)`` すべてのセットのすべての非同期テーブルが、単一のオペレーションで同期されます。テーブルは1つずつコピーおよび同期されます。コマンドはブロックせず、アクションを開始するだけです。 ``pglogical.wait_for_subscription_sync_complete`` を使用して、完了を待機します。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``truncate`` -trueの場合、テーブルはコピー前に切り詰められます、デフォルトfalse - ``pglogical.alter_subscription_resynchronize_table(subscription_name name, relation regclass)`` 既存の1つのテーブルを再同期します。テーブルは、外部キー制約のターゲットであってはなりません。 **警告このファンクションはテーブルをすぐに切り捨て、その後にのみ同期を開始するため、同期中は空になります** ブロックしません。\ ``pglogical.wait_for_table_sync_complete`` を使用して完了を待機します。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``relation`` -既存のテーブルの名前、オプションで修飾 - ``pglogical.wait_for_subscription_sync_complete(subscription_name name)`` ``pglogical.create_subscription`` または\ ``pglogical.alter_subscription_synchronize`` の後に、サブスクリプションまたは同期が終了するまで待機します。 このファンクションは、サブスクリプションの初期スキーマ/データ同期がある場合は、完了し、個々の再同期保留中のテーブルも同期が終了するまで待機します。 最良の結果を得るには、再同期を要求したレプリケーションセットの変更の後にプロバイダーで\ ``SELECT pglogical.wait_slot_confirm_lsn(NULL, NULL)`` を実行し、その後にのみサブスクライバーで\ ``pglogical.wait_for_subscription_sync_complete`` を呼び出します。 - ``pglogical.wait_for_table_sync_complete(subscription_name name, relation regclass)`` ``pglogical.wait_for_subscription_sync_complete`` と同じですが、サブスクリプションの初期同期と名前付けテーブルのみを待機します。再同期保留中の他のテーブルは無視されます。 - ``pglogical.wait_slot_confirm_lsn`` ``SELECT pglogical.wait_slot_confirm_lsn(NULL, NULL)`` 現在のノードのすべてのレプリケーションスロットが、すべてのプロバイダーの呼び出し時にxlog挿入位置まで再生されるまで待機します。呼び出し時にすべてのスロットの\ ``confirmed_flush_lsn`` が\ ``pg_current_wal_insert_lsn()`` を通過したときに返されます。 オプションで、1つのレプリケーションスロット最初の引数のみを待機できます。オプションで、 insert lsn 2番目の引数の代わりに渡される任意のLSNを待機することができます。通常、どちらもnullのままです。 この機能は、すべての加入者がプロバイダーの特定のポイントまでの変更を受信したことを保証するために非常に役立ちます。 - ``pglogical.show_subscription_status(subscription_name name)`` サブスクリプションに関するステータスと基本情報を表示します。 パラメーター - ``subscription_name`` - 既存のサブスクリプションのオプションの名前。名前が指定されない場合、ファンクションはローカルノード上のすべてのサブスクリプションのステータスを表示します - ``pglogical.show_subscription_table(subscription_name name, relation regclass)`` テーブルの同期状態を示します。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``relation`` -既存のテーブルの名前、オプションで修飾 - ``pglogical.alter_subscription_add_replication_set(subscription_name name, replication_set name)`` 1つのレプリケーションセットをサブスクライバーに追加します。同期はせず、イベントの使用をアクティブ化するだけです。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``replication_set`` -追加するレプリケーションセットの名前 - ``pglogical.alter_subscription_remove_replication_set(subscription_name name, replication_set name)`` サブスクライバーから1つのレプリケーションセットを削除します。 パラメーター - ``subscription_name`` -既存のサブスクリプションの名前 - ``replication_set`` -削除するレプリケーションセットの名前 ``postgresql.conf`` パラメーター ``pglogical.extra_connection_options`` もあり、pglogicalによって作成されるすべての接続に適用される接続オプションを割り当てるように設定できます。これは、カスタムキープアライブオプションなどを設定するのに役立ちます。 pglogicalは、TCPキープアライブを有効にして、上流サーバーが予期せず消えたときに通知できるようにします。それらを無効にするには、\ ``keepalives = 0`` を\ ``pglogical.extra_connection_options`` に追加します。 レプリケーションセット ---------------------- レプリケーションセットは、データベース内のどのテーブルをレプリケートするか、およびこれらのテーブルのどのアクションをレプリケートするかを制御するメカニズムを提供します。 レプリケートされた各セットは、セット上の\ ``INSERTs`` 、\ ``UPDATEs`` 、\ ``DELETEs`` 、および\ ``TRUNCATEs`` をレプリケートするかどうかを個別に指定できます。すべてのテーブルは複数のレプリケーションセットにすることができ、すべてのサブスクライバーは同様にマルチプルのレプリケーションセットをサブスクライブできます。レプリケートされたテーブルとアクションの結果のセットは、テーブルが含まれるセットの和集合です。テーブルは、レプリケーションセットに追加されるまでレプリケートされません。 「default」、「default_insert_only」、および「ddl_sql」という名前の3つの既存のレプリケーションセットがあります。 「デフォルト」レプリケーションセットは、その内のテーブルへのすべての変更をレプリケートするように定義されます。 “default_insert_only”はINSERTのみをレプリケートし、主キーを持たないテーブルを対象としています。詳細については、 :ref:`Limitations and restrictions ` セクションを参照してください。 “ddl_sql”レプリケーションセットは、\ ``pglogical.replicate_ddl_command`` で指定されたスキーマ変更をレプリケートするように定義されます レプリケーションセットを管理するために次の機能が提供されています。 - ``pglogical.create_replication_set(set_name name, replicate_insert bool, replicate_update bool, replicate_delete bool, replicate_truncate bool)`` このファンクションは、新しいレプリケーションセットを作成します。 Parameters: - ``set_name`` - name of the set, must be unique - ``replicate_insert`` - specifies if ``INSERT`` is replicated, default true - ``replicate_update`` - specifies if ``UPDATE`` is replicated, default true - ``replicate_delete`` - specifies if ``DELETE`` is replicated, default true - ``replicate_truncate`` - specifies if ``TRUNCATE`` is replicated 、デフォルトtrue - ``pglogical.alter_replication_set(set_name name, replicate_inserts bool, replicate_updates bool, replicate_deletes bool, replicate_truncate bool)`` このファンクションは、既存のレプリケーションセットのパラメーターを変更します。 Parameters: - ``set_name`` - name of the existing replication set - ``replicate_insert`` - specifies if ``INSERT`` is replicated, default true - ``replicate_update`` - specifies if ``UPDATE`` is replicated, default true - ``replicate_delete`` - specifies if ``DELETE`` is replicated, default true - ``replicate_truncate`` - specifies if ``TRUNCATE`` is replicated, default true - ``pglogical.drop_replication_set(set_name text)`` レプリケーションセットを削除します。 パラメーター - ``set_name`` - 既存のレプリケーションセットの名前 - ``pglogical.replication_set_add_table(set_name name, relation regclass, synchronize_data boolean, columns text[], row_filter text)`` レプリケーションセットにテーブルを追加します。 パラメーター - ``set_name`` -既存のレプリケーションの名前 set - ``relation`` -set - に追加するテーブルの名前またはOID ``synchronize_data`` -trueの場合、テーブルデータは指定されたレプリケーションセット、デフォルトfalse - ``columns`` -レプリケートする列のリスト。通常、すべての列をレプリケートする必要がある場合、これはデフォルトであるNULLに設定されますb_tran_13 ``row_filter`` - 行フィルタリング式、デフォルトNULLフィルタリングなし、詳細については、 :ref:`行フィルタリング <行フィルタリング>` を参照してください。 **警告有効な行フィルタとデータを同期するときは注意してください。** 有効な\ ``row_filter`` とともに\ ``synchronize_data=true`` を使用することは、テーブルの1回限りのオペレーションに似ています。 ``row_filter`` を変更して再度実行しても、データはサブスクライバーに同期されません。サブスクリプションは、\ ``pglogical.alter_subscription_resynchronize_table()`` を呼び出して修正する必要がある場合があります。 - ``pglogical.replication_set_add_all_tables(set_name name, schema_names text[], synchronize_data boolean)`` 指定されたスキーマのすべてのテーブルを追加します。既存のテーブルのみが追加されます。今後作成されるテーブルは自動的に追加されません。今後作成されるテーブルが正しいレプリケーションセットに追加されることを確認する方法については、 :ref:`新しいテーブルのレプリケーションセットの自動割り当て <新しいテーブルのレプリケーションセットの自動割り当て>` を参照してください。 パラメーター - ``set_name`` -既存のレプリケーションセットの名前 - ``schema_names`` -名前の配列 テーブルを追加する既存のスキーマの名前 - ``synchronize_data`` -trueの場合、テーブルデータは指定されたレプリケーションセットをサブスクライブしているすべてのサブスクライバーで同期されます。デフォルトはfalse - ``pglogical.replication_set_remove_table(set_name name, relation regclass)`` レプリケーションセットからテーブルを削除します。 パラメーター - ``set_name`` -既存のレプリケーションセットの名前 - ``relation`` -セットから削除するテーブルの名前またはOID - ``pglogical.replication_set_add_sequence(set_name name, relation regclass, synchronize_data boolean)`` シーケンスをレプリケーションセットに追加します。 パラメーター - ``set_name`` -既存のレプリケーションの名前 set - ``relation`` -set - に追加するシーケンスの名前またはOID ``synchronize_data`` -trueの場合、シーケンス値はすぐに同期されます、デフォルトfalse - ``pglogical.replication_set_add_all_sequences(set_name name, schema_names text[], synchronize_data boolean)`` 指定されたスキーマからすべてのシーケンスを追加します。既存のシーケンスのみが追加されます。今後作成されるシーケンスは自動的に追加されません。 パラメーター - ``set_name`` -既存のレプリケーションセットの名前b_tran_7 ``schema_names`` -名前の配列テーブルを追加する既存のスキーマの名前 - ``synchronize_data`` -trueの場合、シーケンス値はすぐに同期されます、デフォルトfalse - ``pglogical.replication_set_remove_sequence(set_name name, relation regclass)`` レプリケーションセットからシーケンスを削除します。 パラメーター - ``set_name`` - 既存のレプリケーションセットの名前 - ``relation`` - セットから削除するシーケンスの名前またはOID ``pglogical.tables`` ビューを照会することにより、どのテーブルがどのセットにあるかに関する情報を表示できます。 新しいテーブルのレプリケーションセットの自動割り当て ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ イベントトリガー機能は、新しく作成されるテーブルのレプリケーションセットを定義するルールを記述するために使用できます。 例 :: CREATE OR REPLACE FUNCTION pglogical_assign_repset() RETURNS event_trigger AS $$ DECLARE obj record; BEGIN FOR obj IN SELECT * FROM pg_event_trigger_ddl_commands() LOOP IF obj.object_type = table THEN IF obj.schema_name = config THEN PERFORM pglogical.replication_set_add_table(configuration, obj.objid); ELSIF NOT obj.in_extension THEN PERFORM pglogical.replication_set_add_table(default, obj.objid); END IF; END IF; END LOOP; END; $$ LANGUAGE plpgsql; CREATE EVENT TRIGGER pglogical_assign_repset_trg ON ddl_command_end WHEN TAG IN (CREATE TABLE, CREATE TABLE AS) EXECUTE PROCEDURE pglogical_assign_repset(); 上記の例では、スキーマ\ ``config`` で作成されたすべての新しいテーブルをレプリケーションセット\ ``configuration`` に配置し、拡張機能によって作成されない他のすべての新しいテーブルは\ ``default`` レプリケーションセットに配置されます。 追加機能 -------- - ``pglogical.replicate_ddl_command(command text, replication_sets text[])`` ローカルで実行し、指定されたコマンドをレプリケーションキューに送信して、指定された\ ``replication_sets`` のいずれかにサブスクライブしているサブスクライバーで実行します。 パラメーター - ``command`` -実行するDDLクエリー - ``replication_sets`` -このコマンドを関連付けるレプリケーションセットの配列、デフォルト”{ddl_sql}” - ``pglogical.synchronize_sequence(relation regclass)`` シーケンス状態をすべてのサブスクライバーにプッシュします。サブスクリプションやテーブル同期ファンクションとは異なり、このファンクションはプロバイダーで実行する必要があります。このファンクションが実行されたトランザクションをレプリケートすると、すべてのサブスクライバが消費する追跡シーケンスの状態の更新を強制しますレプリケーションセットフィルタリングは引き続き適用されます。 パラメーター - ``relation`` - 既存のシーケンスの名前、オプションで修飾 行フィルタリング ---------------- PGLogicalでは、プロバイダー側とサブスクライバー側の両方で行ベースのフィルタリングができます。 プロバイダーの行フィルタリング ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ プロバイダーでは、 ``pglogical.replication_set_add_table`` ファンクションの\ ``row_filter`` パラメーターを指定することにより、行フィルタリングを実行できます。 ``row_filter`` は、\ ``CHECK`` 制約と許可されるものと同じ制限がある通常のPostgreSQL式です。 単純な\ ``row_filter`` は\ ``row_filter := 'id > 0'`` のようになり、\ ``id`` 列の値がゼロより大きい行のみがレプリケートされます。 ``row_filter`` 内でvolatileファンクションを使用することはできますが、書き込みを行う式はエラーをスローし、レプリケーションを停止するため、書き込みに関して注意を払う必要があります。 ``row_filter`` はレプリケーションセッション内で実行されているため、 ``CURRENT_USER`` などのセッション固有の式は、書き込みを行ったセッションではなく、レプリケーションセッションの値を持つことにも注意してください。 サブスクライバーの行フィルタリング ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ サブスクライバーでは、標準の\ ``BEFORE TRIGGER`` メカニズムを使用して行ベースのフィルタリングを実装できます。 このようなトリガーを\ ``ENABLE REPLICA`` または\ ``ENABLE ALWAYS`` としてマークする必要があります。それ以外の場合、レプリケーションプロセスによって実行されません。