1PG_BASEBACKUP(1)         PostgreSQL 11.6 Documentation        PG_BASEBACKUP(1)
2
3
4

NAME

6       pg_basebackup - take a base backup of a PostgreSQL cluster
7

SYNOPSIS

9       pg_basebackup [option...]
10

DESCRIPTION

12       pg_basebackup is used to take base backups of a running PostgreSQL
13       database cluster. These are taken without affecting other clients to
14       the database, and can be used both for point-in-time recovery (see
15       Section 25.3) and as the starting point for a log shipping or streaming
16       replication standby servers (see Section 26.2).
17
18       pg_basebackup makes a binary copy of the database cluster files, while
19       making sure the system is put in and out of backup mode automatically.
20       Backups are always taken of the entire database cluster; it is not
21       possible to back up individual databases or database objects. For
22       individual database backups, a tool such as pg_dump(1) must be used.
23
24       The backup is made over a regular PostgreSQL connection, and uses the
25       replication protocol. The connection must be made with a superuser or a
26       user having REPLICATION permissions (see Section 21.2), and pg_hba.conf
27       must explicitly permit the replication connection. The server must also
28       be configured with max_wal_senders set high enough to leave at least
29       one session available for the backup and one for WAL streaming (if
30       used).
31
32       There can be multiple pg_basebackups running at the same time, but it
33       is better from a performance point of view to take only one backup, and
34       copy the result.
35
36       pg_basebackup can make a base backup from not only the master but also
37       the standby. To take a backup from the standby, set up the standby so
38       that it can accept replication connections (that is, set
39       max_wal_senders and hot_standby, and configure host-based
40       authentication). You will also need to enable full_page_writes on the
41       master.
42
43       Note that there are some limitations in an online backup from the
44       standby:
45
46       ·   The backup history file is not created in the database cluster
47           backed up.
48
49       ·   If you are using -X none, there is no guarantee that all WAL files
50           required for the backup are archived at the end of backup.
51
52       ·   If the standby is promoted to the master during online backup, the
53           backup fails.
54
55       ·   All WAL records required for the backup must contain sufficient
56           full-page writes, which requires you to enable full_page_writes on
57           the master and not to use a tool like pg_compresslog as
58           archive_command to remove full-page writes from WAL files.
59
60

OPTIONS

