<!--
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">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <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.
  </para>

  <para>
   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.
  </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,
   unless the subscription is initially disabled.
  </para>

  <para>
   To be able to create a subscription, you must have the privileges of
   the <literal>pg_create_subscription</literal> role, as well as
   <literal>CREATE</literal> privileges on the current database.
  </para>

  <para>
   Additional information about subscriptions and logical replication as a
   whole is available at <xref linkend="logical-replication-subscription"/> and
   <xref linkend="logical-replication"/>.
  </para>

 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry id="sql-createsubscription-params-name">
    <term><replaceable class="parameter">subscription_name</replaceable></term>
    <listitem>
     <para>
      The name of the new subscription.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="sql-createsubscription-params-connection">
    <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
    <listitem>
     <para>
      The <application>libpq</application> connection string defining how
      to connect to the publisher database.  For details see
      <xref linkend="libpq-connstring"/>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="sql-createsubscription-params-publication">
    <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
    <listitem>
     <para>
      Names of the publications on the publisher to subscribe to.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="sql-createsubscription-params-with">
    <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
    <listitem>
     <para>
      This clause specifies optional parameters for a subscription.
     </para>

     <para>
      The following parameters control what happens during subscription creation:

      <variablelist>

       <varlistentry id="sql-createsubscription-params-with-connect">
        <term><literal>connect</literal> (<type>boolean</type>)</term>
        <listitem>
         <para>
          Specifies whether the <command>CREATE SUBSCRIPTION</command>
          command should connect to the