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

<refentry id="app-pgreceivewal">
 <indexterm zone="app-pgreceivewal">
  <primary>pg_receivewal</primary>
 </indexterm>

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

 <refnamediv>
  <refname>pg_receivewal</refname>
  <refpurpose>stream write-ahead logs from a <productname>PostgreSQL</productname> server</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_receivewal</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>
   <application>pg_receivewal</application> is used to stream the write-ahead log
   from a running <productname>PostgreSQL</productname> cluster. The write-ahead
   log is streamed using the streaming replication protocol, and is written
   to a local directory of files. This directory can be used as the archive
   location for doing a restore using point-in-time recovery (see
   <xref linkend="continuous-archiving"/>).
  </para>

  <para>
   <application>pg_receivewal</application> streams the write-ahead
   log in real time as it's being generated on the server, and does not wait
   for segments to complete like <xref linkend="guc-archive-command"/> and
   <xref linkend="guc-archive-library"/> do.
   For this reason, it is not necessary to set
   <xref linkend="guc-archive-timeout"/> when using
    <application>pg_receivewal</application>.
  </para>

  <para>
   Unlike the WAL receiver of a PostgreSQL standby server, <application>pg_receivewal</application>
   by default flushes WAL data only when a WAL file is closed.
   The option <option>--synchronous</option> must be specified to flush WAL data
   in real time. Since <application>pg_receivewal</application> does not
   apply WAL, you should not allow it to become a synchronous standby when
   <xref linkend="guc-synchronous-commit"/> equals
   <literal>remote_apply</literal>. If it does, it will appear to be a
   standby that never catches up, and will cause transaction commits to
   block. To avoid this, you should either configure an appropriate value
   for <xref linkend="guc-synchronous-standby-names"/>, or specify
   <varname>application_name</varname> for
   <application>pg_receivewal</application> that does not match it, or
   change the value of <varname>synchronous_commit</varname> to
   something other than <literal>remote_apply</literal>.
  </para>

  <para>
   The write-ahead log is streamed over a regular
   <productname>PostgreSQL</productname> connection and uses the replication
   protocol. The connection must be made with a user having
   <literal>REPLICATION</literal> permissions (see
   <xref linkend="role-attributes"/>) or a superuser, and
   <filename>pg_hba.conf</filename> must permit the replication connection.
   The server must also be configured with
   <xref linkend="guc-max-wal-senders"/> set high enough to leave at least
   one session available for the stream.
  </para>

  <para>
   The starting point of the write-ahead log streaming is calculated when
   <application>pg_receivewal</application> starts:
   <orderedlist>
    <listitem>
     <para>
      First, scan the directory where the WAL segment files are written and
      find the newest completed segment file, using as the starting point the
      beginning of the next WAL segment file.
     </para>
    </listitem>

    <listitem>
     <para>
      If a starting point cannot be calculated with the previous method,
      and if a replication slot is used, an extra
      <command>READ_REPLICATION_SLOT</command> command is issued to retrieve
      the slot's <literal>restart_lsn</literal> to use as the starting point.
      This option is only available when streaming write-ahead logs from
      <productname>PostgreSQL</productname> 15 and up.
     </para>