postgresql/doc/src/sgml/ref/create_subscription.sgml

<!--
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 '<replaceable class="PARAMETER">conninfo</replaceable>'
    PUBLICATION { <replaceable class="PARAMETER">publication_name</replaceable> [, ...] }
    [ WITH ( <replaceable class="PARAMETER">option</replaceable> [, ... ] ) ]

<phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>

    | ENABLED | DISABLED
    | CREATE SLOT | NOCREATE SLOT
    | SLOT NAME = <replaceable class="PARAMETER">slot_name</replaceable>
    | COPY DATA | NOCOPY DATA
    | NOCONNECT
</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>
   <command>CREATE SUBSCRIPTION</command> cannot be executed inside a
   transaction block when <literal>CREATE SLOT</literal> is specified.
  </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.  For details
      see <xref linkend="libpq-connstring">.
     </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>

   <varlistentry>
    <term><literal>COPY DATA</literal></term>
    <term><literal>NOCOPY DATA</literal></term>
    <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>
    <term><literal>NOCONNECT</literal></term>
    <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>
  </variablelist>
 </refsect1>

 <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>

 <refsect1>
  <title>Examples</title>

  <para>
   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:
<programlisting>
CREATE SUBSCRIPTION mysub
         CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
        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'
        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>