summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/man1/pg_receivewal.1
blob: 1a74376f187cef32f47fe49c8a46ceaf3b7a0c6f (plain)
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
'\" t
.\"     Title: pg_receivewal
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024
.\"    Manual: PostgreSQL 15.7 Documentation
.\"    Source: PostgreSQL 15.7
.\"  Language: English
.\"
.TH "PG_RECEIVEWAL" "1" "2024" "PostgreSQL 15.7" "PostgreSQL 15.7 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pg_receivewal \- stream write\-ahead logs from a PostgreSQL server
.SH "SYNOPSIS"
.HP \w'\fBpg_receivewal\fR\ 'u
\fBpg_receivewal\fR [\fIoption\fR...]
.SH "DESCRIPTION"
.PP
pg_receivewal
is used to stream the write\-ahead log from a running
PostgreSQL
cluster\&. The write\-ahead log is streamed using the streaming replication protocol, and is written to a local directory of files\&. This directory can be used as the archive location for doing a restore using point\-in\-time recovery (see
Section\ \&26.3)\&.
.PP
pg_receivewal
streams the write\-ahead log in real time as it\*(Aqs being generated on the server, and does not wait for segments to complete like
archive_command
and
archive_library
do\&. For this reason, it is not necessary to set
archive_timeout
when using
pg_receivewal\&.
.PP
Unlike the WAL receiver of a PostgreSQL standby server,
pg_receivewal
by default flushes WAL data only when a WAL file is closed\&. The option
\fB\-\-synchronous\fR
must be specified to flush WAL data in real time\&. Since
pg_receivewal
does not apply WAL, you should not allow it to become a synchronous standby when
synchronous_commit
equals
remote_apply\&. If it does, it will appear to be a standby that never catches up, and will cause transaction commits to block\&. To avoid this, you should either configure an appropriate value for
synchronous_standby_names, or specify
\fIapplication_name\fR
for
pg_receivewal
that does not match it, or change the value of
\fIsynchronous_commit\fR
to something other than
remote_apply\&.
.PP
The write\-ahead log is streamed over a regular
PostgreSQL
connection and uses the replication protocol\&. The connection must be made with a user having
REPLICATION
permissions (see
Section\ \&22.2) or a superuser, and
pg_hba\&.conf
must permit the replication connection\&. The server must also be configured with
max_wal_senders
set high enough to leave at least one session available for the stream\&.
.PP
The starting point of the write\-ahead log streaming is calculated when
pg_receivewal
starts:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
First, scan the directory where the WAL segment files are written and find the newest completed segment file, using as the starting point the beginning of the next WAL segment file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
If a starting point cannot be calculated with the previous method, and if a replication slot is used, an extra
\fBREAD_REPLICATION_SLOT\fR
command is issued to retrieve the slot\*(Aqs
restart_lsn
to use as the starting point\&. This option is only available when streaming write\-ahead logs from
PostgreSQL
15 and up\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
If a starting point cannot be calculated with the previous method, the latest WAL flush location is used as reported by the server from an
IDENTIFY_SYSTEM
command\&.
.RE
.PP
If the connection is lost, or if it cannot be initially established, with a non\-fatal error,
pg_receivewal
will retry the connection indefinitely, and reestablish streaming as soon as possible\&. To avoid this behavior, use the
\-n
parameter\&.
.PP
In the absence of fatal errors,
pg_receivewal
will run until terminated by the
SIGINT
signal (Control+C)\&.
.SH "OPTIONS"
.PP
\fB\-D \fR\fB\fIdirectory\fR\fR
.br
\fB\-\-directory=\fR\fB\fIdirectory\fR\fR
.RS 4
Directory to write the output to\&.
.sp
This parameter is required\&.
.RE
.PP
\fB\-E \fR\fB\fIlsn\fR\fR
.br
\fB\-\-endpos=\fR\fB\fIlsn\fR\fR
.RS 4
Automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN\&.
.sp
If there is a record with LSN exactly equal to
\fIlsn\fR, the record will be processed\&.
.RE
.PP
\fB\-\-if\-not\-exists\fR
.RS 4
Do not error out when
\fB\-\-create\-slot\fR
is specified and a slot with the specified name already exists\&.
.RE
.PP
\fB\-n\fR
.br
\fB\-\-no\-loop\fR
.RS 4
Don\*(Aqt loop on connection errors\&. Instead, exit right away with an error\&.
.RE
.PP
\fB\-\-no\-sync\fR
.RS 4
This option causes
\fBpg_receivewal\fR
to not force WAL data to be flushed to disk\&. This is faster, but means that a subsequent operating system crash can leave the WAL segments corrupt\&. Generally, this option is useful for testing but should not be used when doing WAL archiving on a production deployment\&.
.sp
This option is incompatible with
\-\-synchronous\&.
.RE
.PP
\fB\-s \fR\fB\fIinterval\fR\fR
.br
\fB\-\-status\-interval=\fR\fB\fIinterval\fR\fR
.RS 4
Specifies the number of seconds between status packets sent back to the server\&. This allows for easier monitoring of the progress from server\&. A value of zero disables the periodic status updates completely, although an update will still be sent when requested by the server, to avoid timeout disconnect\&. The default value is 10 seconds\&.
.RE
.PP
\fB\-S \fR\fB\fIslotname\fR\fR
.br
\fB\-\-slot=\fR\fB\fIslotname\fR\fR
.RS 4
Require
pg_receivewal
to use an existing replication slot (see
Section\ \&27.2.6)\&. When this option is used,
pg_receivewal
will report a flush position to the server, indicating when each segment has been synchronized to disk so that the server can remove that segment if it is not otherwise needed\&.
.sp
When the replication client of
pg_receivewal
is configured on the server as a synchronous standby, then using a replication slot will report the flush position to the server, but only when a WAL file is closed\&. Therefore, that configuration will cause transactions on the primary to wait for a long time and effectively not work satisfactorily\&. The option
\-\-synchronous
(see below) must be specified in addition to make this work correctly\&.
.RE
.PP
\fB\-\-synchronous\fR
.RS 4
Flush the WAL data to disk immediately after it has been received\&. Also send a status packet back to the server immediately after flushing, regardless of
\-\-status\-interval\&.
.sp
This option should be specified if the replication client of
pg_receivewal
is configured on the server as a synchronous standby, to ensure that timely feedback is sent to the server\&.
.RE
.PP
\fB\-v\fR
.br
\fB\-\-verbose\fR
.RS 4
Enables verbose mode\&.
.RE
.PP
\fB\-Z \fR\fB\fIlevel\fR\fR
.br
\fB\-Z \fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR
.br
\fB\-\-compress=\fR\fB\fIlevel\fR\fR
.br
\fB\-\-compress=\fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR
.RS 4
Enables compression of write\-ahead logs\&.
.sp
The compression method can be set to
gzip,
lz4
(if
PostgreSQL
was compiled with
\fB\-\-with\-lz4\fR) or
none
for no compression\&. A compression detail string can optionally be specified\&. If the detail string is an integer, it specifies the compression level\&. Otherwise, it should be a comma\-separated list of items, each of the form
keyword
or
keyword=value\&. Currently, the only supported keyword is
level\&.
.sp
If no compression level is specified, the default compression level will be used\&. If only a level is specified without mentioning an algorithm,
gzip
compression will be used if the level is greater than 0, and no compression will be used if the level is 0\&.
.sp
The suffix
\&.gz
will automatically be added to all filenames when using
gzip, and the suffix
\&.lz4
is added when using
lz4\&.
.RE
.PP
The following command\-line options control the database connection parameters\&.
.PP
\fB\-d \fR\fB\fIconnstr\fR\fR
.br
\fB\-\-dbname=\fR\fB\fIconnstr\fR\fR
.RS 4
Specifies parameters used to connect to the server, as a
connection string; these will override any conflicting command line options\&.
.sp
The option is called
\-\-dbname
for consistency with other client applications, but because
pg_receivewal
doesn\*(Aqt connect to any particular database in the cluster, database name in the connection string will be ignored\&.
.RE
.PP
\fB\-h \fR\fB\fIhost\fR\fR
.br
\fB\-\-host=\fR\fB\fIhost\fR\fR
.RS 4
Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the
\fBPGHOST\fR
environment variable, if set, else a Unix domain socket connection is attempted\&.
.RE
.PP
\fB\-p \fR\fB\fIport\fR\fR
.br
\fB\-\-port=\fR\fB\fIport\fR\fR
.RS 4
Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the
\fBPGPORT\fR
environment variable, if set, or a compiled\-in default\&.
.RE
.PP
\fB\-U \fR\fB\fIusername\fR\fR
.br
\fB\-\-username=\fR\fB\fIusername\fR\fR
.RS 4
User name to connect as\&.
.RE
.PP
\fB\-w\fR
.br
\fB\-\-no\-password\fR
.RS 4
Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
\&.pgpass
file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&.
.RE
.PP
\fB\-W\fR
.br
\fB\-\-password\fR
.RS 4
Force
pg_receivewal
to prompt for a password before connecting to a database\&.
.sp
This option is never essential, since
pg_receivewal
will automatically prompt for a password if the server demands password authentication\&. However,
pg_receivewal
will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
\fB\-W\fR
to avoid the extra connection attempt\&.
.RE
.PP
pg_receivewal
can perform one of the two following actions in order to control physical replication slots:
.PP
\fB\-\-create\-slot\fR
.RS 4
Create a new physical replication slot with the name specified in
\fB\-\-slot\fR, then exit\&.
.RE
.PP
\fB\-\-drop\-slot\fR
.RS 4
Drop the replication slot with the name specified in
\fB\-\-slot\fR, then exit\&.
.RE
.PP
Other options are also available:
.PP
\fB\-V\fR
.br
\fB\-\-version\fR
.RS 4
Print the
pg_receivewal
version and exit\&.
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
Show help about
pg_receivewal
command line arguments, and exit\&.
.RE
.SH "EXIT STATUS"
.PP
pg_receivewal
will exit with status 0 when terminated by the
SIGINT
signal\&. (That is the normal way to end it\&. Hence it is not an error\&.) For fatal errors or other signals, the exit status will be nonzero\&.
.SH "ENVIRONMENT"
.PP
This utility, like most other
PostgreSQL
utilities, uses the environment variables supported by
libpq
(see
Section\ \&34.15)\&.
.PP
The environment variable
\fBPG_COLOR\fR
specifies whether to use color in diagnostic messages\&. Possible values are
always,
auto
and
never\&.
.SH "NOTES"
.PP
When using
pg_receivewal
instead of
archive_command
or
archive_library
as the main WAL backup method, it is strongly recommended to use replication slots\&. Otherwise, the server is free to recycle or remove write\-ahead log files before they are backed up, because it does not have any information, either from
archive_command
or
archive_library
or the replication slots, about how far the WAL stream has been archived\&. Note, however, that a replication slot will fill up the server\*(Aqs disk space if the receiver does not keep up with fetching the WAL data\&.
.PP
pg_receivewal
will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster\&.
.SH "EXAMPLES"
.PP
To stream the write\-ahead log from the server at
mydbserver
and store it in the local directory
/usr/local/pgsql/archive:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_receivewal \-h mydbserver \-D /usr/local/pgsql/archive\fR
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
\fBpg_basebackup\fR(1)