1PG_BASEBACKUP(1) PostgreSQL 16.1 Documentation PG_BASEBACKUP(1)
2
6 pg_basebackup - take a base backup of a PostgreSQL cluster
7
9 pg_basebackup [option...]
10
12 pg_basebackup is used to take a base backup of a running PostgreSQL
13 database cluster. The backup is taken without affecting other clients
14 of the database, and can be used both for point-in-time recovery (see
15 Section 26.3) and as the starting point for a log-shipping or
16 streaming-replication standby server (see Section 27.2).
17 pg_basebackup makes an exact copy of the database cluster's files,
19 while making sure the server is put into and out of backup mode
20 automatically. Backups are always taken of the entire database cluster;
21 it is not possible to back up individual databases or database objects.
22 For selective backups, another tool such as pg_dump(1) must be used.
23 The backup is made over a regular PostgreSQL connection that uses the
25 replication protocol. The connection must be made with a user ID that
26 has REPLICATION permissions (see Section 22.2) or is a superuser, and
27 pg_hba.conf must permit the replication connection. The server must
28 also be configured with max_wal_senders set high enough to provide at
29 least one walsender for the backup plus one for WAL streaming (if
30 used).
31 There can be multiple pg_basebackups running at the same time, but it
33 is usually better from a performance point of view to take only one
34 backup, and copy the result.
35 pg_basebackup can make a base backup from not only a primary server but
37 also a standby. To take a backup from a 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 its pg_hba.conf
40 appropriately). You will also need to enable full_page_writes on the
41 primary.
42 Note that there are some limitations in taking a backup from a standby:
44 • The backup history file is not created in the database cluster
46 backed up.
47 • pg_basebackup cannot force the standby to switch to a new WAL file
49 at the end of backup. When you are using -X none, if write activity
50 on the primary is low, pg_basebackup may need to wait a long time
51 for the last WAL file required for the backup to be switched and
52 archived. In this case, it may be useful to run pg_switch_wal on
53 the primary in order to trigger an immediate WAL file switch.
54 • If the standby is promoted to be primary during backup, the backup
56 fails.
57 • All WAL records required for the backup must contain sufficient
59 full-page writes, which requires you to enable full_page_writes on
60 the primary.
61 Whenever pg_basebackup is taking a base backup, the server's
63 pg_stat_progress_basebackup view will report the progress of the
64 backup. See Section 28.4.6 for details.
65
67 The following command-line options control the location and format of
68 the output:
69 -D directory
71 --pgdata=directory
72 Sets the target directory to write the output to. pg_basebackup
73 will create this directory (and any missing parent directories) if
74 it does not exist. If it already exists, it must be empty.
75 When the backup is in tar format, the target directory may be
77 specified as - (dash), causing the tar file to be written to
78 stdout.
79 This option is required.
81 -F format
83 --format=format
84 Selects the format for the output. format can be one of the
85 following:
86 p
88 plain
89 Write the output as plain files, with the same layout as the
90 source server's data directory and tablespaces. When the
91 cluster has no additional tablespaces, the whole database will
92 be placed in the target directory. If the cluster contains
93 additional tablespaces, the main data directory will be placed
94 in the target directory, but all other tablespaces will be
95 placed in the same absolute path as they have on the source
96 server. (See --tablespace-mapping to change that.)
97 This is the default format.
99 t
101 tar
102 Write the output as tar files in the target directory. The main
103 data directory's contents will be written to a file named
104 base.tar, and each other tablespace will be written to a
105 separate tar file named after that tablespace's OID.
106 If the target directory is specified as - (dash), the tar
108 contents will be written to standard output, suitable for
109 piping to (for example) gzip. This is only allowed if the
110 cluster has no additional tablespaces and WAL streaming is not
111 used.
112 -R
114 --write-recovery-conf
115 Creates a standby.signal
116 file and appends connection settings to the postgresql.auto.conf
118 file in the target directory (or within the base archive file when
119 using tar format). This eases setting up a standby server using the
120 results of the backup.
121 The postgresql.auto.conf file will record the connection settings
123 and, if specified, the replication slot that pg_basebackup is
124 using, so that streaming replication will use the same settings
125 later on.
126 -t target
128 --target=target
129 Instructs the server where to place the base backup. The default
130 target is client, which specifies that the backup should be sent to
131 the machine where pg_basebackup is running. If the target is
132 instead set to server:/some/path, the backup will be stored on the
133 machine where the server is running in the /some/path directory.
134 Storing a backup on the server requires superuser privileges or
135 having privileges of the pg_write_server_files role. If the target
136 is set to blackhole, the contents are discarded and not stored
137 anywhere. This should only be used for testing purposes, as you
138 will not end up with an actual backup.
139 Since WAL streaming is implemented by pg_basebackup rather than by
141 the server, this option cannot be used together with -Xstream.
142 Since that is the default, when this option is specified, you must
143 also specify either -Xfetch or -Xnone.
144 -T olddir=newdir
146 --tablespace-mapping=olddir=newdir
147 Relocates the tablespace in directory olddir to newdir during the
148 backup. To be effective, olddir must exactly match the path
149 specification of the tablespace as it is defined on the source
150 server. (But it is not an error if there is no tablespace in olddir
151 on the source server.) Meanwhile newdir is a directory in the
152 receiving host's filesystem. As with the main target directory,
153 newdir need not exist already, but if it does exist it must be
154 empty. Both olddir and newdir must be absolute paths. If either
155 path needs to contain an equal sign (=), precede that with a
156 backslash. This option can be specified multiple times for multiple
157 tablespaces.
158 If a tablespace is relocated in this way, the symbolic links inside
160 the main data directory are updated to point to the new location.
161 So the new data directory is ready to be used for a new server
162 instance with all tablespaces in the updated locations.
163 Currently, this option only works with plain output format; it is
165 ignored if tar format is selected.
166 --waldir=waldir
168 Sets the directory to write WAL (write-ahead log) files to. By
169 default WAL files will be placed in the pg_wal subdirectory of the
170 target directory, but this option can be used to place them
171 elsewhere. waldir must be an absolute path. As with the main
172 target directory, waldir need not exist already, but if it does
173 exist it must be empty. This option can only be specified when the
174 backup is in plain format.
175 -X method
177 --wal-method=method
178 Includes the required WAL (write-ahead log) files in the backup.
179 This will include all write-ahead logs generated during the backup.
180 Unless the method none is specified, it is possible to start a
181 postmaster in the target directory without the need to consult the
182 WAL archive, thus making the output a completely standalone backup.
183 The following methods for collecting the write-ahead logs are
185 supported:
186 n
188 none
189 Don't include write-ahead logs in the backup.
190 f
192 fetch
193 The write-ahead log files are collected at the end of the
194 backup. Therefore, it is necessary for the source server's
195 wal_keep_size parameter to be set high enough that the required
196 log data is not removed before the end of the backup. If the
197 required log data has been recycled before it's time to
198 transfer it, the backup will fail and be unusable.
199 When tar format is used, the write-ahead log files will be
201 included in the base.tar file.
202 s
204 stream
205 Stream write-ahead log data while the backup is being taken.
206 This method will open a second connection to the server and
207 start streaming the write-ahead log in parallel while running
208 the backup. Therefore, it will require two replication
209 connections not just one. As long as the client can keep up
210 with the write-ahead log data, using this method requires no
211 extra write-ahead logs to be saved on the source server.
212 When tar format is used, the write-ahead log files will be
214 written to a separate file named pg_wal.tar (if the server is a
215 version earlier than 10, the file will be named pg_xlog.tar).
216 This value is the default.
218 -z
220 --gzip
221 Enables gzip compression of tar file output, with the default
222 compression level. Compression is only available when using the tar
223 format, and the suffix .gz will automatically be added to all tar
224 filenames.
225 -Z level
227 -Z [{client|server}-]method[:detail]
228 --compress=level
229 --compress=[{client|server}-]method[:detail]
230 Requests compression of the backup. If client or server is
231 included, it specifies where the compression is to be performed.
232 Compressing on the server will reduce transfer bandwidth but will
233 increase server CPU consumption. The default is client except when
234 --target is used. In that case, the backup is not being sent to the
235 client, so only server compression is sensible. When -Xstream,
236 which is the default, is used, server-side compression will not be
237 applied to the WAL. To compress the WAL, use client-side
238 compression, or specify -Xfetch.
239 The compression method can be set to gzip, lz4, zstd, none for no
241 compression or an integer (no compression if 0, gzip if greater
242 than 0). A compression detail string can optionally be specified.
243 If the detail string is an integer, it specifies the compression
244 level. Otherwise, it should be a comma-separated list of items,
245 each of the form keyword or keyword=value. Currently, the supported
246 keywords are level, long, and workers. The detail string cannot be
247 used when the compression method is specified as a plain integer.
248 If no compression level is specified, the default compression level
250 will be used. If only a level is specified without mentioning an
251 algorithm, gzip compression will be used if the level is greater
252 than 0, and no compression will be used if the level is 0.
253 When the tar format is used with gzip, lz4, or zstd, the suffix
255 .gz, .lz4, or .zst, respectively, will be automatically added to
256 all tar filenames. When the plain format is used, client-side
257 compression may not be specified, but it is still possible to
258 request server-side compression. If this is done, the server will
259 compress the backup for transmission, and the client will
260 decompress and extract it.
261 When this option is used in combination with -Xstream, pg_wal.tar
263 will be compressed using gzip if client-side gzip compression is
264 selected, but will not be compressed if any other compression
265 algorithm is selected, or if server-side compression is selected.
266 The following command-line options control the generation of the backup
268 and the invocation of the program:
269 -c {fast|spread}
271 --checkpoint={fast|spread}
272 Sets checkpoint mode to fast (immediate) or spread (the default)
273 (see Section 26.3.3).
274 -C
276 --create-slot
277 Specifies that the replication slot named by the --slot option
278 should be created before starting the backup. An error is raised if
279 the slot already exists.
280 -l label
282 --label=label
283 Sets the label for the backup. If none is specified, a default
284 value of “pg_basebackup base backup” will be used.
285 -n
287 --no-clean
288 By default, when pg_basebackup aborts with an error, it removes any
289 directories it might have created before discovering that it cannot
290 finish the job (for example, the target directory and write-ahead
291 log directory). This option inhibits tidying-up and is thus useful
292 for debugging.
293 Note that tablespace directories are not cleaned up either way.
295 -N
297 --no-sync
298 By default, pg_basebackup will wait for all files to be written
299 safely to disk. This option causes pg_basebackup to return without
300 waiting, which is faster, but means that a subsequent operating
301 system crash can leave the base backup corrupt. Generally, this
302 option is useful for testing but should not be used when creating a
303 production installation.
304 -P
306 --progress
307 Enables progress reporting. Turning this on will deliver an
308 approximate progress report during the backup. Since the database
309 may change during the backup, this is only an approximation and may
310 not end at exactly 100%. In particular, when WAL log is included in
311 the backup, the total amount of data cannot be estimated in
312 advance, and in this case the estimated target size will increase
313 once it passes the total estimate without WAL.
314 -r rate
316 --max-rate=rate
317 Sets the maximum transfer rate at which data is collected from the
318 source server. This can be useful to limit the impact of
319 pg_basebackup on the server. Values are in kilobytes per second.
320 Use a suffix of M to indicate megabytes per second. A suffix of k
321 is also accepted, and has no effect. Valid values are between 32
322 kilobytes per second and 1024 megabytes per second.
323 This option always affects transfer of the data directory. Transfer
325 of WAL files is only affected if the collection method is fetch.
326 -S slotname
328 --slot=slotname
329 This option can only be used together with -X stream. It causes WAL
330 streaming to use the specified replication slot. If the base backup
331 is intended to be used as a streaming-replication standby using a
332 replication slot, the standby should then use the same replication
333 slot name as primary_slot_name. This ensures that the primary
334 server does not remove any necessary WAL data in the time between
335 the end of the base backup and the start of streaming replication
336 on the new standby.
337 The specified replication slot has to exist unless the option -C is
339 also used.
340 If this option is not specified and the server supports temporary
342 replication slots (version 10 and later), then a temporary
343 replication slot is automatically used for WAL streaming.
344 -v
346 --verbose
347 Enables verbose mode. Will output some extra steps during startup
348 and shutdown, as well as show the exact file name that is currently
349 being processed if progress reporting is also enabled.
350 --manifest-checksums=algorithm
352 Specifies the checksum algorithm that should be applied to each
353 file included in the backup manifest. Currently, the available
354 algorithms are NONE, CRC32C, SHA224, SHA256, SHA384, and SHA512.
355 The default is CRC32C.
356 If NONE is selected, the backup manifest will not contain any
358 checksums. Otherwise, it will contain a checksum of each file in
359 the backup using the specified algorithm. In addition, the manifest
360 will always contain a SHA256 checksum of its own contents. The SHA
361 algorithms are significantly more CPU-intensive than CRC32C, so
362 selecting one of them may increase the time required to complete
363 the backup.
364 Using a SHA hash function provides a cryptographically secure
366 digest of each file for users who wish to verify that the backup
367 has not been tampered with, while the CRC32C algorithm provides a
368 checksum that is much faster to calculate; it is good at catching
369 errors due to accidental changes but is not resistant to malicious
370 modifications. Note that, to be useful against an adversary who has
371 access to the backup, the backup manifest would need to be stored
372 securely elsewhere or otherwise verified not to have been modified
373 since the backup was taken.
374 pg_verifybackup(1) can be used to check the integrity of a backup
376 against the backup manifest.
377 --manifest-force-encode
379 Forces all filenames in the backup manifest to be hex-encoded. If
380 this option is not specified, only non-UTF8 filenames are
381 hex-encoded. This option is mostly intended to test that tools
382 which read a backup manifest file properly handle this case.
383 --no-estimate-size
385 Prevents the server from estimating the total amount of backup data
386 that will be streamed, resulting in the backup_total column in the
387 pg_stat_progress_basebackup view always being NULL.
388 Without this option, the backup will start by enumerating the size
390 of the entire database, and then go back and send the actual
391 contents. This may make the backup take slightly longer, and in
392 particular it will take longer before the first data is sent. This
393 option is useful to avoid such estimation time if it's too long.
394 This option is not allowed when using --progress.
396 --no-manifest
398 Disables generation of a backup manifest. If this option is not
399 specified, the server will generate and send a backup manifest
400 which can be verified using pg_verifybackup(1). The manifest is a
401 list of every file present in the backup with the exception of any
402 WAL files that may be included. It also stores the size, last
403 modification time, and an optional checksum for each file.
404 --no-slot
406 Prevents the creation of a temporary replication slot for the
407 backup.
408 By default, if log streaming is selected but no slot name is given
410 with the -S option, then a temporary replication slot is created
411 (if supported by the source server).
412 The main purpose of this option is to allow taking a base backup
414 when the server has no free replication slots. Using a replication
415 slot is almost always preferred, because it prevents needed WAL
416 from being removed by the server during the backup.
417 --no-verify-checksums
419 Disables verification of checksums, if they are enabled on the
420 server the base backup is taken from.
421 By default, checksums are verified and checksum failures will
423 result in a non-zero exit status. However, the base backup will not
424 be removed in such a case, as if the --no-clean option had been
425 used. Checksum verification failures will also be reported in the
426 pg_stat_database view.
427 The following command-line options control the connection to the source
429 server:
430 -d connstr
432 --dbname=connstr
433 Specifies parameters used to connect to the server, as a connection
434 string; these will override any conflicting command line options.
435 The option is called --dbname for consistency with other client
437 applications, but because pg_basebackup doesn't connect to any
438 particular database in the cluster, any database name in the
439 connection string will be ignored.
440 -h host
442 --host=host
443 Specifies the host name of the machine on which the server is
444 running. If the value begins with a slash, it is used as the
445 directory for a Unix domain socket. The default is taken from the
446 PGHOST environment variable, if set, else a Unix domain socket
447 connection is attempted.
448 -p port
450 --port=port
451 Specifies the TCP port or local Unix domain socket file extension
452 on which the server is listening for connections. Defaults to the
453 PGPORT environment variable, if set, or a compiled-in default.
454 -s interval
456 --status-interval=interval
457 Specifies the number of seconds between status packets sent back to
458 the source server. Smaller values allow more accurate monitoring of
459 backup progress from the server. A value of zero disables periodic
460 status updates completely, although an update will still be sent
461 when requested by the server, to avoid timeout-based disconnects.
462 The default value is 10 seconds.
463 -U username
465 --username=username
466 Specifies the user name to connect as.
467 -w
469 --no-password
470 Prevents issuing a password prompt. If the server requires password
471 authentication and a password is not available by other means such
472 as a .pgpass file, the connection attempt will fail. This option
473 can be useful in batch jobs and scripts where no user is present to
474 enter a password.
475 -W
477 --password
478 Forces pg_basebackup to prompt for a password before connecting to
479 the source server.
480 This option is never essential, since pg_basebackup will
482 automatically prompt for a password if the server demands password
483 authentication. However, pg_basebackup will waste a connection
484 attempt finding out that the server wants a password. In some cases
485 it is worth typing -W to avoid the extra connection attempt.
486 Other options are also available:
488 -V
490 --version
491 Prints the pg_basebackup version and exits.
492 -?
494 --help
495 Shows help about pg_basebackup command line arguments, and exits.
496
498 This utility, like most other PostgreSQL utilities, uses the
499 environment variables supported by libpq (see Section 34.15).
500 The environment variable PG_COLOR specifies whether to use color in
502 diagnostic messages. Possible values are always, auto and never.
503
505 At the beginning of the backup, a checkpoint needs to be performed on
506 the source server. This can take some time (especially if the option
507 --checkpoint=fast is not used), during which pg_basebackup will appear
508 to be idle.
509 The backup will include all files in the data directory and
511 tablespaces, including the configuration files and any additional files
512 placed in the directory by third parties, except certain temporary
513 files managed by PostgreSQL. But only regular files and directories are
514 copied, except that symbolic links used for tablespaces are preserved.
515 Symbolic links pointing to certain directories known to PostgreSQL are
516 copied as empty directories. Other symbolic links and special device
517 files are skipped. See Section 55.4 for the precise details.
518 In plain format, tablespaces will be backed up to the same path they
520 have on the source server, unless the option --tablespace-mapping is
521 used. Without this option, running a plain format base backup on the
522 same host as the server will not work if tablespaces are in use,
523 because the backup would have to be written to the same directory
524 locations as the original tablespaces.
525 When tar format is used, it is the user's responsibility to unpack each
527 tar file before starting a PostgreSQL server that uses the data. If
528 there are additional tablespaces, the tar files for them need to be
529 unpacked in the correct locations. In this case the symbolic links for
530 those tablespaces will be created by the server according to the
531 contents of the tablespace_map file that is included in the base.tar
532 file.
533 pg_basebackup works with servers of the same or an older major version,
535 down to 9.1. However, WAL streaming mode (-X stream) only works with
536 server version 9.3 and later, and tar format (--format=tar) only works
537 with server version 9.5 and later.
538 pg_basebackup will preserve group permissions for data files if group
540 permissions are enabled on the source cluster.
541
543 To create a base backup of the server at mydbserver and store it in the
544 local directory /usr/local/pgsql/data:
545 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
547 To create a backup of the local server with one compressed tar file for
549 each tablespace, and store it in the directory backup, showing a
550 progress report while running:
551 $ pg_basebackup -D backup -Ft -z -P
553 To create a backup of a single-tablespace local database and compress
555 this with bzip2:
556 $ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2
558 (This command will fail if there are multiple tablespaces in the
560 database.)
561 To create a backup of a local database where the tablespace in /opt/ts
563 is relocated to ./backup/ts:
564 $ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts
566 To create a backup of a local server with one tar file for each
568 tablespace compressed with gzip at level 9, stored in the directory
569 backup:
570 $ pg_basebackup -D backup -Ft --compress=gzip:9
572
574 pg_dump(1), Section 28.4.6
575PostgreSQL 16.1 2023 PG_BASEBACKUP(1)