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

<refentry id="app-pgrecvlogical">
 <indexterm zone="app-pgrecvlogical">
  <primary>pg_recvlogical</primary>
 </indexterm>

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

 <refnamediv>
  <refname>pg_recvlogical</refname>
  <refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_recvlogical</command>
   <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>
   <command>pg_recvlogical</command> controls logical decoding replication
   slots and streams data from such replication slots.
  </para>

  <para>
   It creates a replication-mode connection, so it is subject to the same
   constraints as <xref linkend="app-pgreceivexlog">, plus those for logical
   replication (see <xref linkend="logicaldecoding">).
  </para>
 </refsect1>

 <refsect1>
  <title>Options</title>

   <para>
    At least one of the following options must be specified to select an action:

    <variablelist>

     <varlistentry>
      <term><option>--create-slot</option></term>
      <listitem>
       <para>
        Create a new logical replication slot with the name specified by
        <option>--slot</option>, using the output plugin specified by
        <option>--plugin</option>, for the database specified
        by <option>--dbname</option>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--drop-slot</option></term>
      <listitem>
       <para>
        Drop the replication slot with the name specified
        by <option>--slot</option>, then exit.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--start</option></term>
      <listitem>
       <para>
        Begin streaming changes from the logical replication slot specified
        by <option>--slot</option>, continuing until terminated by a
        signal. If the server side change stream ends with a server shutdown
        or disconnect, retry in a loop unless
        <option>--no-loop</option> is specified.
       </para>

       <para>
        The stream format is determined by the output plugin specified when
        the slot was created.
       </para>

       <para>
        The connection must be to the same database used to create the slot.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    <option>--create-slot</option> and <option>--start</option> can be
    specified together.  <option>--drop-slot</option> cannot be combined with
    another action.
   </para>

   <para>
    The following command-line options control the location and format of the
    output and other replication behavior:

    <variablelist>
     <varlistentry>
      <term><option>-f <replaceable>filename</replaceable></option></term>
      <term><option>--file=<replaceable>filename</replaceable></option></term>
      <listitem>
       <para>
        Write received and decoded transaction data into this
        file. Use <literal>-</> for <systemitem>stdout</systemitem>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
      <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
      <listitem>
       <para>
        Specifies how often <application>pg_recvlogical</application> should
        issue <function>fsync()</function> calls to ensure the output file is
        safely flushed to disk.
       </para>

       <para>
        The server will occasionally request the client to perform a flush and
        report the flush position to the server.  This setting is in addition
        to that, to perform flushes more frequently.
       </para>

       <para>
        Specifying an interval of <literal>0</literal> disables
        issuing <function>fsync()</function> calls altogether, while still
        reporting progress to the server.  In this case, data could be lost in
        the event of a crash.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-I <replaceable>lsn</replaceable></option></term>
      <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
      <listitem>
       <para>
        In <option>--start</option> mode, start replication from the given
        LSN.  For details on the effect of this, see the documentation
        in <xref linkend="logicaldecoding">
        and <xref linkend="protocol-replication">. Ignored in other modes.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--if-not-exists</option></term>
      <listitem>
       <para>
        Do not error out when <option>--create-slot</option> is specified
        and a slot with the specified name already exists.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-n</option></term>
      <term><option>--no-loop</option></term>
      <listitem>
       <para>
        When the connection to the server is lost, do not retry in a loop, just exit.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
      <term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
      <listitem>
       <para>
        Pass the option <replaceable>name</replaceable> to the output plugin with,
        if specified, the option value <replaceable>value</replaceable>. Which
        options exist and their effects depends on the used output plugin.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-P <replaceable>plugin</replaceable></option></term>
      <term><option>--plugin=<replaceable>plugin</replaceable></option></term>
      <listitem>
       <para>
        When creating a slot, use the specified logical decoding output
        plugin. See <xref linkend="logicaldecoding">. This option has no
        effect if the slot already exists.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-s <replaceable>interval_seconds</replaceable></option></term>
      <term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
      <listitem>
       <para>
        This option has the same effect as the option of the same name
        in <xref linkend="app-pgreceivexlog">.  See the description there.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-S <replaceable>slot_name</replaceable></option></term>
      <term><option>--slot=<replaceable>slot_name</replaceable></option></term>
      <listitem>
       <para>
        In <option>--start</option> mode, use the existing logical replication slot named
        <replaceable>slot_name</replaceable>. In <option>--create-slot</option>
        mode, create the slot with this name. In <option>--drop-slot</option>
        mode, delete the slot with this name.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>-v</></term>
       <term><option>--verbose</></term>
       <listitem>
       <para>
        Enables verbose mode.
       </para>
       </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    The following command-line options control the database connection parameters.

    <variablelist>
      <varlistentry>
       <term><option>-d <replaceable>database</replaceable></option></term>
       <term><option>--dbname=<replaceable>database</replaceable></option></term>
       <listitem>
        <para>
         The database to connect to.  See the description of the actions for
         what this means in detail.  This can be a <application>libpq</application> connection string;
         see <xref linkend="LIBPQ-CONNSTRING"> for more information.  Defaults
         to user name.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
       <term><option>--host=<replaceable>hostname-or-ip</replaceable></option></term>
       <listitem>
        <para>
         Specifies the host name of the machine on which the server is
         running.  If the value begins with a slash, it is used as the
         directory for the Unix domain socket. The default is taken
         from the <envar>PGHOST</envar> environment variable, if set,
         else a Unix domain socket connection is attempted.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>-p <replaceable>port</replaceable></option></term>
       <term><option>--port=<replaceable>port</replaceable></option></term>
       <listitem>
        <para>
         Specifies the TCP port or local Unix domain socket file
         extension on which the server is listening for connections.
         Defaults to the <envar>PGPORT</envar> environment variable, if
         set, or a compiled-in default.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>-U <replaceable>user</replaceable></option></term>
       <term><option>--username=<replaceable>user</replaceable></option></term>
       <listitem>
        <para>
         User name to connect as.  Defaults to current operating system user
         name.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>-w</option></term>
       <term><option>--no-password</option></term>
       <listitem>
        <para>
         Never issue a password prompt.  If the server requires
         password authentication and a password is not available by
         other means such as a <filename>.pgpass</filename> file, the
         connection attempt will fail.  This option can be useful in
         batch jobs and scripts where no user is present to enter a
         password.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>-W</option></term>
       <term><option>--password</option></term>
       <listitem>
        <para>
         Force <application>pg_recvlogical</application> to prompt for a
         password before connecting to a database.
        </para>

        <para>
         This option is never essential, since
         <application>pg_recvlogical</application> will automatically prompt
         for a password if the server demands password authentication.
         However, <application>pg_recvlogical</application> will waste a
         connection attempt finding out that the server wants a password.
         In some cases it is worth typing <option>-W</> to avoid the extra
         connection attempt.
        </para>
      </listitem>
     </varlistentry>
     </variablelist>
   </para>

   <para>
    The following additional options are available:

    <variablelist>
     <varlistentry>
       <term><option>-V</></term>
       <term><option>--version</></term>
       <listitem>
       <para>
        Print the <application>pg_recvlogical</application> version and exit.
       </para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-?</></term>
      <term><option>--help</></term>
       <listitem>
        <para>
         Show help about <application>pg_recvlogical</application> command line
         arguments, and exit.
        </para>
       </listitem>
      </varlistentry>
    </variablelist>
   </para>
 </refsect1>

 <refsect1>
  <title>Environment</title>

  <para>
   This utility, like most other <productname>PostgreSQL</> utilities,
   uses the environment variables supported by <application>libpq</>
   (see <xref linkend="libpq-envars">).
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   See <xref linkend="logicaldecoding-example"> for an example.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-pgreceivexlog"></member>
  </simplelist>
 </refsect1>
</refentry>