codekingpro/portable-devtools
115k
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>