granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/pg_recvlogical.sgml

   1 <!--
   2 doc/src/sgml/ref/pg_recvlogical.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="app-pgrecvlogical">
   7  <indexterm zone="app-pgrecvlogical">
   8   <primary>pg_recvlogical</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle><application>pg_recvlogical</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>pg_recvlogical</refname>
  19   <refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>pg_recvlogical</command>
  25    <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
  26   </cmdsynopsis>
  27  </refsynopsisdiv>
  28
  29  <refsect1>
  30   <title>Description</title>
  31   <para>
  32    <command>pg_recvlogical</command> controls logical decoding replication
  33    slots and streams data from such replication slots.
  34   </para>
  35
  36   <para>
  37    It creates a replication-mode connection, so it is subject to the same
  38    constraints as <xref linkend="app-pgreceivewal">, plus those for logical
  39    replication (see <xref linkend="logicaldecoding">).
  40   </para>
  41
  42   <para>
  43    <command>pg_recvlogical</> has no equivalent to the logical decoding
  44    SQL interface's peek and get modes. It sends replay confirmations for
  45    data lazily as it receives it and on clean exit. To examine pending data on
  46     a slot without consuming it, use
  47    <link linkend="functions-replication"><function>pg_logical_slot_peek_changes</></>.
  48   </para>
  49  </refsect1>
  50
  51  <refsect1>
  52   <title>Options</title>
  53
  54    <para>
  55     At least one of the following options must be specified to select an action:
  56
  57     <variablelist>
  58
  59      <varlistentry>
  60       <term><option>--create-slot</option></term>
  61       <listitem>
  62        <para>
  63         Create a new logical replication slot with the name specified by
  64         <option>--slot</option>, using the output plugin specified by
  65         <option>--plugin</option>, for the database specified
  66         by <option>--dbname</option>.
  67        </para>
  68       </listitem>
  69      </varlistentry>
  70
  71      <varlistentry>
  72       <term><option>--drop-slot</option></term>
  73       <listitem>
  74        <para>
  75         Drop the replication slot with the name specified
  76         by <option>--slot</option>, then exit.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><option>--start</option></term>
  83       <listitem>
  84        <para>
  85         Begin streaming changes from the logical replication slot specified
  86         by <option>--slot</option>, continuing until terminated by a
  87         signal. If the server side change stream ends with a server shutdown
  88         or disconnect, retry in a loop unless
  89         <option>--no-loop</option> is specified.
  90        </para>
  91
  92        <para>
  93         The stream format is determined by the output plugin specified when
  94         the slot was created.
  95        </para>
  96
  97        <para>
  98         The connection must be to the same database used to create the slot.
  99        </para>
 100       </listitem>
 101      </varlistentry>
 102     </variablelist>
 103    </para>
 104
 105    <para>
 106     <option>--create-slot</option> and <option>--start</option> can be
 107     specified together.  <option>--drop-slot</option> cannot be combined with
 108     another action.
 109    </para>
 110
 111    <para>
 112     The following command-line options control the location and format of the
 113     output and other replication behavior:
 114
 115     <variablelist>
 116      <varlistentry>
 117       <term><option>-E <replaceable>lsn</replaceable></option></term>
 118       <term><option>--endpos=<replaceable>lsn</replaceable></option></term>
 119       <listitem>
 120        <para>
 121         In <option>--start</option> mode, automatically stop replication
 122         and exit with normal exit status 0 when receiving reaches the
 123         specified LSN.  If specified when not in <option>--start</option>
 124         mode, an error is raised.
 125        </para>
 126
 127        <para>
 128         If there's a record with LSN exactly equal to <replaceable>lsn</>,
 129         the record will be output.
 130        </para>
 131
 132        <para>
 133         The <option>--endpos</option> option is not aware of transaction
 134         boundaries and may truncate output partway through a transaction.
 135         Any partially output transaction will not be consumed and will be
 136         replayed again when the slot is next read from. Individual messages
 137         are never truncated.
 138        </para>
 139       </listitem>
 140      </varlistentry>
 141
 142      <varlistentry>
 143       <term><option>-f <replaceable>filename</replaceable></option></term>
 144       <term><option>--file=<replaceable>filename</replaceable></option></term>
 145       <listitem>
 146        <para>
 147         Write received and decoded transaction data into this
 148         file. Use <literal>-</> for <systemitem>stdout</systemitem>.
 149        </para>
 150       </listitem>
 151      </varlistentry>
 152
 153      <varlistentry>
 154       <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
 155       <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
 156       <listitem>
 157        <para>
 158         Specifies how often <application>pg_recvlogical</application> should
 159         issue <function>fsync()</function> calls to ensure the output file is
 160         safely flushed to disk.
 161        </para>
 162
 163        <para>
 164         The server will occasionally request the client to perform a flush and
 165         report the flush position to the server.  This setting is in addition
 166         to that, to perform flushes more frequently.
 167        </para>
 168
 169        <para>
 170         Specifying an interval of <literal>0</literal> disables
 171         issuing <function>fsync()</function> calls altogether, while still
 172         reporting progress to the server.  In this case, data could be lost in
 173         the event of a crash.
 174        </para>
 175       </listitem>
 176      </varlistentry>
 177
 178      <varlistentry>
 179       <term><option>-I <replaceable>lsn</replaceable></option></term>
 180       <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
 181       <listitem>
 182        <para>
 183         In <option>--start</option> mode, start replication from the given
 184         LSN.  For details on the effect of this, see the documentation
 185         in <xref linkend="logicaldecoding">
 186         and <xref linkend="protocol-replication">. Ignored in other modes.
 187        </para>
 188       </listitem>
 189      </varlistentry>
 190
 191      <varlistentry>
 192       <term><option>--if-not-exists</option></term>
 193       <listitem>
 194        <para>
 195         Do not error out when <option>--create-slot</option> is specified
 196         and a slot with the specified name already exists.
 197        </para>
 198       </listitem>
 199      </varlistentry>
 200
 201      <varlistentry>
 202       <term><option>-n</option></term>
 203       <term><option>--no-loop</option></term>
 204       <listitem>
 205        <para>
 206         When the connection to the server is lost, do not retry in a loop, just exit.
 207        </para>
 208       </listitem>
 209      </varlistentry>
 210
 211      <varlistentry>
 212       <term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
 213       <term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
 214       <listitem>
 215        <para>
 216         Pass the option <replaceable>name</replaceable> to the output plugin with,
 217         if specified, the option value <replaceable>value</replaceable>. Which
 218         options exist and their effects depends on the used output plugin.
 219        </para>
 220       </listitem>
 221      </varlistentry>
 222
 223      <varlistentry>
 224       <term><option>-P <replaceable>plugin</replaceable></option></term>
 225       <term><option>--plugin=<replaceable>plugin</replaceable></option></term>
 226       <listitem>
 227        <para>
 228         When creating a slot, use the specified logical decoding output
 229         plugin. See <xref linkend="logicaldecoding">. This option has no
 230         effect if the slot already exists.
 231        </para>
 232       </listitem>
 233      </varlistentry>
 234
 235      <varlistentry>
 236       <term><option>-s <replaceable>interval_seconds</replaceable></option></term>
 237       <term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
 238       <listitem>
 239        <para>
 240         This option has the same effect as the option of the same name
 241         in <xref linkend="app-pgreceivewal">.  See the description there.
 242        </para>
 243       </listitem>
 244      </varlistentry>
 245
 246      <varlistentry>
 247       <term><option>-S <replaceable>slot_name</replaceable></option></term>
 248       <term><option>--slot=<replaceable>slot_name</replaceable></option></term>
 249       <listitem>
 250        <para>
 251         In <option>--start</option> mode, use the existing logical replication slot named
 252         <replaceable>slot_name</replaceable>. In <option>--create-slot</option>
 253         mode, create the slot with this name. In <option>--drop-slot</option>
 254         mode, delete the slot with this name.
 255        </para>
 256       </listitem>
 257      </varlistentry>
 258
 259      <varlistentry>
 260        <term><option>-v</></term>
 261        <term><option>--verbose</></term>
 262        <listitem>
 263        <para>
 264         Enables verbose mode.
 265        </para>
 266        </listitem>
 267      </varlistentry>
 268     </variablelist>
 269    </para>
 270
 271    <para>
 272     The following command-line options control the database connection parameters.
 273
 274     <variablelist>
 275       <varlistentry>
 276        <term><option>-d <replaceable>database</replaceable></option></term>
 277        <term><option>--dbname=<replaceable>database</replaceable></option></term>
 278        <listitem>
 279         <para>
 280          The database to connect to.  See the description of the actions for
 281          what this means in detail.  This can be a <application>libpq</application> connection string;
 282          see <xref linkend="LIBPQ-CONNSTRING"> for more information.  Defaults
 283          to user name.
 284         </para>
 285        </listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289        <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
 290        <term><option>--host=<replaceable>hostname-or-ip</replaceable></option></term>
 291        <listitem>
 292         <para>
 293          Specifies the host name of the machine on which the server is
 294          running.  If the value begins with a slash, it is used as the
 295          directory for the Unix domain socket. The default is taken
 296          from the <envar>PGHOST</envar> environment variable, if set,
 297          else a Unix domain socket connection is attempted.
 298         </para>
 299        </listitem>
 300       </varlistentry>
 301
 302       <varlistentry>
 303        <term><option>-p <replaceable>port</replaceable></option></term>
 304        <term><option>--port=<replaceable>port</replaceable></option></term>
 305        <listitem>
 306         <para>
 307          Specifies the TCP port or local Unix domain socket file
 308          extension on which the server is listening for connections.
 309          Defaults to the <envar>PGPORT</envar> environment variable, if
 310          set, or a compiled-in default.
 311         </para>
 312        </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316        <term><option>-U <replaceable>user</replaceable></option></term>
 317        <term><option>--username=<replaceable>user</replaceable></option></term>
 318        <listitem>
 319         <para>
 320          User name to connect as.  Defaults to current operating system user
 321          name.
 322         </para>
 323        </listitem>
 324       </varlistentry>
 325
 326       <varlistentry>
 327        <term><option>-w</option></term>
 328        <term><option>--no-password</option></term>
 329        <listitem>
 330         <para>
 331          Never issue a password prompt.  If the server requires
 332          password authentication and a password is not available by
 333          other means such as a <filename>.pgpass</filename> file, the
 334          connection attempt will fail.  This option can be useful in
 335          batch jobs and scripts where no user is present to enter a
 336          password.
 337         </para>
 338        </listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342        <term><option>-W</option></term>
 343        <term><option>--password</option></term>
 344        <listitem>
 345         <para>
 346          Force <application>pg_recvlogical</application> to prompt for a
 347          password before connecting to a database.
 348         </para>
 349
 350         <para>
 351          This option is never essential, since
 352          <application>pg_recvlogical</application> will automatically prompt
 353          for a password if the server demands password authentication.
 354          However, <application>pg_recvlogical</application> will waste a
 355          connection attempt finding out that the server wants a password.
 356          In some cases it is worth typing <option>-W</> to avoid the extra
 357          connection attempt.
 358         </para>
 359       </listitem>
 360      </varlistentry>
 361      </variablelist>
 362    </para>
 363
 364    <para>
 365     The following additional options are available:
 366
 367     <variablelist>
 368      <varlistentry>
 369        <term><option>-V</></term>
 370        <term><option>--version</></term>
 371        <listitem>
 372        <para>
 373         Print the <application>pg_recvlogical</application> version and exit.
 374        </para>
 375        </listitem>
 376      </varlistentry>
 377
 378      <varlistentry>
 379       <term><option>-?</></term>
 380       <term><option>--help</></term>
 381        <listitem>
 382         <para>
 383          Show help about <application>pg_recvlogical</application> command line
 384          arguments, and exit.
 385         </para>
 386        </listitem>
 387       </varlistentry>
 388     </variablelist>
 389    </para>
 390  </refsect1>
 391
 392  <refsect1>
 393   <title>Environment</title>
 394
 395   <para>
 396    This utility, like most other <productname>PostgreSQL</> utilities,
 397    uses the environment variables supported by <application>libpq</>
 398    (see <xref linkend="libpq-envars">).
 399   </para>
 400  </refsect1>
 401
 402  <refsect1>
 403   <title>Examples</title>
 404
 405   <para>
 406    See <xref linkend="logicaldecoding-example"> for an example.
 407   </para>
 408  </refsect1>
 409
 410  <refsect1>
 411   <title>See Also</title>
 412
 413   <simplelist type="inline">
 414    <member><xref linkend="app-pgreceivewal"></member>
 415   </simplelist>
 416  </refsect1>
 417 </refentry>