62       The following command-line options control the location and format of
63       the output.
64
65       -D directory
66       --pgdata=directory
67           Directory to write the output to.  pg_basebackup will create the
68           directory and any parent directories if necessary. The directory
69           may already exist, but it is an error if the directory already
70           exists and is not empty.
71
72           When the backup is in tar mode, and the directory is specified as -
73           (dash), the tar file will be written to stdout.
74
75           This option is required.
76
77       -F format
78       --format=format
79           Selects the format for the output.  format can be one of the
80           following:
81
82           p
83           plain
84               Write the output as plain files, with the same layout as the
85               current data directory and tablespaces. When the cluster has no
86               additional tablespaces, the whole database will be placed in
87               the target directory. If the cluster contains additional
88               tablespaces, the main data directory will be placed in the
89               target directory, but all other tablespaces will be placed in
90               the same absolute path as they have on the server.
91
92               This is the default format.
93
94           t
95           tar
96               Write the output as tar files in the target directory. The main
97               data directory will be written to a file named base.tar, and
98               all other tablespaces will be named after the tablespace OID.
99
100               If the value - (dash) is specified as target directory, the tar
101               contents will be written to standard output, suitable for
102               piping to for example gzip. This is only possible if the
103               cluster has no additional tablespaces and WAL streaming is not
104               used.
105
106       -r rate
107       --max-rate=rate
108           The maximum transfer rate of data transferred from the server.
109           Values are in kilobytes per second. Use a suffix of M to indicate
110           megabytes per second. A suffix of k is also accepted, and has no
111           effect. Valid values are between 32 kilobytes per second and 1024
112           megabytes per second.
113
114           The purpose is to limit the impact of pg_basebackup on the running
115           server.
116
117           This option always affects transfer of the data directory. Transfer
118           of WAL files is only affected if the collection method is fetch.
119
120       -R
121       --write-recovery-conf
122           Write a minimal recovery.conf in the output directory (or into the
123           base archive file when using tar format) to ease setting up a
124           standby server. The recovery.conf file will record the connection
125           settings and, if specified, the replication slot that pg_basebackup
126           is using, so that the streaming replication will use the same
127           settings later on.
128
129       -T olddir=newdir
130       --tablespace-mapping=olddir=newdir
131           Relocate the tablespace in directory olddir to newdir during the
132           backup. To be effective, olddir must exactly match the path
133           specification of the tablespace as it is currently defined. (But it
134           is not an error if there is no tablespace in olddir contained in
135           the backup.) Both olddir and newdir must be absolute paths. If a
136           path happens to contain a = sign, escape it with a backslash. This
137           option can be specified multiple times for multiple tablespaces.
138           See examples below.
139
140           If a tablespace is relocated in this way, the symbolic links inside
141           the main data directory are updated to point to the new location.
142           So the new data directory is ready to be used for a new server
143           instance with all tablespaces in the updated locations.
144
145       --waldir=waldir
146           Specifies the location for the write-ahead log directory.  waldir
147           must be an absolute path. The write-ahead log directory can only be
148           specified when the backup is in plain mode.
149
150       -X method
151       --wal-method=method
152           Includes the required write-ahead log files (WAL files) in the
153           backup. This will include all write-ahead logs generated during the
154           backup. Unless the method none is specified, it is possible to
155           start a postmaster directly in the extracted directory without the
156           need to consult the log archive, thus making this a completely
157           standalone backup.
158
159           The following methods for collecting the write-ahead logs are
160           supported:
161
162           n
163           none
164               Don't include write-ahead log in the backup.
165
166           f
167           fetch
168               The write-ahead log files are collected at the end of the
169               backup. Therefore, it is necessary for the wal_keep_segments
170               parameter to be set high enough that the log is not removed
171               before the end of the backup. If the log has been rotated when
172               it's time to transfer it, the backup will fail and be unusable.
173
174               When tar format mode is used, the write-ahead log files will be
175               written to the base.tar file.
176
177           s
178           stream
179               Stream the write-ahead log while the backup is created. This
180               will open a second connection to the server and start streaming
181               the write-ahead log in parallel while running the backup.
182               Therefore, it will use up two connections configured by the
183               max_wal_senders parameter. As long as the client can keep up
184               with write-ahead log received, using this mode requires no
185               extra write-ahead logs to be saved on the master.
186
187               When tar format mode is used, the write-ahead log files will be
188               written to a separate file named pg_wal.tar (if the server is a
189               version earlier than 10, the file will be named pg_xlog.tar).
190
191               This value is the default.
192
193
194       -z
195       --gzip
196           Enables gzip compression of tar file output, with the default
197           compression level. Compression is only available when using the tar
198           format, and the suffix .gz will automatically be added to all tar
199           filenames.
200
201       -Z level
202       --compress=level
203           Enables gzip compression of tar file output, and specifies the
204           compression level (0 through 9, 0 being no compression and 9 being
205           best compression). Compression is only available when using the tar
206           format, and the suffix .gz will automatically be added to all tar
207           filenames.
208
209       The following command-line options control the generation of the backup
210       and the running of the program.
211
212       -c fast|spread
213       --checkpoint=fast|spread
214           Sets checkpoint mode to fast (immediate) or spread (default) (see
215           Section 25.3.3).
216
217       -C
218       --create-slot
219           This option causes creation of a replication slot named by the
220           --slot option before starting the backup. An error is raised if the
221           slot already exists.
222
223       -l label
224       --label=label
225           Sets the label for the backup. If none is specified, a default
226           value of “pg_basebackup base backup” will be used.
227
228       -n
229       --no-clean
230           By default, when pg_basebackup aborts with an error, it removes any
231           directories it might have created before discovering that it cannot
232           finish the job (for example, data directory and write-ahead log
233           directory). This option inhibits tidying-up and is thus useful for
234           debugging.
235
236           Note that tablespace directories are not cleaned up either way.
237
238       -N
239       --no-sync
240           By default, pg_basebackup will wait for all files to be written
241           safely to disk. This option causes pg_basebackup to return without
242           waiting, which is faster, but means that a subsequent operating
243           system crash can leave the base backup corrupt. Generally, this
244           option is useful for testing but should not be used when creating a
245           production installation.
246
247       -P
248       --progress
249           Enables progress reporting. Turning this on will deliver an
250           approximate progress report during the backup. Since the database
251           may change during the backup, this is only an approximation and may
252           not end at exactly 100%. In particular, when WAL log is included in
253           the backup, the total amount of data cannot be estimated in
254           advance, and in this case the estimated target size will increase
255           once it passes the total estimate without WAL.
256
257           When this is enabled, the backup will start by enumerating the size
258           of the entire database, and then go back and send the actual
259           contents. This may make the backup take slightly longer, and in
260           particular it will take longer before the first data is sent.
261
262       -S slotname
263       --slot=slotname
264           This option can only be used together with -X stream. It causes the
265           WAL streaming to use the specified replication slot. If the base
266           backup is intended to be used as a streaming replication standby
267           using replication slots, it should then use the same replication
268           slot name in recovery.conf. That way, it is ensured that the server
269           does not remove any necessary WAL data in the time between the end
270           of the base backup and the start of streaming replication.
271
272           The specified replication slot has to exist unless the option -C is
273           also used.
274
275           If this option is not specified and the server supports temporary
276           replication slots (version 10 and later), then a temporary
277           replication slot is automatically used for WAL streaming.
278
279       -v
280       --verbose
281           Enables verbose mode. Will output some extra steps during startup
282           and shutdown, as well as show the exact file name that is currently
283           being processed if progress reporting is also enabled.
284
285       --no-slot
286           This option prevents the creation of a temporary replication slot
287           during the backup even if it's supported by the server.
288
289           Temporary replication slots are created by default if no slot name
290           is given with the option -S when using log streaming.
291
292           The main purpose of this option is to allow taking a base backup
293           when the server is out of free replication slots. Using replication
294           slots is almost always preferred, because it prevents needed WAL
295           from being removed by the server during the backup.
296
297       --no-verify-checksums
298           Disables verification of checksums, if they are enabled on the
299           server the base backup is taken from.
300
301           By default, checksums are verified and checksum failures will
302           result in a non-zero exit status. However, the base backup will not
303           be removed in such a case, as if the --no-clean option had been
304           used.
305
306       The following command-line options control the database connection
307       parameters.
308
309       -d connstr
310       --dbname=connstr
311           Specifies parameters used to connect to the server, as a connection
312           string. See Section 34.1.1 for more information.
313
314           The option is called --dbname for consistency with other client
315           applications, but because pg_basebackup doesn't connect to any
316           particular database in the cluster, database name in the connection
317           string will be ignored.
318
319       -h host
320       --host=host
321           Specifies the host name of the machine on which the server is
322           running. If the value begins with a slash, it is used as the
323           directory for the Unix domain socket. The default is taken from the
324           PGHOST environment variable, if set, else a Unix domain socket
325           connection is attempted.
326
327       -p port
328       --port=port
329           Specifies the TCP port or local Unix domain socket file extension
330           on which the server is listening for connections. Defaults to the
331           PGPORT environment variable, if set, or a compiled-in default.
332
333       -s interval
334       --status-interval=interval
335           Specifies the number of seconds between status packets sent back to
336           the server. This allows for easier monitoring of the progress from
337           server. A value of zero disables the periodic status updates
338           completely, although an update will still be sent when requested by
339           the server, to avoid timeout disconnect. The default value is 10
340           seconds.
341
342       -U username
343       --username=username
344           User name to connect as.
345
346       -w
347       --no-password
348           Never issue a password prompt. If the server requires password
349           authentication and a password is not available by other means such
350           as a .pgpass file, the connection attempt will fail. This option
351           can be useful in batch jobs and scripts where no user is present to
352           enter a password.
353
354       -W
355       --password
356           Force pg_basebackup to prompt for a password before connecting to a
357           database.
358
359           This option is never essential, since pg_basebackup will
360           automatically prompt for a password if the server demands password
361           authentication. However, pg_basebackup will waste a connection
362           attempt finding out that the server wants a password. In some cases
363           it is worth typing -W to avoid the extra connection attempt.
364
365       Other options are also available:
366
367       -V
368       --version
369           Print the pg_basebackup version and exit.
370
371       -?
372       --help
373           Show help about pg_basebackup command line arguments, and exit.
374

