CREATE SUBSCRIPTION — 新しいサブスクリプションを定義する
CREATE SUBSCRIPTIONsubscription_name
CONNECTION 'conninfo
' PUBLICATIONpublication_name
[, ...] [ WITH (subscription_parameter
[=value
] [, ... ] ) ]
CREATE SUBSCRIPTION
は新しい論理レプリケーションのサブスクリプションを追加します。
サブスクリプションの名前は現在のデータベースに存在するどのサブスクリプションの名前とも異なるものでなければなりません。
サブスクリプションはパブリッシャーへのレプリケーション接続を表します。 そのため、このコマンドはローカルのカタログに定義を追加するだけでなく、通常はパブリッシャーのレプリケーションスロットも作成します。
サブスクリプションが最初に無効にされていない限り、このコマンドが実行されるトランザクションがコミットされた時点で、新しいサブスクリプションに対してデータを複製する論理レプリケーションワーカーが開始されます。
subscription_name
新しいサブスクリプションの名前です。
CONNECTION 'conninfo
'
パブリッシャーデータベースへの接続を定義するlibpq接続文字列です。 詳細は34.1.1を参照してください。
PUBLICATION publication_name
[, ...]
パブリッシャー上のパブリケーションで、サブスクリプションの対象となるものの名前です。
WITH ( subscription_parameter
[= value
] [, ... ] )
この句は、サブスクリプションのオプションのパラメータを指定します。
以下のパラメータは、サブスクリプションの作成時に何が行われるかを制御します。
connect
(boolean
)
CREATE SUBSCRIPTION
コマンドがパブリッシャーに接続する必要があるかどうかを指定します。
デフォルトはtrue
です。
これをfalse
に設定すると、create_slot
、enabled
、およびcopy_data
の値が、false
に強制的に設定されます。
(connect
をfalse
に設定することは、create_slot
、enabled
、またはcopy_data
をtrue
に設定することと組み合わせることはできません。)
このオプションがfalse
に設定されると接続が行われないため、テーブルはサブスクライブされません。そのため、サブスクリプションを有効にしても、何も複製されません。
テーブルをサブスクライブするには、ALTER SUBSCRIPTION ... REFRESH PUBLICATION
を実行する必要があります。
create_slot
(boolean
)
このコマンドがパブリッシャー上にレプリケーションスロットを作るかどうかを指定します。
デフォルトはtrue
です。
false
に設定した場合、パブリッシャーのスロットを何か他の方法で作成するのは利用者の責任です。
enabled
(boolean
)
サブスクリプションが複製の動作をすぐに行うか、あるいは単に設定をするだけでまだ開始しないかを指定します。
デフォルトはtrue
です。
slot_name
(string
)使用するパブリッシャーのレプリケーションスロットの名前です。 デフォルトでは、サブスクリプションの名前をスロット名として使用します。
slot_name
をNONE
に設定すると、サブスクリプションに紐付けられたレプリケーションスロットがなくなります。
これはレプリケーションスロットを後で手作業で作成する場合に使用してください。
そのようなサブスクリプションは、enabled
とcreate_slot
の両方をfalse
に設定しなければなりません。
以下のパラメータは、作成された後のサブスクリプションのレプリケーション動作を制御します。
binary
(boolean
)
(テキストではなく)バイナリ形式でデータを送信するようにサブスクリプションがパブリッシャーに要求するかどうかを指定します。
デフォルトはfalse
です。
このオプションが有効になっている場合でも、バイナリ送受信関数を持つデータ型のみがバイナリ形式で転送されます。
バージョンをまたいでレプリケーションをしている場合は、パブリッシャーはあるデータ型に対してバイナリ送信関数を持っているものの、サブスクライバーはその型に対してバイナリ受信関数を持っていないという場合があり得ます。
その場合、データ転送は失敗し、binary
オプションは使えません。
copy_data
(boolean
)
サブスクリプションの対象となるパブリケーションの既存データが、レプリケーションの開始時にコピーされるかどうかを指定します。
デフォルトはtrue
です。
パブリケーションにWHERE
句が含まれている場合、コピーされるデータに影響します。
詳細は注釈を参照してください。
streaming
(boolean
)進行中のトランザクションのストリーミングをこのサブスクリプションで有効にするかどうかを指定します。 デフォルトでは、すべてのトランザクションはパブリッシャーで完全にデコードされ、その後でのみ全体としてサブスクライバーに送られます。
synchronous_commit
(enum
)
このパラメータの値は、このサブスクリプションの適用されるワーカープロセスのsynchronous_commitの設定をオーバーライドします。
デフォルト値はoff
です。
論理レプリケーションではoff
を使用するのが安全です。
そうすることで、同期の失敗によりサブスクライバーがトランザクションを失った場合でも、パブリッシャーからデータが再送されます。
同期論理レプリケーションを行う場合は別の設定が適切かもしれません。
論理レプリケーションのワーカーは書き込みおよび吐き出しの位置をパブリッシャーに報告しますが、同期レプリケーションを行っているときは、パブリッシャーは実際に吐き出しがされるのを待ちます。
これはつまり、サブスクリプションが同期レプリケーションで使われている時に、サブスクライバーのsynchronous_commit
をoff
に設定すると、パブリッシャーでのCOMMIT
の遅延が増大するかもしれない、ということを意味します。
この場合、synchronous_commit
をlocal
またはそれ以上に設定することが有利になりえます。
two_phase
(boolean
)
このサブスクリプションに対して2相コミットを有効にするかどうかを指定します。
デフォルトはfalse
です。
2相コミットが使用可能な場合、プリペアドトランザクションはPREPARE TRANSACTION
時にサブスクライバーに送信され、サブスクライバー上でも2相トランザクションとして処理されます。
それ以外の場合、プリペアドトランザクションはコミット時にのみサブスクライバーに送信され、サブスクライバーによってただちに処理されます。
2相コミットの実装では、レプリケーションが最初のテーブル同期フェーズを正常に完了している必要があります。
そのため、two_phase
がサブスクリプションに対して有効になっている場合でも、内部の2相状態は初期化フェーズが完了するまで一時的に「pending(保留)」のままです。
実際の2相状態を知るには、pg_subscription
のsubtwophasestate
列を参照してください。
disable_on_error
(boolean
)
パブリッシャーからのデータレプリケーション中にサブスクリプションワーカーによってエラーが検出された場合に、サブスクリプションを自動的に無効にするかどうかを指定します。
デフォルトはfalse
です。
サブスクリプションとパブリケーションのインスタンスの間のアクセス制御をどのように設定するかの詳細については、31.9を参照してください。
レプリケーションスロットを作成する(デフォルトの動作です)場合、CREATE SUBSCRIPTION
をトランザクションブロックの内側で実行することはできません。
同じデータベースクラスタに接続するサブスクリプション(例えば、同一のクラスタ内のデータベース間で複製を行う、あるいは同一のデータベース内で複製を行う)の作成は、同じコマンド内でレプリケーションスロットが作成されない場合にのみ成功します。
そうでない場合、CREATE SUBSCRIPTION
の呼び出しはハングアップします。
これを動作させるには、(関数pg_create_logical_replication_slot
をプラグイン名pgoutput
で使って)レプリケーションスロットを別に作り、パラメータcreate_slot = false
を使ってサブスクリプションを作成してください。
これは実装上の制限で、将来のリリースでは解決されるかもしれません。
パブリケーション内のテーブルにWHERE
句がある場合、expression
が偽またはNULLと評価される行はパブリッシュされません。
サブスクリプションに、同じテーブルが異なるWHERE
句でパブリッシュされた複数のパブリケーションがある場合、(パブリッシュ操作を参照する)式のいずれかが満たされると行がパブリッシュされます。
WHERE
句が異なる場合、パブリケーションのいずれかにWHERE
句がないか(パブリッシュ操作を参照する)パブリケーションがFOR ALL TABLES
またはFOR TABLES IN SCHEMA
として宣言されている場合、行は他の式の定義に関係なく常にパブリッシュされます。
サブスクライバーのバージョンがPostgreSQL 15より前の場合、最初のデータ同期フェーズでは行のフィルタリングは無視されます。
この場合、後続のフィルタリングと互換性のない最初にコピーされたデータの削除を検討したくなるでしょう。
最初のデータ同期では、既存のテーブルデータをコピーする際にパブリケーションpublish
パラメータが考慮されないため、DMLを使用してレプリケートされない行がコピーされる場合があります。
例については31.2.2を参照してください。
同じテーブルが異なる列リストでパブリッシュされた複数のパブリケーションを持つサブスクリプションはサポートされません。
後で追加できるように、存在しないパブリケーションを指定できます。
これはpg_subscription
が存在しないパブリケーションを持つことができることを意味します。
パブリケーションmypublication
およびinsert_only
のテーブルを複製する、リモートサーバへのサブスクリプションを作成し、コミット後、すぐにレプリケーションを開始します。
CREATE SUBSCRIPTION mysub CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' PUBLICATION mypublication, insert_only;
パブリケーションinsert_only
のテーブルを複製するリモートサーバへのサブスクリプションを作成しますが、後に有効化するまではレプリケーションを開始しません。
CREATE SUBSCRIPTION mysub CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' PUBLICATION insert_only WITH (enabled = false);
CREATE SUBSCRIPTION
はPostgreSQLの拡張です。