pgsql/doc/src/sgml/html/protocol-replication.html - master - Ao/MaxReport

pgsql/doc/src/sgml/html/protocol-replication.html
578 строк49 KB
AoAnima
first_commit
13 июл 2026, 17:47
13 июл 2026, 17:47f1a670a
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.4. Streaming Replication Protocol</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sasl-authentication.html" title="54.3. SASL Authentication" /><link rel="next" href="protocol-logical-replication.html" title="54.5. Logical Streaming Replication Protocol" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.4. Streaming Replication Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sasl-authentication.html" title="54.3. SASL Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 54. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 54. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="54.5. Logical Streaming Replication Protocol">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.4. Streaming Replication Protocol <a href="#PROTOCOL-REPLICATION" class="id_link">#</a></h2></div></div></div><p>
   To initiate streaming replication, the frontend sends the
   <code class="literal">replication</code> parameter in the startup message. A Boolean
   value of <code class="literal">true</code> (or <code class="literal">on</code>,
   <code class="literal">yes</code>, <code class="literal">1</code>) tells the backend to go into
   physical replication walsender mode, wherein a small set of replication
   commands, shown below, can be issued instead of SQL statements.
  </p><p>
   Passing <code class="literal">database</code> as the value for the
   <code class="literal">replication</code> parameter instructs the backend to go into
   logical replication walsender mode, connecting to the database specified in
   the <code class="literal">dbname</code> parameter.  In logical replication walsender
   mode, the replication commands shown below as well as normal SQL commands can
   be issued.
  </p><p>
   In either physical replication or logical replication walsender mode, only the
   simple query protocol can be used.
  </p><p>
   For the purpose of testing replication commands, you can make a replication
   connection via <span class="application">psql</span> or any other
   <span class="application">libpq</span>-using tool with a connection string including
   the <code class="literal">replication</code> option,
   e.g.:
</p><pre class="programlisting">
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</pre><p>
   However, it is often more useful to use
   <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a> (for physical replication) or
   <a class="xref" href="app-pgrecvlogical.html" title="pg_recvlogical"><span class="refentrytitle"><span class="application">pg_recvlogical</span></span></a> (for logical replication).
  </p><p>
   Replication commands are logged in the server log when
   <a class="xref" href="runtime-config-logging.html#GUC-LOG-REPLICATION-COMMANDS">log_replication_commands</a> is enabled.
  </p><p>
   The commands accepted in replication mode are:

   </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-IDENTIFY-SYSTEM"><span class="term"><code class="literal">IDENTIFY_SYSTEM</code>
      <a id="id-1.10.6.9.7.1.1.1.2" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-IDENTIFY-SYSTEM" class="id_link">#</a></dt><dd><p>
       Requests the server to identify itself. Server replies with a result
       set of a single row, containing four fields:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">systemid</code> (<code class="type">text</code>)</span></dt><dd><p>
          The unique system identifier identifying the cluster. This
          can be used to check that the base backup used to initialize the
          standby came from the same cluster.
         </p></dd><dt><span class="term"><code class="literal">timeline</code> (<code class="type">int8</code>)</span></dt><dd><p>
          Current timeline ID. Also useful to check that the standby is
          consistent with the primary.
         </p></dd><dt><span class="term"><code class="literal">xlogpos</code> (<code class="type">text</code>)</span></dt><dd><p>
          Current WAL flush location. Useful to get a known location in the
          write-ahead log where streaming can start.
         </p></dd><dt><span class="term"><code class="literal">dbname</code> (<code class="type">text</code>)</span></dt><dd><p>
          Database connected to or null.
         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-SHOW"><span class="term"><code class="literal">SHOW</code> <em class="replaceable"><code>name</code></em>
      <a id="id-1.10.6.9.7.1.2.1.3" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-SHOW" class="id_link">#</a></dt><dd><p>
       Requests the server to send the current setting of a run-time parameter.
       This is similar to the SQL command <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a>.
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
          The name of a run-time parameter. Available parameters are documented
          in <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a>.
         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-TIMELINE-HISTORY"><span class="term"><code class="literal">TIMELINE_HISTORY</code> <em class="replaceable"><code>tli</code></em>
      <a id="id-1.10.6.9.7.1.3.1.3" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-TIMELINE-HISTORY" class="id_link">#</a></dt><dd><p>
       Requests the server to send over the timeline history file for timeline
       <em class="replaceable"><code>tli</code></em>.  Server replies with a
       result set of a single row, containing two fields.  While the fields
       are labeled as <code class="type">text</code>, they effectively return raw bytes,
       with no encoding conversion:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">filename</code> (<code class="type">text</code>)</span></dt><dd><p>
          File name of the timeline history file, e.g., <code class="filename">00000002.history</code>.
         </p></dd><dt><span class="term"><code class="literal">content</code> (<code class="type">text</code>)</span></dt><dd><p>
          Contents of the timeline history file.
         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT"><span class="term"><code class="literal">CREATE_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [ <code class="literal">TEMPORARY</code> ] { <code class="literal">PHYSICAL</code> | <code class="literal">LOGICAL</code> <em class="replaceable"><code>output_plugin</code></em> } [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
      <a id="id-1.10.6.9.7.1.4.1.8" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>
       Create a physical or logical replication
       slot. See <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="26.2.6. Replication Slots">Section 26.2.6</a> for more about
       replication slots.
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
          The name of the slot to create. Must be a valid replication slot
          name (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS-MANIPULATION" title="26.2.6.1. Querying and Manipulating Replication Slots">Section 26.2.6.1</a>).
         </p></dd><dt><span class="term"><em class="replaceable"><code>output_plugin</code></em></span></dt><dd><p>
          The name of the output plugin used for logical decoding
          (see <a class="xref" href="logicaldecoding-output-plugin.html" title="47.6. Logical Decoding Output Plugins">Section 47.6</a>).
         </p></dd><dt><span class="term"><code class="literal">TEMPORARY</code></span></dt><dd><p>
          Specify that this replication slot is a temporary one. Temporary
          slots are not saved to disk and are automatically dropped on error
          or when the session has finished.
         </p></dd></dl></div><p>The following options are supported:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TWO_PHASE [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
          If true, this logical replication slot supports decoding of two-phase
          commit. With this option, commands related to two-phase commit such as
          <code class="literal">PREPARE TRANSACTION</code>, <code class="literal">COMMIT PREPARED</code>
          and <code class="literal">ROLLBACK PREPARED</code> are decoded and transmitted.
          The transaction will be decoded and transmitted at
          <code class="literal">PREPARE TRANSACTION</code> time.
          The default is false.
         </p></dd><dt><span class="term"><code class="literal">RESERVE_WAL [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
          If true, this physical replication slot reserves <acronym class="acronym">WAL</acronym>
          immediately.  Otherwise, <acronym class="acronym">WAL</acronym> is only reserved upon
          connection from a streaming replication client.
          The default is false.
         </p></dd><dt><span class="term"><code class="literal">SNAPSHOT { 'export' | 'use' | 'nothing' }</code></span></dt><dd><p>
          Decides what to do with the snapshot created during logical slot
          initialization. <code class="literal">'export'</code>, which is the default,
          will export the snapshot for use in other sessions. This option can't
          be used inside a transaction.  <code class="literal">'use'</code> will use the
          snapshot for the current transaction executing the command. This
          option must be used in a transaction, and
          <code class="literal">CREATE_REPLICATION_SLOT</code> must be the first command
          run in that transaction.  Finally, <code class="literal">'nothing'</code> will
          just use the snapshot for logical decoding as normal but won't do
          anything else with it.
         </p></dd><dt><span class="term"><code class="literal">FAILOVER [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
          If true, the slot is enabled to be synced to the standbys
          so that logical replication can be resumed after failover.
          The default is false.
         </p></dd></dl></div><p>
       In response to this command, the server will send a one-row result set
       containing the following fields:

       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">slot_name</code> (<code class="type">text</code>)</span></dt><dd><p>
           The name of the newly-created replication slot.
          </p></dd><dt><span class="term"><code class="literal">consistent_point</code> (<code class="type">text</code>)</span></dt><dd><p>
           The WAL location at which the slot became consistent.  This is the
           earliest location from which streaming can start on this replication
           slot.
          </p></dd><dt><span class="term"><code class="literal">snapshot_name</code> (<code class="type">text</code>)</span></dt><dd><p>
           The identifier of the snapshot exported by the command.  The
           snapshot is valid until a new command is executed on this connection
           or the replication connection is closed.  Null if the created slot
           is physical.
          </p></dd><dt><span class="term"><code class="literal">output_plugin</code> (<code class="type">text</code>)</span></dt><dd><p>
           The name of the output plugin used by the newly-created replication
           slot.  Null if the created slot is physical.
          </p></dd></dl></div><p>
      </p></dd><dt id="PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT-LEGACY"><span class="term"><code class="literal">CREATE_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [ <code class="literal">TEMPORARY</code> ] { <code class="literal">PHYSICAL</code> [ <code class="literal">RESERVE_WAL</code> ] | <code class="literal">LOGICAL</code> <em class="replaceable"><code>output_plugin</code></em> [ <code class="literal">EXPORT_SNAPSHOT</code> | <code class="literal">NOEXPORT_SNAPSHOT</code> | <code class="literal">USE_SNAPSHOT</code> | <code class="literal">TWO_PHASE</code> ] }
     </span> <a href="#PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT-LEGACY" class="id_link">#</a></dt><dd><p>
       For compatibility with older releases, this alternative syntax for
       the <code class="literal">CREATE_REPLICATION_SLOT</code> command is still supported.
      </p></dd><dt id="PROTOCOL-REPLICATION-ALTER-REPLICATION-SLOT"><span class="term"><code class="literal">ALTER_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> ( <em class="replaceable"><code>option</code></em> [, ...] )
      <a id="id-1.10.6.9.7.1.6.1.4" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-ALTER-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>
       Change the definition of a replication slot.
       See <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="26.2.6. Replication Slots">Section 26.2.6</a> for more about
       replication slots. This command is currently only supported for logical
       replication slots.
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
          The name of the slot to alter. Must be a valid replication slot
          name (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS-MANIPULATION" title="26.2.6.1. Querying and Manipulating Replication Slots">Section 26.2.6.1</a>).
         </p></dd></dl></div><p>The following options are supported:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TWO_PHASE [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
          If true, this logical replication slot supports decoding of two-phase
          commit. With this option, commands related to two-phase commit such as
          <code class="literal">PREPARE TRANSACTION</code>, <code class="literal">COMMIT PREPARED</code>
          and <code class="literal">ROLLBACK PREPARED</code> are decoded and transmitted.
          The transaction will be decoded and transmitted at
          <code class="literal">PREPARE TRANSACTION</code> time.
         </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">FAILOVER [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
          If true, the slot is enabled to be synced to the standbys
          so that logical replication can be resumed after failover.
         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-READ-REPLICATION-SLOT"><span class="term"><code class="literal">READ_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em>
      <a id="id-1.10.6.9.7.1.7.1.3" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-READ-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>
       Read some information associated with a replication slot. Returns a tuple
       with <code class="literal">NULL</code> values if the replication slot does not
       exist. This command is currently only supported for physical replication
       slots.
      </p><p>
       In response to this command, the server will return a one-row result set,
       containing the following fields:
       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">slot_type</code> (<code class="type">text</code>)</span></dt><dd><p>
           The replication slot's type, either <code class="literal">physical</code> or
           <code class="literal">NULL</code>.
          </p></dd><dt><span class="term"><code class="literal">restart_lsn</code> (<code class="type">text</code>)</span></dt><dd><p>
           The replication slot's <code class="literal">restart_lsn</code>.
          </p></dd><dt><span class="term"><code class="literal">restart_tli</code> (<code class="type">int8</code>)</span></dt><dd><p>
           The timeline ID associated with <code class="literal">restart_lsn</code>,
           following the current timeline history.
          </p></dd></dl></div><p>
      </p></dd><dt id="PROTOCOL-REPLICATION-START-REPLICATION"><span class="term"><code class="literal">START_REPLICATION</code> [ <code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em> ] [ <code class="literal">PHYSICAL</code> ] <em class="replaceable"><code>XXX/XXX</code></em> [ <code class="literal">TIMELINE</code> <em class="replaceable"><code>tli</code></em> ]
      <a id="id-1.10.6.9.7.1.8.1.8" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-START-REPLICATION" class="id_link">#</a></dt><dd><p>
       Instructs server to start streaming WAL, starting at
       WAL location <em class="replaceable"><code>XXX/XXX</code></em>.
       If <code class="literal">TIMELINE</code> option is specified,
       streaming starts on timeline <em class="replaceable"><code>tli</code></em>;
       otherwise, the server's current timeline is selected. The server can
       reply with an error, for example if the requested section of WAL has already
       been recycled. On success, the server responds with a CopyBothResponse
       message, and then starts to stream WAL to the frontend.
      </p><p>
       If a slot's name is provided
       via <em class="replaceable"><code>slot_name</code></em>, it will be updated
       as replication progresses so that the server knows which WAL segments,
       and if <code class="varname">hot_standby_feedback</code> is on which transactions,
       are still needed by the standby.
      </p><p>
       If the client requests a timeline that's not the latest but is part of
       the history of the server, the server will stream all the WAL on that
       timeline starting from the requested start point up to the point where
       the server switched to another timeline. If the client requests
       streaming at exactly the end of an old timeline, the server skips COPY
       mode entirely.
      </p><p>
       After streaming all the WAL on a timeline that is not the latest one,
       the server will end streaming by exiting the COPY mode. When the client
       acknowledges this by also exiting COPY mode, the server sends a result
       set with one row and two columns, indicating the next timeline in this
       server's history. The first column is the next timeline's ID (type <code class="type">int8</code>), and the
       second column is the WAL location where the switch happened (type <code class="type">text</code>). Usually,
       the switch position is the end of the WAL that was streamed, but there
       are corner cases where the server can send some WAL from the old
       timeline that it has not itself replayed before promoting. Finally, the
       server sends two CommandComplete messages (one that ends the CopyData
       and the other ends the <code class="literal">START_REPLICATION</code> itself), and
       is ready to accept a new command.
      </p><p>
       WAL data is sent as a series of CopyData messages;
       see <a class="xref" href="protocol-message-types.html" title="54.6. Message Data Types">Section 54.6</a> and <a class="xref" href="protocol-message-formats.html" title="54.7. Message Formats">Section 54.7</a> for details.
       (This allows other information to be intermixed; in particular the server can send
       an ErrorResponse message if it encounters a failure after beginning
       to stream.)  The payload of each CopyData message from server to the
       client contains a message of one of the following formats:
      </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-XLOGDATA"><span class="term">XLogData (B)</span> <a href="#PROTOCOL-REPLICATION-XLOGDATA" class="id_link">#</a></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('w')</span></dt><dd><p>
             Identifies the message as WAL data.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The starting point of the WAL data in this message.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The current end of WAL on the server.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The server's system clock at the time of transmission, as
             microseconds since midnight on 2000-01-01.
            </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
             A section of the WAL data stream.
            </p><p>
             A single WAL record is never split across two XLogData messages.
             When a WAL record crosses a WAL page boundary, and is therefore
             already split using continuation records, it can be split at the page
             boundary. In other words, the first main WAL record and its
             continuation records can be sent in different XLogData messages.
            </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-PRIMARY-KEEPALIVE-MESSAGE"><span class="term">Primary keepalive message (B)</span> <a href="#PROTOCOL-REPLICATION-PRIMARY-KEEPALIVE-MESSAGE" class="id_link">#</a></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('k')</span></dt><dd><p>
             Identifies the message as a sender keepalive.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The current end of WAL on the server.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The server's system clock at the time of transmission, as
             microseconds since midnight on 2000-01-01.
            </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
             1 means that the client should reply to this message as soon as
             possible, to avoid a timeout disconnect. 0 otherwise.
            </p></dd></dl></div></dd></dl></div><p>
       The receiving process can send replies back to the sender at any time,
       using one of the following message formats (also in the payload of a
       CopyData message):
      </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-STANDBY-STATUS-UPDATE"><span class="term">Standby status update (F)</span> <a href="#PROTOCOL-REPLICATION-STANDBY-STATUS-UPDATE" class="id_link">#</a></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('r')</span></dt><dd><p>
             Identifies the message as a receiver status update.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The location of the last WAL byte + 1 received and written to disk
             in the standby.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The location of the last WAL byte + 1 flushed to disk in
             the standby.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The location of the last WAL byte + 1 applied in the standby.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The client's system clock at the time of transmission, as
             microseconds since midnight on 2000-01-01.
            </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
             If 1, the client requests the server to reply to this message
             immediately. This can be used to ping the server, to test if
             the connection is still healthy.
            </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-HOT-STANDBY-FEEDBACK-MESSAGE"><span class="term">Hot standby feedback message (F)</span> <a href="#PROTOCOL-REPLICATION-HOT-STANDBY-FEEDBACK-MESSAGE" class="id_link">#</a></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('h')</span></dt><dd><p>
             Identifies the message as a hot standby feedback message.
            </p></dd><dt><span class="term">Int64</span></dt><dd><p>
             The client's system clock at the time of transmission, as
             microseconds since midnight on 2000-01-01.
            </p></dd><dt><span class="term">Int32</span></dt><dd><p>
             The standby's current global <code class="literal">xmin</code>, excluding the
             <code class="literal">catalog_xmin</code> from any replication slots. If both
             this value and the following <code class="literal">catalog_xmin</code>
             are 0, this is treated as a notification that hot standby feedback
             will no longer be sent on this connection. Later non-zero messages
             may reinitiate the feedback mechanism.
            </p></dd><dt><span class="term">Int32</span></dt><dd><p>
             The epoch of the global <code class="literal">xmin</code> xid on the standby.
            </p></dd><dt><span class="term">Int32</span></dt><dd><p>
             The lowest <code class="literal">catalog_xmin</code> of any replication
             slots on the standby. Set to 0 if no <code class="literal">catalog_xmin</code>
             exists on the standby or if hot standby feedback is being
             disabled.
            </p></dd><dt><span class="term">Int32</span></dt><dd><p>
             The epoch of the <code class="literal">catalog_xmin</code> xid on the standby.
            </p></dd></dl></div></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-START-REPLICATION-SLOT-LOGICAL"><span class="term"><code class="literal">START_REPLICATION</code> <code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em> <code class="literal">LOGICAL</code> <em class="replaceable"><code>XXX/XXX</code></em> [ ( <em class="replaceable"><code>option_name</code></em> [ <em class="replaceable"><code>option_value</code></em> ] [, ...] ) ]</span> <a href="#PROTOCOL-REPLICATION-START-REPLICATION-SLOT-LOGICAL" class="id_link">#</a></dt><dd><p>
       Instructs server to start streaming WAL for logical replication,
       starting at either WAL location <em class="replaceable"><code>XXX/XXX</code></em> or the slot's
       <code class="literal">confirmed_flush_lsn</code> (see <a class="xref" href="view-pg-replication-slots.html" title="53.20. pg_replication_slots">Section 53.20</a>), whichever is greater. This
       behavior makes it easier for clients to avoid updating their local LSN
       status when there is no data to process. However, starting at a
       different LSN than requested might not catch certain kinds of client
       errors; so the client may wish to check that
       <code class="literal">confirmed_flush_lsn</code> matches its expectations before
       issuing <code class="literal">START_REPLICATION</code>.
      </p><p>
       The server can reply with an error, for example if the
       slot does not exist. On success, the server responds with a CopyBothResponse
       message, and then starts to stream WAL to the frontend.
      </p><p>
       The messages inside the CopyBothResponse messages are of the same format
       documented for <code class="literal">START_REPLICATION ... PHYSICAL</code>, including
       two CommandComplete messages.
      </p><p>
       The output plugin associated with the selected slot is used
       to process the output for streaming.
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
          The name of the slot to stream changes from. This parameter is required,
          and must correspond to an existing logical replication slot created
          with <code class="literal">CREATE_REPLICATION_SLOT</code> in
          <code class="literal">LOGICAL</code> mode.
         </p></dd><dt><span class="term"><em class="replaceable"><code>XXX/XXX</code></em></span></dt><dd><p>
          The WAL location to begin streaming at.
         </p></dd><dt><span class="term"><em class="replaceable"><code>option_name</code></em></span></dt><dd><p>
          The name of an option passed to the slot's logical decoding output
          plugin.  See <a class="xref" href="protocol-logical-replication.html" title="54.5. Logical Streaming Replication Protocol">Section 54.5</a> for
          options that are accepted by the standard (<code class="literal">pgoutput</code>)
          plugin.
         </p></dd><dt><span class="term"><em class="replaceable"><code>option_value</code></em></span></dt><dd><p>
          Optional value, in the form of a string constant, associated with the
          specified option.
         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-DROP-REPLICATION-SLOT"><span class="term">
      <code class="literal">DROP_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [<span class="optional"> <code class="literal">WAIT</code> </span>]
      <a id="id-1.10.6.9.7.1.10.1.4" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-DROP-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>
       Drops a replication slot, freeing any reserved server-side resources.
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
          The name of the slot to drop.
         </p></dd><dt><span class="term"><code class="literal">WAIT</code></span></dt><dd><p>
          This option causes the command to wait if the slot is active until
          it becomes inactive, instead of the default behavior of raising an
          error.
         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-UPLOAD-MANIFEST"><span class="term">
      <code class="literal">UPLOAD_MANIFEST</code>
      <a id="id-1.10.6.9.7.1.11.1.2" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-UPLOAD-MANIFEST" class="id_link">#</a></dt><dd><p>
       Uploads a backup manifest in preparation for taking an incremental
       backup.
      </p></dd><dt id="PROTOCOL-REPLICATION-BASE-BACKUP"><span class="term"><code class="literal">BASE_BACKUP</code> [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
      <a id="id-1.10.6.9.7.1.12.1.3" class="indexterm"></a>
     </span> <a href="#PROTOCOL-REPLICATION-BASE-BACKUP" class="id_link">#</a></dt><dd><p>
       Instructs the server to start streaming a base backup.
       The system will automatically be put in backup mode before the backup
       is started, and taken out of it when the backup is complete. The
       following options are accepted:

       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">LABEL</code> <em class="replaceable"><code>'label'</code></em></span></dt><dd><p>
           Sets the label of the backup. If none is specified, a backup label
           of <code class="literal">base backup</code> will be used. The quoting rules
           for the label are the same as a standard SQL string with
           <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> turned on.
          </p></dd><dt><span class="term"><code class="literal">TARGET</code> <em class="replaceable"><code>'target'</code></em></span></dt><dd><p>
           Tells the server where to send the backup.  If the target is
           <code class="literal">client</code>, which is the default, the backup data is
           sent to the client. If it is <code class="literal">server</code>, the backup
           data is written to the server at the pathname specified by the
           <code class="literal">TARGET_DETAIL</code> option. If it is
           <code class="literal">blackhole</code>, the backup data is not sent
           anywhere; it is simply discarded.
          </p><p>
           The <code class="literal">server</code> target requires superuser privilege or
           being granted the <code class="literal">pg_write_server_files</code> role.
          </p></dd><dt><span class="term"><code class="literal">TARGET_DETAIL</code> <em class="replaceable"><code>'detail'</code></em></span></dt><dd><p>
           Provides additional information about the backup target.
          </p><p>
           Currently, this option can only be used when the backup target is
           <code class="literal">server</code>. It specifies the server directory
           to which the backup should be written.
          </p></dd><dt><span class="term"><code class="literal">PROGRESS [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
           If set to true, request information required to generate a progress
           report. This will send back an approximate size in the header of each
           tablespace, which can be used to calculate how far along the stream
           is done. This is calculated by enumerating all the file sizes once
           before the transfer is even started, and might as such have a
           negative impact on the performance.  In particular, it might take
           longer before the first data
           is streamed. Since the database files can change during the backup,
           the size is only approximate and might both grow and shrink between
           the time of approximation and the sending of the actual files.
           The default is false.
          </p></dd><dt><span class="term"><code class="literal">CHECKPOINT { 'fast' | 'spread' }</code></span></dt><dd><p>
           Sets the type of checkpoint to be performed at the beginning of the
           base backup. The default is <code class="literal">spread</code>.
          </p></dd><dt><span class="term"><code class="literal">WAL [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
           If set to true, include the necessary WAL segments in the backup.
           This will include all the files between start and stop backup in the
           <code class="filename">pg_wal</code> directory of the base directory tar
           file. The default is false.
          </p></dd><dt><span class="term"><code class="literal">WAIT [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
           If set to true, the backup will wait until the last required WAL
           segment has been archived, or emit a warning if WAL archiving is
           not enabled. If false, the backup will neither wait nor warn,
           leaving the client responsible for ensuring the required log is
           available. The default is true.
          </p></dd><dt><span class="term"><code class="literal">COMPRESSION</code> <em class="replaceable"><code>'method'</code></em></span></dt><dd><p>
           Instructs the server to compress the backup using the specified
           method. Currently, the supported methods are <code class="literal">gzip</code>,
           <code class="literal">lz4</code>, and <code class="literal">zstd</code>.
          </p></dd><dt><span class="term"><code class="literal">COMPRESSION_DETAIL</code> <em class="replaceable"><code>detail</code></em></span></dt><dd><p>
           Specifies details for the chosen compression method. This should only
           be used in conjunction with the <code class="literal">COMPRESSION</code>
           option.  If the value is an integer, it specifies the compression
           level.  Otherwise, it should be a comma-separated list of items,
           each of the form <em class="replaceable"><code>keyword</code></em> or
           <em class="replaceable"><code>keyword=value</code></em>. Currently, the supported
           keywords are <code class="literal">level</code>, <code class="literal">long</code> and
           <code class="literal">workers</code>.
          </p><p>
           The <code class="literal">level</code> keyword sets the compression level.
           For <code class="literal">gzip</code> the compression level should be an
           integer between <code class="literal">1</code> and <code class="literal">9</code>
           (default <code class="literal">Z_DEFAULT_COMPRESSION</code> or
           <code class="literal">-1</code>), for <code class="literal">lz4</code> an integer
           between 1 and 12 (default <code class="literal">0</code> for fast compression
           mode), and for <code class="literal">zstd</code> an integer between
           <code class="literal">ZSTD_minCLevel()</code> (usually <code class="literal">-131072</code>)
           and <code class="literal">ZSTD_maxCLevel()</code> (usually <code class="literal">22</code>),
           (default <code class="literal">ZSTD_CLEVEL_DEFAULT</code> or
           <code class="literal">3</code>).
          </p><p>
           The <code class="literal">long</code> keyword enables long-distance matching
           mode, for improved compression ratio, at the expense of higher memory
           use.  Long-distance mode is supported only for
           <code class="literal">zstd</code>.
          </p><p>
           The <code class="literal">workers</code> keyword sets the number of threads
           that should be used for parallel compression. Parallel compression
           is supported only for <code class="literal">zstd</code>.
          </p></dd><dt><span class="term"><code class="literal">MAX_RATE</code> <em class="replaceable"><code>rate</code></em></span></dt><dd><p>
           Limit (throttle) the maximum amount of data transferred from server
           to client per unit of time.  The expected unit is kilobytes per second.
           If this option is specified, the value must either be equal to zero
           or it must fall within the range from 32 kB through 1 GB (inclusive).
           If zero is passed or the option is not specified, no restriction is
           imposed on the transfer.
          </p></dd><dt><span class="term"><code class="literal">TABLESPACE_MAP [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
           If true, include information about symbolic links present in the
           directory <code class="filename">pg_tblspc</code> in a file named
           <code class="filename">tablespace_map</code>. The tablespace map file includes
           each symbolic link name as it exists in the directory
           <code class="filename">pg_tblspc/</code> and the full path of that symbolic link.
           The default is false.
          </p></dd><dt><span class="term"><code class="literal">VERIFY_CHECKSUMS [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
           If true, checksums are verified during a base backup if they are
           enabled. If false, this is skipped. The default is true.
          </p></dd><dt><span class="term"><code class="literal">MANIFEST</code> <em class="replaceable"><code>manifest_option</code></em></span></dt><dd><p>
           When this option is specified with a value of <code class="literal">yes</code>
           or <code class="literal">force-encode</code>, a backup manifest is created
           and sent along with the backup.  The manifest is a list of every
           file present in the backup with the exception of any WAL files that
           may be included. It also stores the size, last modification time, and
           optionally a checksum for each file.
           A value of <code class="literal">force-encode</code> forces all filenames
           to be hex-encoded; otherwise, this type of encoding is performed only
           for files whose names are non-UTF8 octet sequences.
           <code class="literal">force-encode</code> is intended primarily for testing
           purposes, to be sure that clients which read the backup manifest
           can handle this case. For compatibility with previous releases,
           the default is <code class="literal">MANIFEST 'no'</code>.
          </p></dd><dt><span class="term"><code class="literal">MANIFEST_CHECKSUMS</code> <em class="replaceable"><code>checksum_algorithm</code></em></span></dt><dd><p>
           Specifies the checksum algorithm that should be applied to each file included
           in the backup manifest. Currently, the available
           algorithms are <code class="literal">NONE</code>, <code class="literal">CRC32C</code>,
           <code class="literal">SHA224</code>, <code class="literal">SHA256</code>,
           <code class="literal">SHA384</code>, and <code class="literal">SHA512</code>.
           The default is <code class="literal">CRC32C</code>.
          </p></dd><dt><span class="term"><code class="literal">INCREMENTAL</code></span></dt><dd><p>
           Requests an incremental backup. The
           <code class="literal">UPLOAD_MANIFEST</code> command must be executed
           before running a base backup with this option.
          </p></dd></dl></div><p>
      </p><p>
       When the backup is started, the server will first send two
       ordinary result sets, followed by one or more CopyOutResponse
       results.
      </p><p>
       The first ordinary result set contains the starting position of the
       backup, in a single row with two columns. The first column contains
       the start position given in XLogRecPtr format, and the second column
       contains the corresponding timeline ID.
      </p><p>
       The second ordinary result set has one row for each tablespace.
       The fields in this row are:

       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">spcoid</code> (<code class="type">oid</code>)</span></dt><dd><p>
           The OID of the tablespace, or null if it's the base
           directory.
          </p></dd><dt><span class="term"><code class="literal">spclocation</code> (<code class="type">text</code>)</span></dt><dd><p>
           The full path of the tablespace directory, or null
           if it's the base directory.
          </p></dd><dt><span class="term"><code class="literal">size</code> (<code class="type">int8</code>)</span></dt><dd><p>
           The approximate size of the tablespace, in kilobytes (1024 bytes),
           if progress report has been requested; otherwise it's null.
          </p></dd></dl></div><p>
      </p><p>
       After the second regular result set, a CopyOutResponse will be sent.
       The payload of each CopyData message will contain a message in one of
       the following formats:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">new archive (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('n')</span></dt><dd><p>
            Identifies the message as indicating the start of a new archive.
            There will be one archive for the main data directory and one
            for each additional tablespace; each will use tar format
            (following the <span class="quote">“<span class="quote">ustar interchange format</span>”</span> specified
            in the POSIX 1003.1-2008 standard).
           </p></dd><dt><span class="term">String</span></dt><dd><p>
            The file name for this archive.
           </p></dd><dt><span class="term">String</span></dt><dd><p>
            For the main data directory, an empty string. For other
            tablespaces, the full path to the directory from which this
            archive was created.
           </p></dd></dl></div></dd><dt><span class="term">manifest (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('m')</span></dt><dd><p>
            Identifies the message as indicating the start of the backup
            manifest.
           </p></dd></dl></div></dd><dt><span class="term">archive or manifest data (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('d')</span></dt><dd><p>
            Identifies the message as containing archive or manifest data.
           </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
            Data bytes.
           </p></dd></dl></div></dd><dt><span class="term">progress report (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
            Identifies the message as a progress report.
           </p></dd><dt><span class="term">Int64</span></dt><dd><p>
            The number of bytes from the current tablespace for which
            processing has been completed.
           </p></dd></dl></div></dd></dl></div><p>
       After the CopyOutResponse, or all such responses, have been sent, a
       final ordinary result set will be sent, containing the WAL end position
       of the backup, in the same format as the start position.
      </p><p>
       The tar archive for the data directory and each tablespace will contain
       all files in the directories, regardless of whether they are
       <span class="productname">PostgreSQL</span> files or other files added to the same
       directory. The only excluded files are:

       </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
          <code class="filename">postmaster.pid</code>
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          <code class="filename">postmaster.opts</code>
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          <code class="filename">pg_internal.init</code> (found in multiple directories)
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          Various temporary files and directories created during the operation
          of the PostgreSQL server, such as any file or directory beginning
          with <code class="filename">pgsql_tmp</code> and temporary relations.
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          Unlogged relations, except for the init fork which is required to
          recreate the (empty) unlogged relation on recovery.
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          <code class="filename">pg_wal</code>, including subdirectories. If the backup is run
          with WAL files included, a synthesized version of <code class="filename">pg_wal</code> will be
          included, but it will only contain the files necessary for the
          backup to work, not the rest of the contents.
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          <code class="filename">pg_dynshmem</code>, <code class="filename">pg_notify</code>,
          <code class="filename">pg_replslot</code>, <code class="filename">pg_serial</code>,
          <code class="filename">pg_snapshots</code>, <code class="filename">pg_stat_tmp</code>, and
          <code class="filename">pg_subtrans</code> are copied as empty directories (even if
          they are symbolic links).
         </p></li><li class="listitem" style="list-style-type: disc"><p>
          Files other than regular files and directories, such as symbolic
          links (other than for the directories listed above) and special
          device and operating system files, are skipped.  (Symbolic links
          in <code class="filename">pg_tblspc</code> are maintained.)
         </p></li></ul></div><p>
       Owner, group, and file mode are set if the underlying file system on
       the server supports it.
      </p></dd></dl></div><p>
  </p><p>
   In all the above commands,
   when specifying a parameter of type <code class="type">boolean</code> the
   <em class="replaceable"><code>value</code></em> part can be omitted,
   which is equivalent to specifying <code class="literal">TRUE</code>.
  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sasl-authentication.html" title="54.3. SASL Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 54. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="54.5. Logical Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.3. SASL Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.5. Logical Streaming Replication Protocol</td></tr></table></div></body></html>