2017-01-19 18:00:00 +01:00
|
|
|
<!--
|
|
|
|
doc/src/sgml/ref/create_subscription.sgml
|
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="SQL-CREATESUBSCRIPTION">
|
|
|
|
<indexterm zone="sql-createsubscription">
|
|
|
|
<primary>CREATE SUBSCRIPTION</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<refmeta>
|
|
|
|
<refentrytitle>CREATE SUBSCRIPTION</refentrytitle>
|
|
|
|
<manvolnum>7</manvolnum>
|
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>CREATE SUBSCRIPTION</refname>
|
|
|
|
<refpurpose>define a new subscription</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2017-03-22 20:11:13 +01:00
|
|
|
CREATE SUBSCRIPTION <replaceable class="PARAMETER">subscription_name</replaceable>
|
|
|
|
CONNECTION '<replaceable class="PARAMETER">conninfo</replaceable>'
|
|
|
|
PUBLICATION { <replaceable class="PARAMETER">publication_name</replaceable> [, ...] }
|
|
|
|
[ WITH ( <replaceable class="PARAMETER">option</replaceable> [, ... ] ) ]
|
2017-01-19 18:00:00 +01:00
|
|
|
|
|
|
|
<phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>
|
|
|
|
|
|
|
|
| ENABLED | DISABLED
|
|
|
|
| CREATE SLOT | NOCREATE SLOT
|
2017-03-22 20:11:13 +01:00
|
|
|
| SLOT NAME = <replaceable class="PARAMETER">slot_name</replaceable>
|
2017-03-23 13:36:36 +01:00
|
|
|
| COPY DATA | NOCOPY DATA
|
|
|
|
| NOCONNECT
|
2017-01-19 18:00:00 +01:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE SUBSCRIPTION</command> adds a new subscription for a
|
|
|
|
current database. The subscription name must be distinct from the name of
|
|
|
|
any existing subscription in the database.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The subscription represents a replication connection to the publisher. As
|
|
|
|
such this command does not only add definitions in the local catalogs but
|
|
|
|
also creates a replication slot on the publisher.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
|
2017-03-04 05:25:34 +01:00
|
|
|
<para>
|
|
|
|
<command>CREATE SUBSCRIPTION</command> cannot be executed inside a
|
|
|
|
transaction block when <literal>CREATE SLOT</literal> is specified.
|
|
|
|
</para>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<para>
|
|
|
|
Additional info about subscriptions and logical replication as a whole
|
|
|
|
can is available at <xref linkend="logical-replication-subscription"> and
|
|
|
|
<xref linkend="logical-replication">.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">subscription_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of the new subscription.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-02-08 03:26:50 +01:00
|
|
|
The connection string to the publisher. For details
|
|
|
|
see <xref linkend="libpq-connstring">.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Name(s) of the publications on the publisher to subscribe to.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>ENABLED</literal></term>
|
|
|
|
<term><literal>DISABLED</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Specifies whether the subscription should be actively replicating or
|
|
|
|
if it should be just setup but not started yet. Note that the
|
|
|
|
replication slot as described above is created in either case.
|
|
|
|
<literal>ENABLED</literal> is the default.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>CREATE SLOT</literal></term>
|
|
|
|
<term><literal>NOCREATE SLOT</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Specifies whether the command should create the replication slot on the
|
|
|
|
publisher. <literal>CREATE SLOT</literal> is the default.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>SLOT NAME = <replaceable class="parameter">slot_name</replaceable></literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Name of the replication slot to use. The default behavior is to use
|
|
|
|
<literal>subscription_name</> for slot name.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2017-03-23 13:36:36 +01:00
|
|
|
|
|
|
|
<varlistentry>
|
2017-04-08 04:42:03 +02:00
|
|
|
<term><literal>COPY DATA</literal></term>
|
|
|
|
<term><literal>NOCOPY DATA</literal></term>
|
2017-03-23 13:36:36 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Specifies if the existing data in the publications that are being
|
|
|
|
subscribed to should be copied once the replication starts.
|
|
|
|
<literal>COPY DATA</literal> is the default.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2017-04-08 04:42:03 +02:00
|
|
|
<term><literal>NOCONNECT</literal></term>
|
2017-03-23 13:36:36 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Instructs <command>CREATE SUBSCRIPTION</command> to skip the initial
|
|
|
|
connection to the provider. This will change default values of other
|
|
|
|
options to <literal>DISABLED</literal>,
|
|
|
|
<literal>NOCREATE SLOT</literal>, and <literal>NOCOPY DATA</literal>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
It's not allowed to combine <literal>NOCONNECT</literal> and
|
|
|
|
<literal>ENABLED</literal>, <literal>CREATE SLOT</literal>, or
|
|
|
|
<literal>COPY DATA</literal>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Since no connection is made when this option is specified, the tables
|
|
|
|
are not subscribed, so after you enable the subscription nothing will
|
|
|
|
be replicated. It is required to run
|
|
|
|
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</> in order for
|
|
|
|
tables to be subscribed.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2017-01-19 18:00:00 +01:00
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
2017-02-08 03:26:50 +01:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
See <xref linkend="streaming-replication-authentication"> for details on
|
|
|
|
how to configure access control between the subscription and the
|
|
|
|
publication instance.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Create a subscription to a remote server that replicates tables in
|
2017-02-18 00:59:29 +01:00
|
|
|
the publications <literal>mypublication</literal> and
|
2017-01-19 18:00:00 +01:00
|
|
|
<literal>insert_only</literal> and starts replicating immediately on
|
|
|
|
commit:
|
|
|
|
<programlisting>
|
|
|
|
CREATE SUBSCRIPTION mysub
|
2017-02-08 03:26:50 +01:00
|
|
|
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
|
2017-01-19 18:00:00 +01:00
|
|
|
PUBLICATION mypublication, insert_only;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
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.
|
|
|
|
<programlisting>
|
|
|
|
CREATE SUBSCRIPTION mysub
|
2017-02-08 03:26:50 +01:00
|
|
|
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
|
2017-01-19 18:00:00 +01:00
|
|
|
PUBLICATION insert_only
|
|
|
|
WITH (DISABLED);
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</>
|
|
|
|
extension.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="sql-altersubscription"></member>
|
|
|
|
<member><xref linkend="sql-dropsubscription"></member>
|
|
|
|
<member><xref linkend="sql-createpublication"></member>
|
|
|
|
<member><xref linkend="sql-alterpublication"></member>
|
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|