ENVIRONMENT

376       This utility, like most other PostgreSQL utilities, uses the
377       environment variables supported by libpq (see Section 34.14).
378

NOTES

380       At the beginning of the backup, a checkpoint needs to be written on the
381       server the backup is taken from. Especially if the option
382       --checkpoint=fast is not used, this can take some time during which
383       pg_basebackup will be appear to be idle.
384
385       The backup will include all files in the data directory and
386       tablespaces, including the configuration files and any additional files
387       placed in the directory by third parties, except certain temporary
388       files managed by PostgreSQL. But only regular files and directories are
389       copied, except that symbolic links used for tablespaces are preserved.
390       Symbolic links pointing to certain directories known to PostgreSQL are
391       copied as empty directories. Other symbolic links and special device
392       files are skipped. See Section 53.4 for the precise details.
393
394       Tablespaces will in plain format by default be backed up to the same
395       path they have on the server, unless the option --tablespace-mapping is
396       used. Without this option, running a plain format base backup on the
397       same host as the server will not work if tablespaces are in use,
398       because the backup would have to be written to the same directory
399       locations as the original tablespaces.
400
401       When tar format mode is used, it is the user's responsibility to unpack
402       each tar file before starting the PostgreSQL server. If there are
403       additional tablespaces, the tar files for them need to be unpacked in
404       the correct locations. In this case the symbolic links for those
405       tablespaces will be created by the server according to the contents of
406       the tablespace_map file that is included in the base.tar file.
407
408       pg_basebackup works with servers of the same or an older major version,
409       down to 9.1. However, WAL streaming mode (-X stream) only works with
410       server version 9.3 and later, and tar format mode (--format=tar) of the
411       current version only works with server version 9.5 or later.
412
413       pg_basebackup will preserve group permissions in both the plain and tar
414       formats if group permissions are enabled on the source cluster.
415

EXAMPLES

417       To create a base backup of the server at mydbserver and store it in the
418       local directory /usr/local/pgsql/data:
419
420           $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
421
422       To create a backup of the local server with one compressed tar file for
423       each tablespace, and store it in the directory backup, showing a
424       progress report while running:
425
426           $ pg_basebackup -D backup -Ft -z -P
427
428       To create a backup of a single-tablespace local database and compress
429       this with bzip2:
430
431           $ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2
432
433       (This command will fail if there are multiple tablespaces in the
434       database.)
435
436       To create a backup of a local database where the tablespace in /opt/ts
437       is relocated to ./backup/ts:
438
439           $ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts
440
441

SEE ALSO

443       pg_dump(1)
444
445
446
447PostgreSQL 11.6                      2019                     PG_BASEBACKUP(1)
Impressum