1PG_BASEBACKUP(1) PostgreSQL 15.4 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.5 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 log 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, or none for
241 no compression. A compression detail string can optionally be
242 specified. If the detail string is an integer, it specifies the
243 compression level. Otherwise, it should be a comma-separated list
244 of items, each of the form keyword or keyword=value. Currently, the
245 supported keywords are level and workers.
246 If no compression level is specified, the default compression level
248 will be used. If only a level is specified without mentioning an
249 algorithm, gzip compression will be used if the level is greater
250 than 0, and no compression will be used if the level is 0.
251 When the tar format is used with gzip, lz4, or zstd, the suffix
253 .gz, .lz4, or .zst, respectively, will be automatically added to
254 all tar filenames. When the plain format is used, client-side
255 compression may not be specified, but it is still possible to
256 request server-side compression. If this is done, the server will
257 compress the backup for transmission, and the client will
258 decompress and extract it.
259 When this option is used in combination with -Xstream, pg_wal.tar
261 will be compressed using gzip if client-side gzip compression is
262 selected, but will not be compressed if any other compression
263 algorithm is selected, or if server-side compression is selected.
264 The following command-line options control the generation of the backup
266 and the invocation of the program:
267 -c {fast|spread}
269 --checkpoint={fast|spread}
270 Sets checkpoint mode to fast (immediate) or spread (the default)
271 (see Section 26.3.3).
272 -C
274 --create-slot
275 Specifies that the replication slot named by the --slot option
276 should be created before starting the backup. An error is raised if
277 the slot already exists.
278 -l label
280 --label=label
281 Sets the label for the backup. If none is specified, a default
282 value of “pg_basebackup base backup” will be used.
283 -n
285 --no-clean
286 By default, when pg_basebackup aborts with an error, it removes any
287 directories it might have created before discovering that it cannot
288 finish the job (for example, the target directory and write-ahead
289 log directory). This option inhibits tidying-up and is thus useful
290 for debugging.
291 Note that tablespace directories are not cleaned up either way.
293 -N
295 --no-sync
296 By default, pg_basebackup will wait for all files to be written
297 safely to disk. This option causes pg_basebackup to return without
298 waiting, which is faster, but means that a subsequent operating
299 system crash can leave the base backup corrupt. Generally, this
300 option is useful for testing but should not be used when creating a
301 production installation.
302 -P
304 --progress
305 Enables progress reporting. Turning this on will deliver an
306 approximate progress report during the backup. Since the database
307 may change during the backup, this is only an approximation and may
308 not end at exactly 100%. In particular, when WAL log is included in
309 the backup, the total amount of data cannot be estimated in
310 advance, and in this case the estimated target size will increase
311 once it passes the total estimate without WAL.
312 -r rate
314 --max-rate=rate
315 Sets the maximum transfer rate at which data is collected from the
316 source server. This can be useful to limit the impact of
317 pg_basebackup on the server. Values are in kilobytes per second.
318 Use a suffix of M to indicate megabytes per second. A suffix of k
319 is also accepted, and has no effect. Valid values are between 32
320 kilobytes per second and 1024 megabytes per second.
321 This option always affects transfer of the data directory. Transfer
323 of WAL files is only affected if the collection method is fetch.
324 -S slotname
326 --slot=slotname
327 This option can only be used together with -X stream. It causes WAL
328 streaming to use the specified replication slot. If the base backup
329 is intended to be used as a streaming-replication standby using a
330 replication slot, the standby should then use the same replication
331 slot name as primary_slot_name. This ensures that the primary
332 server does not remove any necessary WAL data in the time between
333 the end of the base backup and the start of streaming replication
334 on the new standby.
335 The specified replication slot has to exist unless the option -C is
337 also used.
338 If this option is not specified and the server supports temporary
340 replication slots (version 10 and later), then a temporary
341 replication slot is automatically used for WAL streaming.
342 -v
344 --verbose
345 Enables verbose mode. Will output some extra steps during startup
346 and shutdown, as well as show the exact file name that is currently
347 being processed if progress reporting is also enabled.
348 --manifest-checksums=algorithm
350 Specifies the checksum algorithm that should be applied to each
351 file included in the backup manifest. Currently, the available
352 algorithms are NONE, CRC32C, SHA224, SHA256, SHA384, and SHA512.
353 The default is CRC32C.
354 If NONE is selected, the backup manifest will not contain any
356 checksums. Otherwise, it will contain a checksum of each file in
357 the backup using the specified algorithm. In addition, the manifest
358 will always contain a SHA256 checksum of its own contents. The SHA
359 algorithms are significantly more CPU-intensive than CRC32C, so
360 selecting one of them may increase the time required to complete
361 the backup.
362 Using a SHA hash function provides a cryptographically secure
364 digest of each file for users who wish to verify that the backup
365 has not been tampered with, while the CRC32C algorithm provides a
366 checksum that is much faster to calculate; it is good at catching
367 errors due to accidental changes but is not resistant to malicious
368 modifications. Note that, to be useful against an adversary who has
369 access to the backup, the backup manifest would need to be stored
370 securely elsewhere or otherwise verified not to have been modified
371 since the backup was taken.
372 pg_verifybackup(1) can be used to check the integrity of a backup
374 against the backup manifest.
375 --manifest-force-encode
377 Forces all filenames in the backup manifest to be hex-encoded. If
378 this option is not specified, only non-UTF8 filenames are
379 hex-encoded. This option is mostly intended to test that tools
380 which read a backup manifest file properly handle this case.
381 --no-estimate-size
383 Prevents the server from estimating the total amount of backup data
384 that will be streamed, resulting in the backup_total column in the
385 pg_stat_progress_basebackup view always being NULL.
386 Without this option, the backup will start by enumerating the size
388 of the entire database, and then go back and send the actual
389 contents. This may make the backup take slightly longer, and in
390 particular it will take longer before the first data is sent. This
391 option is useful to avoid such estimation time if it's too long.
392 This option is not allowed when using --progress.
394 --no-manifest
396 Disables generation of a backup manifest. If this option is not
397 specified, the server will generate and send a backup manifest
398 which can be verified using pg_verifybackup(1). The manifest is a
399 list of every file present in the backup with the exception of any
400 WAL files that may be included. It also stores the size, last
401 modification time, and an optional checksum for each file.
402 --no-slot
404 Prevents the creation of a temporary replication slot for the
405 backup.
406 By default, if log streaming is selected but no slot name is given
408 with the -S option, then a temporary replication slot is created
409 (if supported by the source server).
410 The main purpose of this option is to allow taking a base backup
412 when the server has no free replication slots. Using a replication
413 slot is almost always preferred, because it prevents needed WAL
414 from being removed by the server during the backup.
415 --no-verify-checksums
417 Disables verification of checksums, if they are enabled on the
418 server the base backup is taken from.
419 By default, checksums are verified and checksum failures will
421 result in a non-zero exit status. However, the base backup will not
422 be removed in such a case, as if the --no-clean option had been
423 used. Checksum verification failures will also be reported in the
424 pg_stat_database view.
425 The following command-line options control the connection to the source
427 server:
428 -d connstr
430 --dbname=connstr
431 Specifies parameters used to connect to the server, as a connection
432 string; these will override any conflicting command line options.
433 The option is called --dbname for consistency with other client
435 applications, but because pg_basebackup doesn't connect to any
436 particular database in the cluster, any database name in the
437 connection string will be ignored.
438 -h host
440 --host=host
441 Specifies the host name of the machine on which the server is
442 running. If the value begins with a slash, it is used as the
443 directory for a Unix domain socket. The default is taken from the
444 PGHOST environment variable, if set, else a Unix domain socket
445 connection is attempted.
446 -p port
448 --port=port
449 Specifies the TCP port or local Unix domain socket file extension
450 on which the server is listening for connections. Defaults to the
451 PGPORT environment variable, if set, or a compiled-in default.
452 -s interval
454 --status-interval=interval
455 Specifies the number of seconds between status packets sent back to
456 the source server. Smaller values allow more accurate monitoring of
457 backup progress from the server. A value of zero disables periodic
458 status updates completely, although an update will still be sent
459 when requested by the server, to avoid timeout-based disconnects.
460 The default value is 10 seconds.
461 -U username
463 --username=username
464 Specifies the user name to connect as.
465 -w
467 --no-password
468 Prevents issuing a password prompt. If the server requires password
469 authentication and a password is not available by other means such
470 as a .pgpass file, the connection attempt will fail. This option
471 can be useful in batch jobs and scripts where no user is present to
472 enter a password.
473 -W
475 --password
476 Forces pg_basebackup to prompt for a password before connecting to
477 the source server.
478 This option is never essential, since pg_basebackup will
480 automatically prompt for a password if the server demands password
481 authentication. However, pg_basebackup will waste a connection
482 attempt finding out that the server wants a password. In some cases
483 it is worth typing -W to avoid the extra connection attempt.
484 Other options are also available:
486 -V
488 --version
489 Prints the pg_basebackup version and exits.
490 -?
492 --help
493 Shows help about pg_basebackup command line arguments, and exits.
494
496 This utility, like most other PostgreSQL utilities, uses the
497 environment variables supported by libpq (see Section 34.15).
498 The environment variable PG_COLOR specifies whether to use color in
500 diagnostic messages. Possible values are always, auto and never.
501
503 At the beginning of the backup, a checkpoint needs to be performed on
504 the source server. This can take some time (especially if the option
505 --checkpoint=fast is not used), during which pg_basebackup will appear
506 to be idle.
507 The backup will include all files in the data directory and
509 tablespaces, including the configuration files and any additional files
510 placed in the directory by third parties, except certain temporary
511 files managed by PostgreSQL. But only regular files and directories are
512 copied, except that symbolic links used for tablespaces are preserved.
513 Symbolic links pointing to certain directories known to PostgreSQL are
514 copied as empty directories. Other symbolic links and special device
515 files are skipped. See Section 55.4 for the precise details.
516 In plain format, tablespaces will be backed up to the same path they
518 have on the source server, unless the option --tablespace-mapping is
519 used. Without this option, running a plain format base backup on the
520 same host as the server will not work if tablespaces are in use,
521 because the backup would have to be written to the same directory
522 locations as the original tablespaces.
523 When tar format is used, it is the user's responsibility to unpack each
525 tar file before starting a PostgreSQL server that uses the data. If
526 there are additional tablespaces, the tar files for them need to be
527 unpacked in the correct locations. In this case the symbolic links for
528 those tablespaces will be created by the server according to the
529 contents of the tablespace_map file that is included in the base.tar
530 file.
531 pg_basebackup works with servers of the same or an older major version,
533 down to 9.1. However, WAL streaming mode (-X stream) only works with
534 server version 9.3 and later, and tar format (--format=tar) only works
535 with server version 9.5 and later.
536 pg_basebackup will preserve group permissions for data files if group
538 permissions are enabled on the source cluster.
539
541 To create a base backup of the server at mydbserver and store it in the
542 local directory /usr/local/pgsql/data:
543 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
545 To create a backup of the local server with one compressed tar file for
547 each tablespace, and store it in the directory backup, showing a
548 progress report while running:
549 $ pg_basebackup -D backup -Ft -z -P
551 To create a backup of a single-tablespace local database and compress
553 this with bzip2:
554 $ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2
556 (This command will fail if there are multiple tablespaces in the
558 database.)
559 To create a backup of a local database where the tablespace in /opt/ts
561 is relocated to ./backup/ts:
562 $ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts
564 To create a backup of a local server with one tar file for each
566 tablespace compressed with gzip at level 9, stored in the directory
567 backup:
568 $ pg_basebackup -D backup -Ft --compress=gzip:9
570
572 pg_dump(1), Section 28.4.5
573PostgreSQL 15.4 2023 PG_BASEBACKUP(1)