Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
protocol-replication.html538 linesDownload Raw Back to html
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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>55.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="55.3. SASL Authentication" /><link rel="next" href="protocol-logical-replication.html" title="55.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">55.4. Streaming Replication Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sasl-authentication.html" title="55.3. SASL Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="55.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">55.4. Streaming Replication Protocol <a href="#PROTOCOL-REPLICATION" class="id_link">#</a></h2></div></div></div><p>3   To initiate streaming replication, the frontend sends the4   <code class="literal">replication</code> parameter in the startup message. A Boolean5   value of <code class="literal">true</code> (or <code class="literal">on</code>,6   <code class="literal">yes</code>, <code class="literal">1</code>) tells the backend to go into7   physical replication walsender mode, wherein a small set of replication8   commands, shown below, can be issued instead of SQL statements.9  </p><p>10   Passing <code class="literal">database</code> as the value for the11   <code class="literal">replication</code> parameter instructs the backend to go into12   logical replication walsender mode, connecting to the database specified in13   the <code class="literal">dbname</code> parameter.  In logical replication walsender14   mode, the replication commands shown below as well as normal SQL commands can15   be issued.16  </p><p>17   In either physical replication or logical replication walsender mode, only the18   simple query protocol can be used.19  </p><p>20   For the purpose of testing replication commands, you can make a replication21   connection via <span class="application">psql</span> or any other22   <span class="application">libpq</span>-using tool with a connection string including23   the <code class="literal">replication</code> option,24   e.g.:25</p><pre class="programlisting">26psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"27</pre><p>28   However, it is often more useful to use29   <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a> (for physical replication) or30   <a class="xref" href="app-pgrecvlogical.html" title="pg_recvlogical"><span class="refentrytitle"><span class="application">pg_recvlogical</span></span></a> (for logical replication).31  </p><p>32   Replication commands are logged in the server log when33   <a class="xref" href="runtime-config-logging.html#GUC-LOG-REPLICATION-COMMANDS">log_replication_commands</a> is enabled.34  </p><p>35   The commands accepted in replication mode are:36 37   </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-IDENTIFY-SYSTEM"><span class="term"><code class="literal">IDENTIFY_SYSTEM</code>38      <a id="id-1.10.6.9.7.1.1.1.2" class="indexterm"></a>39     </span> <a href="#PROTOCOL-REPLICATION-IDENTIFY-SYSTEM" class="id_link">#</a></dt><dd><p>40       Requests the server to identify itself. Server replies with a result41       set of a single row, containing four fields:42      </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>43          The unique system identifier identifying the cluster. This44          can be used to check that the base backup used to initialize the45          standby came from the same cluster.46         </p></dd><dt><span class="term"><code class="literal">timeline</code> (<code class="type">int8</code>)</span></dt><dd><p>47          Current timeline ID. Also useful to check that the standby is48          consistent with the primary.49         </p></dd><dt><span class="term"><code class="literal">xlogpos</code> (<code class="type">text</code>)</span></dt><dd><p>50          Current WAL flush location. Useful to get a known location in the51          write-ahead log where streaming can start.52         </p></dd><dt><span class="term"><code class="literal">dbname</code> (<code class="type">text</code>)</span></dt><dd><p>53          Database connected to or null.54         </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>55      <a id="id-1.10.6.9.7.1.2.1.3" class="indexterm"></a>56     </span> <a href="#PROTOCOL-REPLICATION-SHOW" class="id_link">#</a></dt><dd><p>57       Requests the server to send the current setting of a run-time parameter.58       This is similar to the SQL command <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a>.59      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>60          The name of a run-time parameter. Available parameters are documented61          in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.62         </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>63      <a id="id-1.10.6.9.7.1.3.1.3" class="indexterm"></a>64     </span> <a href="#PROTOCOL-REPLICATION-TIMELINE-HISTORY" class="id_link">#</a></dt><dd><p>65       Requests the server to send over the timeline history file for timeline66       <em class="replaceable"><code>tli</code></em>.  Server replies with a67       result set of a single row, containing two fields.  While the fields68       are labeled as <code class="type">text</code>, they effectively return raw bytes,69       with no encoding conversion:70      </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>71          File name of the timeline history file, e.g., <code class="filename">00000002.history</code>.72         </p></dd><dt><span class="term"><code class="literal">content</code> (<code class="type">text</code>)</span></dt><dd><p>73          Contents of the timeline history file.74         </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> [, ...] ) ]75      <a id="id-1.10.6.9.7.1.4.1.8" class="indexterm"></a>76     </span> <a href="#PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>77       Create a physical or logical replication78       slot. See <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a> for more about79       replication slots.80      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>81          The name of the slot to create. Must be a valid replication slot82          name (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS-MANIPULATION" title="27.2.6.1. Querying and Manipulating Replication Slots">Section 27.2.6.1</a>).83         </p></dd><dt><span class="term"><em class="replaceable"><code>output_plugin</code></em></span></dt><dd><p>84          The name of the output plugin used for logical decoding85          (see <a class="xref" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Section 49.6</a>).86         </p></dd><dt><span class="term"><code class="literal">TEMPORARY</code></span></dt><dd><p>87          Specify that this replication slot is a temporary one. Temporary88          slots are not saved to disk and are automatically dropped on error89          or when the session has finished.90         </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>91          If true, this logical replication slot supports decoding of two-phase92          commit. With this option, commands related to two-phase commit such as93          <code class="literal">PREPARE TRANSACTION</code>, <code class="literal">COMMIT PREPARED</code>94          and <code class="literal">ROLLBACK PREPARED</code> are decoded and transmitted.95          The transaction will be decoded and transmitted at96          <code class="literal">PREPARE TRANSACTION</code> time.97          The default is false.98         </p></dd><dt><span class="term"><code class="literal">RESERVE_WAL [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>99          If true, this physical replication slot reserves <acronym class="acronym">WAL</acronym>100          immediately.  Otherwise, <acronym class="acronym">WAL</acronym> is only reserved upon101          connection from a streaming replication client.102          The default is false.103         </p></dd><dt><span class="term"><code class="literal">SNAPSHOT { 'export' | 'use' | 'nothing' }</code></span></dt><dd><p>104          Decides what to do with the snapshot created during logical slot105          initialization. <code class="literal">'export'</code>, which is the default,106          will export the snapshot for use in other sessions. This option can't107          be used inside a transaction.  <code class="literal">'use'</code> will use the108          snapshot for the current transaction executing the command. This109          option must be used in a transaction, and110          <code class="literal">CREATE_REPLICATION_SLOT</code> must be the first command111          run in that transaction.  Finally, <code class="literal">'nothing'</code> will112          just use the snapshot for logical decoding as normal but won't do113          anything else with it.114         </p></dd></dl></div><p>115       In response to this command, the server will send a one-row result set116       containing the following fields:117 118       </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>119           The name of the newly-created replication slot.120          </p></dd><dt><span class="term"><code class="literal">consistent_point</code> (<code class="type">text</code>)</span></dt><dd><p>121           The WAL location at which the slot became consistent.  This is the122           earliest location from which streaming can start on this replication123           slot.124          </p></dd><dt><span class="term"><code class="literal">snapshot_name</code> (<code class="type">text</code>)</span></dt><dd><p>125           The identifier of the snapshot exported by the command.  The126           snapshot is valid until a new command is executed on this connection127           or the replication connection is closed.  Null if the created slot128           is physical.129          </p></dd><dt><span class="term"><code class="literal">output_plugin</code> (<code class="type">text</code>)</span></dt><dd><p>130           The name of the output plugin used by the newly-created replication131           slot.  Null if the created slot is physical.132          </p></dd></dl></div><p>133      </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> ] }134     </span> <a href="#PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT-LEGACY" class="id_link">#</a></dt><dd><p>135       For compatibility with older releases, this alternative syntax for136       the <code class="literal">CREATE_REPLICATION_SLOT</code> command is still supported.137      </p></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>138      <a id="id-1.10.6.9.7.1.6.1.3" class="indexterm"></a>139     </span> <a href="#PROTOCOL-REPLICATION-READ-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>140       Read some information associated with a replication slot. Returns a tuple141       with <code class="literal">NULL</code> values if the replication slot does not142       exist. This command is currently only supported for physical replication143       slots.144      </p><p>145       In response to this command, the server will return a one-row result set,146       containing the following fields:147       </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>148           The replication slot's type, either <code class="literal">physical</code> or149           <code class="literal">NULL</code>.150          </p></dd><dt><span class="term"><code class="literal">restart_lsn</code> (<code class="type">text</code>)</span></dt><dd><p>151           The replication slot's <code class="literal">restart_lsn</code>.152          </p></dd><dt><span class="term"><code class="literal">restart_tli</code> (<code class="type">int8</code>)</span></dt><dd><p>153           The timeline ID associated with <code class="literal">restart_lsn</code>,154           following the current timeline history.155          </p></dd></dl></div><p>156      </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> ]157      <a id="id-1.10.6.9.7.1.7.1.8" class="indexterm"></a>158     </span> <a href="#PROTOCOL-REPLICATION-START-REPLICATION" class="id_link">#</a></dt><dd><p>159       Instructs server to start streaming WAL, starting at160       WAL location <em class="replaceable"><code>XXX/XXX</code></em>.161       If <code class="literal">TIMELINE</code> option is specified,162       streaming starts on timeline <em class="replaceable"><code>tli</code></em>;163       otherwise, the server's current timeline is selected. The server can164       reply with an error, for example if the requested section of WAL has already165       been recycled. On success, the server responds with a CopyBothResponse166       message, and then starts to stream WAL to the frontend.167      </p><p>168       If a slot's name is provided169       via <em class="replaceable"><code>slot_name</code></em>, it will be updated170       as replication progresses so that the server knows which WAL segments,171       and if <code class="varname">hot_standby_feedback</code> is on which transactions,172       are still needed by the standby.173      </p><p>174       If the client requests a timeline that's not the latest but is part of175       the history of the server, the server will stream all the WAL on that176       timeline starting from the requested start point up to the point where177       the server switched to another timeline. If the client requests178       streaming at exactly the end of an old timeline, the server skips COPY179       mode entirely.180      </p><p>181       After streaming all the WAL on a timeline that is not the latest one,182       the server will end streaming by exiting the COPY mode. When the client183       acknowledges this by also exiting COPY mode, the server sends a result184       set with one row and two columns, indicating the next timeline in this185       server's history. The first column is the next timeline's ID (type <code class="type">int8</code>), and the186       second column is the WAL location where the switch happened (type <code class="type">text</code>). Usually,187       the switch position is the end of the WAL that was streamed, but there188       are corner cases where the server can send some WAL from the old189       timeline that it has not itself replayed before promoting. Finally, the190       server sends two CommandComplete messages (one that ends the CopyData191       and the other ends the <code class="literal">START_REPLICATION</code> itself), and192       is ready to accept a new command.193      </p><p>194       WAL data is sent as a series of CopyData messages.  (This allows195       other information to be intermixed; in particular the server can send196       an ErrorResponse message if it encounters a failure after beginning197       to stream.)  The payload of each CopyData message from server to the198       client contains a message of one of the following formats:199      </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>200             Identifies the message as WAL data.201            </p></dd><dt><span class="term">Int64</span></dt><dd><p>202             The starting point of the WAL data in this message.203            </p></dd><dt><span class="term">Int64</span></dt><dd><p>204             The current end of WAL on the server.205            </p></dd><dt><span class="term">Int64</span></dt><dd><p>206             The server's system clock at the time of transmission, as207             microseconds since midnight on 2000-01-01.208            </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>209             A section of the WAL data stream.210            </p><p>211             A single WAL record is never split across two XLogData messages.212             When a WAL record crosses a WAL page boundary, and is therefore213             already split using continuation records, it can be split at the page214             boundary. In other words, the first main WAL record and its215             continuation records can be sent in different XLogData messages.216            </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>217             Identifies the message as a sender keepalive.218            </p></dd><dt><span class="term">Int64</span></dt><dd><p>219             The current end of WAL on the server.220            </p></dd><dt><span class="term">Int64</span></dt><dd><p>221             The server's system clock at the time of transmission, as222             microseconds since midnight on 2000-01-01.223            </p></dd><dt><span class="term">Byte1</span></dt><dd><p>224             1 means that the client should reply to this message as soon as225             possible, to avoid a timeout disconnect. 0 otherwise.226            </p></dd></dl></div></dd></dl></div><p>227       The receiving process can send replies back to the sender at any time,228       using one of the following message formats (also in the payload of a229       CopyData message):230      </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>231             Identifies the message as a receiver status update.232            </p></dd><dt><span class="term">Int64</span></dt><dd><p>233             The location of the last WAL byte + 1 received and written to disk234             in the standby.235            </p></dd><dt><span class="term">Int64</span></dt><dd><p>236             The location of the last WAL byte + 1 flushed to disk in237             the standby.238            </p></dd><dt><span class="term">Int64</span></dt><dd><p>239             The location of the last WAL byte + 1 applied in the standby.240            </p></dd><dt><span class="term">Int64</span></dt><dd><p>241             The client's system clock at the time of transmission, as242             microseconds since midnight on 2000-01-01.243            </p></dd><dt><span class="term">Byte1</span></dt><dd><p>244             If 1, the client requests the server to reply to this message245             immediately. This can be used to ping the server, to test if246             the connection is still healthy.247            </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>248             Identifies the message as a hot standby feedback message.249            </p></dd><dt><span class="term">Int64</span></dt><dd><p>250             The client's system clock at the time of transmission, as251             microseconds since midnight on 2000-01-01.252            </p></dd><dt><span class="term">Int32</span></dt><dd><p>253             The standby's current global xmin, excluding the catalog_xmin from any254             replication slots. If both this value and the following255             catalog_xmin are 0 this is treated as a notification that hot standby256             feedback will no longer be sent on this connection. Later non-zero257             messages may reinitiate the feedback mechanism.258            </p></dd><dt><span class="term">Int32</span></dt><dd><p>259             The epoch of the global xmin xid on the standby.260            </p></dd><dt><span class="term">Int32</span></dt><dd><p>261             The lowest catalog_xmin of any replication slots on the standby. Set to 0262             if no catalog_xmin exists on the standby or if hot standby feedback is being263             disabled.264            </p></dd><dt><span class="term">Int32</span></dt><dd><p>265             The epoch of the catalog_xmin xid on the standby.266            </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>267       Instructs server to start streaming WAL for logical replication,268       starting at either WAL location <em class="replaceable"><code>XXX/XXX</code></em> or the slot's269       <code class="literal">confirmed_flush_lsn</code> (see <a class="xref" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">Section 54.19</a>), whichever is greater. This270       behavior makes it easier for clients to avoid updating their local LSN271       status when there is no data to process. However, starting at a272       different LSN than requested might not catch certain kinds of client273       errors; so the client may wish to check that274       <code class="literal">confirmed_flush_lsn</code> matches its expectations before275       issuing <code class="literal">START_REPLICATION</code>.276      </p><p>277       The server can reply with an error, for example if the278       slot does not exist. On success, the server responds with a CopyBothResponse279       message, and then starts to stream WAL to the frontend.280      </p><p>281       The messages inside the CopyBothResponse messages are of the same format282       documented for <code class="literal">START_REPLICATION ... PHYSICAL</code>, including283       two CommandComplete messages.284      </p><p>285       The output plugin associated with the selected slot is used286       to process the output for streaming.287      </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>288          The name of the slot to stream changes from. This parameter is required,289          and must correspond to an existing logical replication slot created290          with <code class="literal">CREATE_REPLICATION_SLOT</code> in291          <code class="literal">LOGICAL</code> mode.292         </p></dd><dt><span class="term"><em class="replaceable"><code>XXX/XXX</code></em></span></dt><dd><p>293          The WAL location to begin streaming at.294         </p></dd><dt><span class="term"><em class="replaceable"><code>option_name</code></em></span></dt><dd><p>295          The name of an option passed to the slot's logical decoding output296          plugin.  See <a class="xref" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Section 55.5</a> for297          options that are accepted by the standard (<code class="literal">pgoutput</code>)298          plugin.299         </p></dd><dt><span class="term"><em class="replaceable"><code>option_value</code></em></span></dt><dd><p>300          Optional value, in the form of a string constant, associated with the301          specified option.302         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-DROP-REPLICATION-SLOT"><span class="term">303      <code class="literal">DROP_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [<span class="optional"> <code class="literal">WAIT</code> </span>]304      <a id="id-1.10.6.9.7.1.9.1.4" class="indexterm"></a>305     </span> <a href="#PROTOCOL-REPLICATION-DROP-REPLICATION-SLOT" class="id_link">#</a></dt><dd><p>306       Drops a replication slot, freeing any reserved server-side resources.307       If the slot is a logical slot that was created in a database other than308       the database the walsender is connected to, this command fails.309      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>310          The name of the slot to drop.311         </p></dd><dt><span class="term"><code class="literal">WAIT</code></span></dt><dd><p>312          This option causes the command to wait if the slot is active until313          it becomes inactive, instead of the default behavior of raising an314          error.315         </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-BASE-BACKUP"><span class="term"><code class="literal">BASE_BACKUP</code> [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ]316      <a id="id-1.10.6.9.7.1.10.1.3" class="indexterm"></a>317     </span> <a href="#PROTOCOL-REPLICATION-BASE-BACKUP" class="id_link">#</a></dt><dd><p>318       Instructs the server to start streaming a base backup.319       The system will automatically be put in backup mode before the backup320       is started, and taken out of it when the backup is complete. The321       following options are accepted:322 323       </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>324           Sets the label of the backup. If none is specified, a backup label325           of <code class="literal">base backup</code> will be used. The quoting rules326           for the label are the same as a standard SQL string with327           <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> turned on.328          </p></dd><dt><span class="term"><code class="literal">TARGET</code> <em class="replaceable"><code>'target'</code></em></span></dt><dd><p>329           Tells the server where to send the backup.  If the target is330           <code class="literal">client</code>, which is the default, the backup data is331           sent to the client. If it is <code class="literal">server</code>, the backup332           data is written to the server at the pathname specified by the333           <code class="literal">TARGET_DETAIL</code> option. If it is334           <code class="literal">blackhole</code>, the backup data is not sent335           anywhere; it is simply discarded.336          </p><p>337           The <code class="literal">server</code> target requires superuser privilege or338           being granted the <code class="literal">pg_write_server_files</code> role.339          </p></dd><dt><span class="term"><code class="literal">TARGET_DETAIL</code> <em class="replaceable"><code>'detail'</code></em></span></dt><dd><p>340           Provides additional information about the backup target.341          </p><p>342           Currently, this option can only be used when the backup target is343           <code class="literal">server</code>. It specifies the server directory344           to which the backup should be written.345          </p></dd><dt><span class="term"><code class="literal">PROGRESS [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>346           If set to true, request information required to generate a progress347           report. This will send back an approximate size in the header of each348           tablespace, which can be used to calculate how far along the stream349           is done. This is calculated by enumerating all the file sizes once350           before the transfer is even started, and might as such have a351           negative impact on the performance.  In particular, it might take352           longer before the first data353           is streamed. Since the database files can change during the backup,354           the size is only approximate and might both grow and shrink between355           the time of approximation and the sending of the actual files.356           The default is false.357          </p></dd><dt><span class="term"><code class="literal">CHECKPOINT { 'fast' | 'spread' }</code></span></dt><dd><p>358           Sets the type of checkpoint to be performed at the beginning of the359           base backup. The default is <code class="literal">spread</code>.360          </p></dd><dt><span class="term"><code class="literal">WAL [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>361           If set to true, include the necessary WAL segments in the backup.362           This will include all the files between start and stop backup in the363           <code class="filename">pg_wal</code> directory of the base directory tar364           file. The default is false.365          </p></dd><dt><span class="term"><code class="literal">WAIT [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>366           If set to true, the backup will wait until the last required WAL367           segment has been archived, or emit a warning if WAL archiving is368           not enabled. If false, the backup will neither wait nor warn,369           leaving the client responsible for ensuring the required log is370           available. The default is true.371          </p></dd><dt><span class="term"><code class="literal">COMPRESSION</code> <em class="replaceable"><code>'method'</code></em></span></dt><dd><p>372           Instructs the server to compress the backup using the specified373           method. Currently, the supported methods are <code class="literal">gzip</code>,374           <code class="literal">lz4</code>, and <code class="literal">zstd</code>.375          </p></dd><dt><span class="term"><code class="literal">COMPRESSION_DETAIL</code> <em class="replaceable"><code>detail</code></em></span></dt><dd><p>376           Specifies details for the chosen compression method. This should only377           be used in conjunction with the <code class="literal">COMPRESSION</code>378           option.  If the value is an integer, it specifies the compression379           level.  Otherwise, it should be a comma-separated list of items,380           each of the form <em class="replaceable"><code>keyword</code></em> or381           <em class="replaceable"><code>keyword=value</code></em>. Currently, the supported382           keywords are <code class="literal">level</code>, <code class="literal">long</code> and383           <code class="literal">workers</code>.384          </p><p>385           The <code class="literal">level</code> keyword sets the compression level.386           For <code class="literal">gzip</code> the compression level should be an387           integer between <code class="literal">1</code> and <code class="literal">9</code>388           (default <code class="literal">Z_DEFAULT_COMPRESSION</code> or389           <code class="literal">-1</code>), for <code class="literal">lz4</code> an integer390           between 1 and 12 (default <code class="literal">0</code> for fast compression391           mode), and for <code class="literal">zstd</code> an integer between392           <code class="literal">ZSTD_minCLevel()</code> (usually <code class="literal">-131072</code>)393           and <code class="literal">ZSTD_maxCLevel()</code> (usually <code class="literal">22</code>),394           (default <code class="literal">ZSTD_CLEVEL_DEFAULT</code> or395           <code class="literal">3</code>).396          </p><p>397           The <code class="literal">long</code> keyword enables long-distance matching398           mode, for improved compression ratio, at the expense of higher memory399           use.  Long-distance mode is supported only for400           <code class="literal">zstd</code>.401          </p><p>402           The <code class="literal">workers</code> keyword sets the number of threads403           that should be used for parallel compression. Parallel compression404           is supported only for <code class="literal">zstd</code>.405          </p></dd><dt><span class="term"><code class="literal">MAX_RATE</code> <em class="replaceable"><code>rate</code></em></span></dt><dd><p>406           Limit (throttle) the maximum amount of data transferred from server407           to client per unit of time.  The expected unit is kilobytes per second.408           If this option is specified, the value must either be equal to zero409           or it must fall within the range from 32 kB through 1 GB (inclusive).410           If zero is passed or the option is not specified, no restriction is411           imposed on the transfer.412          </p></dd><dt><span class="term"><code class="literal">TABLESPACE_MAP [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>413           If true, include information about symbolic links present in the414           directory <code class="filename">pg_tblspc</code> in a file named415           <code class="filename">tablespace_map</code>. The tablespace map file includes416           each symbolic link name as it exists in the directory417           <code class="filename">pg_tblspc/</code> and the full path of that symbolic link.418           The default is false.419          </p></dd><dt><span class="term"><code class="literal">VERIFY_CHECKSUMS [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>420           If true, checksums are verified during a base backup if they are421           enabled. If false, this is skipped. The default is true.422          </p></dd><dt><span class="term"><code class="literal">MANIFEST</code> <em class="replaceable"><code>manifest_option</code></em></span></dt><dd><p>423           When this option is specified with a value of <code class="literal">yes</code>424           or <code class="literal">force-encode</code>, a backup manifest is created425           and sent along with the backup.  The manifest is a list of every426           file present in the backup with the exception of any WAL files that427           may be included. It also stores the size, last modification time, and428           optionally a checksum for each file.429           A value of <code class="literal">force-encode</code> forces all filenames430           to be hex-encoded; otherwise, this type of encoding is performed only431           for files whose names are non-UTF8 octet sequences.432           <code class="literal">force-encode</code> is intended primarily for testing433           purposes, to be sure that clients which read the backup manifest434           can handle this case. For compatibility with previous releases,435           the default is <code class="literal">MANIFEST 'no'</code>.436          </p></dd><dt><span class="term"><code class="literal">MANIFEST_CHECKSUMS</code> <em class="replaceable"><code>checksum_algorithm</code></em></span></dt><dd><p>437           Specifies the checksum algorithm that should be applied to each file included438           in the backup manifest. Currently, the available439           algorithms are <code class="literal">NONE</code>, <code class="literal">CRC32C</code>,440           <code class="literal">SHA224</code>, <code class="literal">SHA256</code>,441           <code class="literal">SHA384</code>, and <code class="literal">SHA512</code>.442           The default is <code class="literal">CRC32C</code>.443          </p></dd></dl></div><p>444      </p><p>445       When the backup is started, the server will first send two446       ordinary result sets, followed by one or more CopyOutResponse447       results.448      </p><p>449       The first ordinary result set contains the starting position of the450       backup, in a single row with two columns. The first column contains451       the start position given in XLogRecPtr format, and the second column452       contains the corresponding timeline ID.453      </p><p>454       The second ordinary result set has one row for each tablespace.455       The fields in this row are:456 457       </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>458           The OID of the tablespace, or null if it's the base459           directory.460          </p></dd><dt><span class="term"><code class="literal">spclocation</code> (<code class="type">text</code>)</span></dt><dd><p>461           The full path of the tablespace directory, or null462           if it's the base directory.463          </p></dd><dt><span class="term"><code class="literal">size</code> (<code class="type">int8</code>)</span></dt><dd><p>464           The approximate size of the tablespace, in kilobytes (1024 bytes),465           if progress report has been requested; otherwise it's null.466          </p></dd></dl></div><p>467      </p><p>468       After the second regular result set, a CopyOutResponse will be sent.469       The payload of each CopyData message will contain a message in one of470       the following formats:471      </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>472            Identifies the message as indicating the start of a new archive.473            There will be one archive for the main data directory and one474            for each additional tablespace; each will use tar format475            (following the <span class="quote">“<span class="quote">ustar interchange format</span>”</span> specified476            in the POSIX 1003.1-2008 standard).477           </p></dd><dt><span class="term">String</span></dt><dd><p>478            The file name for this archive.479           </p></dd><dt><span class="term">String</span></dt><dd><p>480            For the main data directory, an empty string. For other481            tablespaces, the full path to the directory from which this482            archive was created.483           </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>484            Identifies the message as indicating the start of the backup485            manifest.486           </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>487            Identifies the message as containing archive or manifest data.488           </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>489            Data bytes.490           </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>491            Identifies the message as a progress report.492           </p></dd><dt><span class="term">Int64</span></dt><dd><p>493            The number of bytes from the current tablespace for which494            processing has been completed.495           </p></dd></dl></div></dd></dl></div><p>496       After the CopyOutResponse, or all such responses, have been sent, a497       final ordinary result set will be sent, containing the WAL end position498       of the backup, in the same format as the start position.499      </p><p>500       The tar archive for the data directory and each tablespace will contain501       all files in the directories, regardless of whether they are502       <span class="productname">PostgreSQL</span> files or other files added to the same503       directory. The only excluded files are:504 505       </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>506          <code class="filename">postmaster.pid</code>507         </p></li><li class="listitem" style="list-style-type: disc"><p>508          <code class="filename">postmaster.opts</code>509         </p></li><li class="listitem" style="list-style-type: disc"><p>510          <code class="filename">pg_internal.init</code> (found in multiple directories)511         </p></li><li class="listitem" style="list-style-type: disc"><p>512          Various temporary files and directories created during the operation513          of the PostgreSQL server, such as any file or directory beginning514          with <code class="filename">pgsql_tmp</code> and temporary relations.515         </p></li><li class="listitem" style="list-style-type: disc"><p>516          Unlogged relations, except for the init fork which is required to517          recreate the (empty) unlogged relation on recovery.518         </p></li><li class="listitem" style="list-style-type: disc"><p>519          <code class="filename">pg_wal</code>, including subdirectories. If the backup is run520          with WAL files included, a synthesized version of <code class="filename">pg_wal</code> will be521          included, but it will only contain the files necessary for the522          backup to work, not the rest of the contents.523         </p></li><li class="listitem" style="list-style-type: disc"><p>524          <code class="filename">pg_dynshmem</code>, <code class="filename">pg_notify</code>,525          <code class="filename">pg_replslot</code>, <code class="filename">pg_serial</code>,526          <code class="filename">pg_snapshots</code>, <code class="filename">pg_stat_tmp</code>, and527          <code class="filename">pg_subtrans</code> are copied as empty directories (even if528          they are symbolic links).529         </p></li><li class="listitem" style="list-style-type: disc"><p>530          Files other than regular files and directories, such as symbolic531          links (other than for the directories listed above) and special532          device and operating system files, are skipped.  (Symbolic links533          in <code class="filename">pg_tblspc</code> are maintained.)534         </p></li></ul></div><p>535       Owner, group, and file mode are set if the underlying file system on536       the server supports it.537      </p></dd></dl></div><p>538  </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="55.3. SASL Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.3. SASL Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.5. Logical Streaming Replication Protocol</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai