1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
|
<?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>52.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 V1.79.1" /><link rel="prev" href="sasl-authentication.html" title="52.3. SASL Authentication" /><link rel="next" href="protocol-logical-replication.html" title="52.5. Logical Streaming Replication Protocol" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.4. Streaming Replication Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sasl-authentication.html" title="52.3. SASL Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 52. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="52.5. Logical Streaming Replication Protocol">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="PROTOCOL-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.4. Streaming Replication Protocol</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">pg_receivewal</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><span class="term"><code class="literal">IDENTIFY_SYSTEM</code>
<a id="id-1.10.5.9.7.1.1.1.2" class="indexterm"></a>
</span></dt><dd><p>
Requests the server to identify itself. Server replies with a result
set of a single row, containing four fields:
</p><p>
</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">int4</code>)
</span></dt><dd><p>
Current timeline ID. Also useful to check that the standby is
consistent with the master.
</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><p>
</p></dd><dt><span class="term"><code class="literal">SHOW</code> <em class="replaceable"><code>name</code></em>
<a id="id-1.10.5.9.7.1.2.1.3" class="indexterm"></a>
</span></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><span class="term"><code class="literal">TIMELINE_HISTORY</code> <em class="replaceable"><code>tli</code></em>
<a id="id-1.10.5.9.7.1.3.1.3" class="indexterm"></a>
</span></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> and <code class="type">bytea</code>,
they effectively return raw bytes, with no escaping or encoding
conversion:
</p><p>
</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">bytea</code>)
</span></dt><dd><p>
Contents of the timeline history file.
</p></dd></dl></div><p>
</p></dd><dt id="PROTOCOL-REPLICATION-CREATE-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">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> ] }
<a id="id-1.10.5.9.7.1.4.1.11" class="indexterm"></a>
</span></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="48.6. Logical Decoding Output Plugins">Section 48.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><dt><span class="term"><code class="literal">RESERVE_WAL</code></span></dt><dd><p>
Specify that 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.
</p></dd><dt><span class="term"><code class="literal">EXPORT_SNAPSHOT</code><br /></span><span class="term"><code class="literal">NOEXPORT_SNAPSHOT</code><br /></span><span class="term"><code class="literal">USE_SNAPSHOT</code></span></dt><dd><p>
Decides what to do with the snapshot created during logical slot
initialization. <code class="literal">EXPORT_SNAPSHOT</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_SNAPSHOT</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">NOEXPORT_SNAPSHOT</code> will
just use the snapshot for logical decoding as normal but won't do
anything else with it.
</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><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.5.9.7.1.5.1.8" class="indexterm"></a>
</span></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, 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 responds
immediately with CommandComplete without entering COPY mode.
</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. (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><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
XLogData (B)
</span></dt><dd><p>
</p><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><p>
</p></dd><dt><span class="term">
Primary keepalive message (B)
</span></dt><dd><p>
</p><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><p>
</p></dd></dl></div><p>
</p><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><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
Standby status update (F)
</span></dt><dd><p>
</p><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><p>
</p></dd></dl></div><p>
</p><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
Hot Standby feedback message (F)
</span></dt><dd><p>
</p><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 xmin, excluding the catalog_xmin from any
replication slots. If both this value and the following
catalog_xmin 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 xmin xid on the standby.
</p></dd><dt><span class="term">
Int32
</span></dt><dd><p>
The lowest catalog_xmin of any replication slots on the standby. Set to 0
if no catalog_xmin 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 catalog_xmin xid on the standby.
</p></dd></dl></div><p>
</p></dd></dl></div><p>
</p></dd><dt><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></dt><dd><p>
Instructs server to start streaming WAL for logical replication, starting
at WAL location <em class="replaceable"><code>XXX/XXX</code></em>. The server can
reply with an error, for example if the requested section of WAL has already
been recycled. On success, 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 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><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.5.9.7.1.7.1.4" class="indexterm"></a>
</span></dt><dd><p>
Drops a replication slot, freeing any reserved server-side resources.
If the slot is a logical slot that was created in a database other than
the database the walsender is connected to, this command fails.
</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-BASE-BACKUP"><span class="term"><code class="literal">BASE_BACKUP</code> [ <code class="literal">LABEL</code> <em class="replaceable"><code>'label'</code></em> ] [ <code class="literal">PROGRESS</code> ] [ <code class="literal">FAST</code> ] [ <code class="literal">WAL</code> ] [ <code class="literal">NOWAIT</code> ] [ <code class="literal">MAX_RATE</code> <em class="replaceable"><code>rate</code></em> ] [ <code class="literal">TABLESPACE_MAP</code> ] [ <code class="literal">NOVERIFY_CHECKSUMS</code> ] [ <code class="literal">MANIFEST</code> <em class="replaceable"><code>manifest_option</code></em> ] [ <code class="literal">MANIFEST_CHECKSUMS</code> <em class="replaceable"><code>checksum_algorithm</code></em> ]
<a id="id-1.10.5.9.7.1.8.1.16" class="indexterm"></a>
</span></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">PROGRESS</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="literal">FAST</code></span></dt><dd><p>
Request a fast checkpoint.
</p></dd><dt><span class="term"><code class="literal">WAL</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="literal">NOWAIT</code></span></dt><dd><p>
By default, the backup will wait until the last required WAL
segment has been archived, or emit a warning if log archiving is
not enabled. Specifying <code class="literal">NOWAIT</code> disables both
the waiting and the warning, leaving the client responsible for
ensuring the required log is available.
</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</code></span></dt><dd><p>
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.
</p></dd><dt><span class="term"><code class="literal">NOVERIFY_CHECKSUMS</code></span></dt><dd><p>
By default, checksums are verified during a base backup if they are
enabled. Specifying <code class="literal">NOVERIFY_CHECKSUMS</code> disables
this verification.
</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></dl></div><p>
</p><p>
When the backup is started, the server will first send two
ordinary result sets, followed by one or more CopyResponse
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, one or more CopyResponse results
will be sent, one for the main data directory and one for each additional tablespace other
than <code class="literal">pg_default</code> and <code class="literal">pg_global</code>. The data in
the CopyResponse results will be a tar format (following the
<span class="quote">“<span class="quote">ustar interchange format</span>”</span> specified in the POSIX 1003.1-2008
standard) dump of the tablespace contents, except that the two trailing
blocks of zeroes specified in the standard are omitted.
After the tar data is complete, and if a backup manifest was requested,
another CopyResponse result is sent, containing the manifest data for the
current base backup. In any case, 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 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></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sasl-authentication.html" title="52.3. SASL Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="52.5. Logical Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.3. SASL Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.5. Logical Streaming Replication Protocol</td></tr></table></div></body></html>
|
