diff options
Diffstat (limited to 'doc/src/sgml/ref/create_subscription.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_subscription.sgml | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml new file mode 100644 index 00000000000..40d08b34409 --- /dev/null +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -0,0 +1,176 @@ +<!-- +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> +CREATE SUBSCRIPTION <replaceable class="PARAMETER">subscription_name</replaceable> CONNECTION 'conninfo' PUBLICATION { publication_name [, ...] } [ WITH ( <replaceable class="PARAMETER">option</replaceable> [, ... ] ) ] + +<phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase> + + | ENABLED | DISABLED + | CREATE SLOT | NOCREATE SLOT + | SLOT NAME = slot_name +</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> + + <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> + The connection string to the publisher. + </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> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Create a subscription to a remote server that replicates tables in + the publications <literal>mypubclication</literal> and + <literal>insert_only</literal> and starts replicating immediately on + commit: +<programlisting> +CREATE SUBSCRIPTION mysub + CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb password=foopass' + 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 + CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb password=foopass' + 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> |