CREATE SUBSCRIPTION <refpurpose>define a new subscription</refpurpose> — 新しいサブスクリプションを定義する
CREATE SUBSCRIPTIONsubscription_nameCONNECTION 'conninfo' PUBLICATIONpublication_name[, ...] [ WITH (subscription_parameter[=value] [, ... ] ) ]
<command>CREATE SUBSCRIPTION</command> adds a new logical-replication
subscription. The user that creates a subscription becomes the owner
of the subscription. The subscription name must be distinct from the name of
any existing subscription in the current database.
CREATE SUBSCRIPTIONは新しい論理レプリケーションのサブスクリプションを追加します。
サブスクリプションを作成するユーザは、サブスクリプションの所有者になります。
サブスクリプションの名前は現在のデータベースに存在するどのサブスクリプションの名前とも異なるものでなければなりません。
A subscription represents a replication connection to the publisher. Hence, in addition to adding definitions in the local catalogs, this command normally creates a replication slot on the publisher. サブスクリプションはパブリッシャーへのレプリケーション接続を表します。 そのため、このコマンドはローカルのカタログに定義を追加するだけでなく、通常はパブリッシャーのレプリケーションスロットも作成します。
A logical replication worker will be started to replicate data for the new subscription at the commit of the transaction where this command is run, unless the subscription is initially disabled. サブスクリプションが最初に無効にされていない限り、このコマンドが実行されるトランザクションがコミットされた時点で、新しいサブスクリプションに対してデータを複製する論理レプリケーションワーカーが開始されます。
To be able to create a subscription, you must have the privileges of the
the <literal>pg_create_subscription</literal> role, as well as
<literal>CREATE</literal> privileges on the current database.
サブスクリプションを作成するには、現在のデータベースに対するCREATE権限に加えて、pg_create_subscriptionロールの権限が必要です。
Additional information about subscriptions and logical replication as a whole is available at <xref linkend="logical-replication-subscription"/> and <xref linkend="logical-replication"/>. サブスクリプションおよび論理レプリケーションの全体像についての追加情報は31.2および第31章に記述されています。
subscription_name #The name of the new subscription. 新しいサブスクリプションの名前です。
CONNECTION 'conninfo' #The <application>libpq</application> connection string defining how to connect to the publisher database. For details see <xref linkend="libpq-connstring"/>. パブリッシャーデータベースへの接続を定義するlibpq接続文字列です。 詳細は34.1.1を参照してください。
PUBLICATION publication_name [, ...] #Names of the publications on the publisher to subscribe to. パブリッシャー上のパブリケーションで、サブスクリプションの対象となるものの名前です。
WITH ( subscription_parameter [= value] [, ... ] ) #This clause specifies optional parameters for a subscription. この句は、サブスクリプションのオプションのパラメータを指定します。
The following parameters control what happens during subscription creation: 以下のパラメータは、サブスクリプションの作成時に何が行われるかを制御します。
connect (boolean) #
Specifies whether the <command>CREATE SUBSCRIPTION</command>
command should connect to the publisher at all. The default
is <literal>true</literal>. Setting this to
<literal>false</literal> will force the values of
<literal>create_slot</literal>, <literal>enabled</literal> and
<literal>copy_data</literal> to <literal>false</literal>.
(You cannot combine setting <literal>connect</literal>
to <literal>false</literal> with
setting <literal>create_slot</literal>, <literal>enabled</literal>,
or <literal>copy_data</literal> to <literal>true</literal>.)
CREATE SUBSCRIPTIONコマンドがパブリッシャーに接続する必要があるかどうかを指定します。
デフォルトはtrueです。
これをfalseに設定すると、create_slot、enabled、およびcopy_dataの値が、falseに強制的に設定されます。
(connectをfalseに設定することは、create_slot、enabled、またはcopy_dataをtrueに設定することと組み合わせることはできません。)
Since no connection is made when this option is
<literal>false</literal>, no tables are subscribed. To initiate
replication, you must manually create the replication slot, enable
the subscription, and refresh the subscription. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
このオプションがfalseに設定されると接続が行われないため、テーブルはサブスクライブされません。
レプリケーションを開始するには、レプリケーションスロットを手動で作成し、サブスクリプションを有効にして、サブスクリプションをリフレッシュする必要があります。
例については31.2.3を参照してください。
create_slot (boolean) #
Specifies whether the command should create the replication slot on
the publisher. The default is <literal>true</literal>.
このコマンドがパブリッシャー上にレプリケーションスロットを作るかどうかを指定します。
デフォルトはtrueです。
If set to <literal>false</literal>, you are responsible for
creating the publisher's slot in some other way. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
falseに設定した場合、パブリッシャーのスロットを何か他の方法で作成するのは利用者の責任です。
例については31.2.3を参照してください。
enabled (boolean) #
Specifies whether the subscription should be actively replicating
or whether it should just be set up but not started yet. The default
is <literal>true</literal>.
サブスクリプションが複製の動作をすぐに行うか、あるいは単に設定をするだけでまだ開始しないかを指定します。
デフォルトはtrueです。
slot_name (string) #Name of the publisher's replication slot to use. The default is to use the name of the subscription for the slot name. 使用するパブリッシャーのレプリケーションスロットの名前です。 デフォルトでは、サブスクリプションの名前をスロット名として使用します。
Setting <literal>slot_name</literal> to <literal>NONE</literal>
means there will be no replication slot associated with the
subscription. Such subscriptions must also have both
<literal>enabled</literal> and <literal>create_slot</literal> set to
<literal>false</literal>. Use this when you will be creating the
replication slot later manually. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
slot_nameをNONEに設定すると、サブスクリプションに紐付けられたレプリケーションスロットがなくなります。
そのようなサブスクリプションは、enabledとcreate_slotの両方をfalseに設定しなければなりません。
これはレプリケーションスロットを後で手作業で作成する場合に使用してください。
例については31.2.3を参照してください。
The following parameters control the subscription's replication behavior after it has been created: 以下のパラメータは、作成された後のサブスクリプションのレプリケーション動作を制御します。
binary (boolean) #
Specifies whether the subscription will request the publisher to send
the data in binary format (as opposed to text). The default is
<literal>false</literal>. Any initial table synchronization copy
(see <literal>copy_data</literal>) also uses the same format. Binary
format can be faster than the text format, but it is less portable
across machine architectures and <productname>PostgreSQL</productname>
versions. Binary format is very data type specific; for example, it
will not allow copying from a <type>smallint</type> column to an
<type>integer</type> column, even though that would work fine in text
format. Even when this option is enabled, only data types having binary
send and receive functions will be transferred in binary. Note that
the initial synchronization requires all data types to have binary
send and receive functions, otherwise the synchronization will fail
(see <xref linkend="sql-createtype"/> for more about send/receive
functions).
（テキストではなく）バイナリ形式でデータを送信するようにサブスクリプションがパブリッシャーに要求するかどうかを指定します。
デフォルトはfalseです。
最初のテーブル同期コピー(copy_data参照)も同じ形式を使います。
バイナリ形式はテキスト形式よりも高速かもしれませんが、マシンアーキテクチャやPostgreSQLのバージョンをまたがる移植性が落ちます。
バイナリ形式はデータ型に非常に依存します。
例えば、テキスト形式では問題なく動作するにも関わらず、smallintの列からintegerの列へのコピーを認めません。
このオプションが有効になっている場合でも、バイナリ送受信関数を持つデータ型のみがバイナリ形式で転送されます。
最初の同期ではデータ型すべてがバイナリ送受信関数を持つことが必要なことに注意してください。さもないと同期は失敗します(送受信関数についてはCREATE TYPEを参照してください)。
When doing cross-version replication, it could be that the
publisher has a binary send function for some data type, but the
subscriber lacks a binary receive function for that type. In
such a case, data transfer will fail, and
the <literal>binary</literal> option cannot be used.
バージョンをまたいでレプリケーションをしている場合は、パブリッシャーはあるデータ型に対してバイナリ送信関数を持っているものの、サブスクライバーはその型に対してバイナリ受信関数を持っていないという場合があり得ます。
その場合、データ転送は失敗し、binaryオプションは使えません。
If the publisher is a <productname>PostgreSQL</productname> version
before 16, then any initial table synchronization will use text format
even if <literal>binary = true</literal>.
パブリッシャーのバージョンがPostgreSQL 16より前の場合、最初のテーブル同期では、binary = trueであってもテキストフォーマットが使用されます。
copy_data (boolean) #
Specifies whether to copy pre-existing data in the publications
that are being subscribed to when the replication starts.
The default is <literal>true</literal>.
サブスクリプションの対象となるパブリケーションの既存データが、レプリケーションの開始時にコピーされるかどうかを指定します。
デフォルトはtrueです。
If the publications contain <literal>WHERE</literal> clauses, it
will affect what data is copied. Refer to the
<xref linkend="sql-createsubscription-notes" /> for details.
パブリケーションにWHERE句が含まれている場合、コピーされるデータに影響します。
詳細は注釈を参照してください。
See <xref linkend="sql-createsubscription-notes"/> for details of how
<literal>copy_data = true</literal> can interact with the
<literal>origin</literal> parameter.
copy_data = trueがoriginパラメータとどのように相互作用するかの詳細については、注釈を参照してください。
streaming (enum) #
Specifies whether to enable streaming of in-progress transactions
for this subscription. The default value is <literal>off</literal>,
meaning all transactions are fully decoded on the publisher and only
then sent to the subscriber as a whole.
進行中のトランザクションのストリーミングをこのサブスクリプションで有効にするかどうかを指定します。
デフォルト値はoffで、すべてのトランザクションはパブリッシャーで完全にデコードされ、その後でのみ全体としてサブスクライバーに送られることを意味します。
If set to <literal>on</literal>, the incoming changes are written to
temporary files and then applied only after the transaction is
committed on the publisher and received by the subscriber.
onに設定すると、受信した変更は一時ファイルに書き込まれ、トランザクションがパブリッシャーでコミットされ、サブスクライバーで受信された後にのみ適用されます。
If set to <literal>parallel</literal>, incoming changes are directly
applied via one of the parallel apply workers, if available. If no
parallel apply worker is free to handle streaming transactions then
the changes are written to temporary files and applied after the
transaction is committed. Note that if an error happens in a
parallel apply worker, the finish LSN of the remote transaction
might not be reported in the server log.
parallelに設定すると、受信した変更は、可能であれば、パラレル適用ワーカーの1つを介して直接適用されます。
ストリーミングトランザクションを扱えるパラレル適用ワーカーがない場合、変更は一時ファイルに書き込まれ、トランザクションがコミットされた後に適用されます。
パラレル適用ワーカーでエラーが発生した場合、リモートトランザクションの終了LSNがサーバーログで報告されない場合があることに注意してください。
synchronous_commit (enum) #
The value of this parameter overrides the
<xref linkend="guc-synchronous-commit"/> setting within this
subscription's apply worker processes. The default value
is <literal>off</literal>.
このパラメータの値は、このサブスクリプションの適用されるワーカープロセスのsynchronous_commitの設定をオーバーライドします。
デフォルト値はoffです。
It is safe to use <literal>off</literal> for logical replication:
If the subscriber loses transactions because of missing
synchronization, the data will be sent again from the publisher.
論理レプリケーションではoffを使用するのが安全です。
そうすることで、同期の失敗によりサブスクライバーがトランザクションを失った場合でも、パブリッシャーからデータが再送されます。
A different setting might be appropriate when doing synchronous
logical replication. The logical replication workers report the
positions of writes and flushes to the publisher, and when using
synchronous replication, the publisher will wait for the actual
flush. This means that setting
<literal>synchronous_commit</literal> for the subscriber to
<literal>off</literal> when the subscription is used for
synchronous replication might increase the latency for
<command>COMMIT</command> on the publisher. In this scenario, it
can be advantageous to set <literal>synchronous_commit</literal>
to <literal>local</literal> or higher.
同期論理レプリケーションを行う場合は別の設定が適切かもしれません。
論理レプリケーションのワーカーは書き込みおよび吐き出しの位置をパブリッシャーに報告しますが、同期レプリケーションを行っているときは、パブリッシャーは実際に吐き出しがされるのを待ちます。
これはつまり、サブスクリプションが同期レプリケーションで使われている時に、サブスクライバーのsynchronous_commitをoffに設定すると、パブリッシャーでのCOMMITの遅延が増大するかもしれない、ということを意味します。
この場合、synchronous_commitをlocalまたはそれ以上に設定することが有利になりえます。
two_phase (boolean) #
Specifies whether two-phase commit is enabled for this subscription.
The default is <literal>false</literal>.
このサブスクリプションに対して2相コミットを有効にするかどうかを指定します。
デフォルトはfalseです。
When two-phase commit is enabled, prepared transactions are sent
to the subscriber at the time of <command>PREPARE
TRANSACTION</command>, and are processed as two-phase
transactions on the subscriber too. Otherwise, prepared
transactions are sent to the subscriber only when committed, and
are then processed immediately by the subscriber.
2相コミットが使用可能な場合、プリペアドトランザクションはPREPARE TRANSACTION時にサブスクライバーに送信され、サブスクライバー上でも2相トランザクションとして処理されます。
それ以外の場合、プリペアドトランザクションはコミット時にのみサブスクライバーに送信され、サブスクライバーによってただちに処理されます。
The implementation of two-phase commit requires that replication
has successfully finished the initial table synchronization
phase. So even when <literal>two_phase</literal> is enabled for a
subscription, the internal two-phase state remains
temporarily <quote>pending</quote> until the initialization phase
completes. See column <structfield>subtwophasestate</structfield>
of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
to know the actual two-phase state.
2相コミットの実装では、レプリケーションが最初のテーブル同期フェーズを正常に完了している必要があります。
そのため、two_phaseがサブスクリプションに対して有効になっている場合でも、内部の2相状態は初期化フェーズが完了するまで一時的に「pending（保留）」のままです。
実際の2相状態を知るには、pg_subscriptionのsubtwophasestate列を参照してください。
disable_on_error (boolean) #
Specifies whether the subscription should be automatically disabled
if any errors are detected by subscription workers during data
replication from the publisher. The default is
<literal>false</literal>.
パブリッシャーからのデータレプリケーション中にサブスクリプションワーカーによってエラーが検出された場合に、サブスクリプションを自動的に無効にするかどうかを指定します。
デフォルトはfalseです。
password_required (boolean) #
Specifies whether connections to the publisher made as a result
of this subscription must use password authentication. This setting
is ignored when the subscription is owned by a superuser.
The default is <literal>true</literal>. Only superusers can set
this value to <literal>false</literal>.
このパブリッシャーの結果として行われたサブスクリプションへの接続で、パスワード認証を使用する必要があるかどうかを指定します。
サブスクリプションがスーパーユーザによって所有されている場合、この設定は無視されます。
デフォルトはtrueです。
スーパーユーザのみがこの値をfalseに設定できます。
run_as_owner (boolean) #
If true, all replication actions are performed as the subscription
owner. If false, replication workers will perform actions on each
table as the owner of that table. The latter configuration is
generally much more secure; for details, see
<xref linkend="logical-replication-security" />.
The default is <literal>false</literal>.
trueの場合、レプリケーションのアクションはすべてサブスクリプション所有者として行われます。
falseの場合、レプリケーションワーカーは各テーブルでそのテーブルの所有者としてアクションを行います。
後者の設定が一般的にはよりセキュアです。詳細は31.9を参照してください。
デフォルトはfalseです。
origin (string) #
Specifies whether the subscription will request the publisher to only
send changes that don't have an origin or send changes regardless of
origin. Setting <literal>origin</literal> to <literal>none</literal>
means that the subscription will request the publisher to only send
changes that don't have an origin. Setting <literal>origin</literal>
to <literal>any</literal> means that the publisher sends changes
regardless of their origin. The default is <literal>any</literal>.
サブスクリプションがパブリッシャーに、オリジンのない変更のみを送信するよう要求するか、オリジンに関係なく変更を送信するよう要求するかを指定します。
originをnoneに設定すると、サブスクリプションはパブリッシャーにオリジンのない変更のみを送信するよう要求します。
originをanyに設定すると、パブリッシャーはオリジンに関係なく変更を送信します。
デフォルトはanyです。
See <xref linkend="sql-createsubscription-notes"/> for details of how
<literal>copy_data = true</literal> can interact with the
<literal>origin</literal> parameter.
copy_data = trueがoriginパラメータとどのように相互作用するかの詳細については、注釈を参照してください。
When specifying a parameter of type <type>boolean</type>, the
<literal>=</literal> <replaceable class="parameter">value</replaceable>
part can be omitted, which is equivalent to
specifying <literal>TRUE</literal>.
boolean型のパラメータを指定する場合、= valueの部分を省略できます。これはTRUEを指定するのと同じです。
See <xref linkend="logical-replication-security"/> for details on how to configure access control between the subscription and the publication instance. サブスクリプションとパブリケーションのインスタンスの間のアクセス制御をどのように設定するかの詳細については、31.9を参照してください。
When creating a replication slot (the default behavior), <command>CREATE
SUBSCRIPTION</command> cannot be executed inside a transaction block.
レプリケーションスロットを作成する（デフォルトの動作です）場合、CREATE SUBSCRIPTIONをトランザクションブロックの内側で実行することはできません。
Creating a subscription that connects to the same database cluster (for
example, to replicate between databases in the same cluster or to replicate
within the same database) will only succeed if the replication slot is not
created as part of the same command. Otherwise, the <command>CREATE
SUBSCRIPTION</command> call will hang. To make this work, create the
replication slot separately (using the
function <function>pg_create_logical_replication_slot</function> with the
plugin name <literal>pgoutput</literal>) and create the subscription using
the parameter <literal>create_slot = false</literal>. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples. This is an implementation restriction that might be lifted in a
future release.
同じデータベースクラスタに接続するサブスクリプション（例えば、同一のクラスタ内のデータベース間で複製を行う、あるいは同一のデータベース内で複製を行う）の作成は、同じコマンド内でレプリケーションスロットが作成されない場合にのみ成功します。
そうでない場合、CREATE SUBSCRIPTIONの呼び出しはハングアップします。
これを動作させるには、（関数pg_create_logical_replication_slotをプラグイン名pgoutputで使って）レプリケーションスロットを別に作り、パラメータcreate_slot = falseを使ってサブスクリプションを作成してください。
例については31.2.3を参照してください。
これは実装上の制限で、将来のリリースでは解決されるかもしれません。
If any table in the publication has a <literal>WHERE</literal> clause, rows
for which the <replaceable class="parameter">expression</replaceable>
evaluates to false or null will not be published. If the subscription has
several publications in which the same table has been published with
different <literal>WHERE</literal> clauses, a row will be published if any
of the expressions (referring to that publish operation) are satisfied. In
the case of different <literal>WHERE</literal> clauses, if one of the
publications has no <literal>WHERE</literal> clause (referring to that
publish operation) or the publication is declared as
<link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
rows are always published regardless of the definition of the other
expressions. If the subscriber is a <productname>PostgreSQL</productname>
version before 15, then any row filtering is ignored during the initial data
synchronization phase. For this case, the user might want to consider
deleting any initially copied data that would be incompatible with
subsequent filtering. Because initial data synchronization does not take
into account the publication
<link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
parameter when copying existing table data, some rows may be copied that
would not be replicated using DML. See
<xref linkend="logical-replication-subscription-examples"/> for examples.
パブリケーション内のテーブルにWHERE句がある場合、expressionが偽またはNULLと評価される行はパブリッシュされません。
サブスクリプションに、同じテーブルが異なるWHERE句でパブリッシュされた複数のパブリケーションがある場合、(パブリッシュ操作を参照する)式のいずれかが満たされると行がパブリッシュされます。
WHERE句が異なる場合、パブリケーションのいずれかにWHERE句がないか(パブリッシュ操作を参照する)パブリケーションがFOR ALL TABLESまたはFOR TABLES IN SCHEMAとして宣言されている場合、行は他の式の定義に関係なく常にパブリッシュされます。
サブスクライバーのバージョンがPostgreSQL 15より前の場合、最初のデータ同期フェーズでは行のフィルタリングは無視されます。
この場合、後続のフィルタリングと互換性のない最初にコピーされたデータの削除を検討したくなるでしょう。
最初のデータ同期では、既存のテーブルデータをコピーする際にパブリケーションpublishパラメータが考慮されないため、DMLを使用してレプリケートされない行がコピーされる場合があります。
例については31.2.2を参照してください。
Subscriptions having several publications in which the same table has been published with different column lists are not supported. 同じテーブルが異なる列リストでパブリッシュされた複数のパブリケーションを持つサブスクリプションはサポートされません。
We allow non-existent publications to be specified so that users can add
those later. This means
<link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
can have non-existent publications.
後で追加できるように、存在しないパブリケーションを指定できます。
これはpg_subscriptionが存在しないパブリケーションを持つことができることを意味します。
When using a subscription parameter combination of
<literal>copy_data = true</literal> and <literal>origin = NONE</literal>,
the initial sync table data is copied directly from the publisher, meaning
that knowledge of the true origin of that data is not possible. If the
publisher also has subscriptions then the copied table data might have
originated from further upstream. This scenario is detected and a WARNING is
logged to the user, but the warning is only an indication of a potential
problem; it is the user's responsibility to make the necessary checks to
ensure the copied data origins are really as wanted or not.
サブスクリプションパラメータのcopy_data = trueとorigin = NONEの組合せを使用する場合、初期同期テーブルデータはパブリッシャーから直接コピーされます。これは、そのデータの真のオリジンを認識できないことを意味します。
そのパブリッシャーにもサブスクリプションがある場合、コピーされたテーブルデータはさらに上流から発生した可能性があります。
このシナリオは検出され、警告がユーザに向けて記録されますが、警告は潜在的な問題を示しているだけです。
コピーされたデータの発生元が本当に望んだものであること、またはそうでないことを保証する必要ななチェックを行うのは、ユーザの責任です。
To find which tables might potentially include non-local origins (due to other subscriptions created on the publisher) try this SQL query: どのテーブルが(そのパブリッシャーで作成された他のサブスクリプションのために)ローカルでないオリジンを含む可能性があるのかを知るためには、次のSQL問い合わせを試してください。
# substitute <pub-names> below with your publication name(s) to be queried
# 以下の<pub-names>を問い合わせるパブリケーションの名前で置き換えてください
SELECT DISTINCT PT.schemaname, PT.tablename
FROM pg_publication_tables PT,
pg_subscription_rel PS
JOIN pg_class C ON (C.oid = PS.srrelid)
JOIN pg_namespace N ON (N.oid = C.relnamespace)
WHERE N.nspname = PT.schemaname AND
C.relname = PT.tablename AND
PT.pubname IN (<pub-names>);
Create a subscription to a remote server that replicates tables in
the publications <literal>mypublication</literal> and
<literal>insert_only</literal> and starts replicating immediately on
commit:
パブリケーションmypublicationおよびinsert_onlyのテーブルを複製する、リモートサーバへのサブスクリプションを作成し、コミット後、すぐにレプリケーションを開始します。
CREATE SUBSCRIPTION mysub
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
PUBLICATION mypublication, insert_only;
Create a subscription to a remote server that replicates tables in
the <literal>insert_only</literal> publication and does not start replicating
until enabled at a later time.
パブリケーションinsert_onlyのテーブルを複製するリモートサーバへのサブスクリプションを作成しますが、後に有効化するまではレプリケーションを開始しません。
CREATE SUBSCRIPTION mysub
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
PUBLICATION insert_only
WITH (enabled = false);
<command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</productname>
extension.
CREATE SUBSCRIPTIONはPostgreSQLの拡張です。