<!--
doc/src/sgml/ref/pg_createsubscriber.sgml
PostgreSQL documentation
-->

<refentry id="app-pgcreatesubscriber">
 <indexterm zone="app-pgcreatesubscriber">
  <primary>pg_createsubscriber</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>pg_createsubscriber</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_createsubscriber</refname>
  <refpurpose>convert a physical replica into a new logical replica</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_createsubscriber</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <group choice="plain">
    <group choice="req">
     <arg choice="plain"><option>-d</option></arg>
     <arg choice="plain"><option>--database</option></arg>
    </group>
    <replaceable>dbname</replaceable>
    <group choice="req">
     <arg choice="plain"><option>-D</option> </arg>
     <arg choice="plain"><option>--pgdata</option></arg>
    </group>
    <replaceable>datadir</replaceable>
    <group choice="req">
     <arg choice="plain"><option>-P</option></arg>
     <arg choice="plain"><option>--publisher-server</option></arg>
    </group>
    <replaceable>connstr</replaceable>
   </group>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <application>pg_createsubscriber</application> creates a new logical
   replica from a physical standby server.  All tables in the specified
   database are included in the <link linkend="logical-replication">logical
   replication</link> setup.  A pair of
   publication and subscription objects are created for each database.  It
   must be run at the target server.
  </para>

  <para>
   After a successful run, the state of the target server is analogous to a
   fresh logical replication setup.  The main difference between the logical
   replication setup and <application>pg_createsubscriber</application> is how
   the data synchronization is done. <application>pg_createsubscriber</application>
   does not copy the initial table data. It does only the synchronization phase,
   which ensures each table is brought up to a synchronized state.
  </para>

  <para>
   <application>pg_createsubscriber</application> targets large database
   systems because in logical replication setup, most of the time is spent
   doing the initial data copy.  Furthermore, a side effect of this long time
   spent synchronizing data is usually a large amount of changes to be applied
   (that were produced during the initial data copy), which increases even
   more the time when the logical replica will be available. For smaller
   databases, it is recommended to set up logical replication with initial data
   synchronization.  For details, see the <command>CREATE SUBSCRIPTION</command>
   <link linkend="sql-createsubscription-params-with-copy-data">
   <literal>copy_data</literal></link> option.

  </para>
 </refsect1>

 <refsect1>
  <title>Options</title>

  <para>
   <application>pg_createsubscriber</application> accepts the following
   command-line arguments:

   <variablelist>
    <varlistentry>
     <term><option>-a</option></term>
     <term><option>--all</option></term>
     <listitem>
      <para>
       Create one subscription per database on the target server. Exceptions
       are template databases and databases that don't allow connections.
       To discover the list of all databases, connect to the source server
       using the database name specified in the <option>--publisher-server</option>
       connection string, or if not specified, the <literal>postgres</literal>
       database will be used, or if that does not exist, <literal>template1</literal>
       will be used.
       Automatically generated names for subscriptions, publications, and
       replication slots are used when this option is specified.
       This option cannot be used along with <option>--database</option>,