NAME

       pg_combinebackup - reconstruct a full backup from an incremental backup and dependent
       backups

SYNOPSIS

       pg_combinebackup [option...] [backup_directory...]

DESCRIPTION

       pg_combinebackup is used to reconstruct a synthetic full backup from an incremental backup
       and the earlier backups upon which it depends.

       Specify all of the required backups on the command line from oldest to newest. That is,
       the first backup directory should be the path to the full backup, and the last should be
       the path to the final incremental backup that you wish to restore. The reconstructed
       backup will be written to the output directory specified by the -o option.

       pg_combinebackup will attempt to verify that the backups you specify form a legal backup
       chain from which a correct full backup can be reconstructed. However, it is not designed
       to help you keep track of which backups depend on which other backups. If you remove one
       or more of the previous backups upon which your incremental backup relies, you will not be
       able to restore it. Moreover, pg_combinebackup only attempts to verify that the backups
       have the correct relationship to each other, not that each individual backup is intact;
       for that, use pg_verifybackup(1).

       Since the output of pg_combinebackup is a synthetic full backup, it can be used as an
       input to a future invocation of pg_combinebackup. The synthetic full backup would be
       specified on the command line in lieu of the chain of backups from which it was
       reconstructed.

OPTIONS

       -d
       --debug
           Print lots of debug logging output on stderr.

       -n
       --dry-run
           The -n/--dry-run option instructs pg_combinebackup to figure out what would be done
           without actually creating the target directory or any output files. It is particularly
           useful in combination with --debug.

       -N
       --no-sync
           By default, pg_combinebackup will wait for all files to be written safely to disk.
           This option causes pg_combinebackup to return without waiting, which is faster, but
           means that a subsequent operating system crash can leave the output backup corrupt.
           Generally, this option is useful for testing but should not be used when creating a
           production installation.

       -o outputdir
       --output=outputdir
           Specifies the output directory to which the synthetic full backup should be written.
           Currently, this argument is required.

       -T olddir=newdir
       --tablespace-mapping=olddir=newdir
           Relocates the tablespace in directory olddir to newdir during the backup.  olddir is
           the absolute path of the tablespace as it exists in the final backup specified on the
           command line, and newdir is the absolute path to use for the tablespace in the
           reconstructed backup. If either path needs to contain an equal sign (=), precede that
           with a backslash. This option can be specified multiple times for multiple
           tablespaces.

       --clone
           Use efficient file cloning (also known as “reflinks” on some systems) instead of
           copying files to the new data directory, which can result in near-instantaneous
           copying of the data files.

           If a backup manifest is not available or does not contain checksum of the right type,
           file cloning will be used to copy the file, but the file will be also read
           block-by-block for the checksum calculation.

           File cloning is only supported on some operating systems and file systems. If it is
           selected but not supported, the pg_combinebackup run will error. At present, it is
           supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on file systems created
           with reflink support), and on macOS with APFS.

       --copy
           Perform regular file copy. This is the default. (See also --copy-file-range and
           --clone.)

       --copy-file-range
           Use the copy_file_range system call for efficient copying. On some file systems this
           gives results similar to --clone, sharing physical disk blocks, while on others it may
           still copy blocks, but do so via an optimized path. At present, it is supported on
           Linux and FreeBSD.

           If a backup manifest is not available or does not contain checksum of the right type,
           copy_file_range will be used to copy the file, but the file will be also read
           block-by-block for the checksum calculation.

       --manifest-checksums=algorithm
           Like pg_basebackup(1), pg_combinebackup writes a backup manifest in the output
           directory. This option specifies the checksum algorithm that should be applied to each
           file included in the backup manifest. Currently, the available algorithms are NONE,
           CRC32C, SHA224, SHA256, SHA384, and SHA512. The default is CRC32C.

       --no-manifest
           Disables generation of a backup manifest. If this option is not specified, a backup
           manifest for the reconstructed backup will be written to the output directory.

       --sync-method=method
           When set to fsync, which is the default, pg_combinebackup will recursively open and
           synchronize all files in the backup directory. When the plain format is used, the
           search for files will follow symbolic links for the WAL directory and each configured
           tablespace.

           On Linux, syncfs may be used instead to ask the operating system to synchronize the
           whole file system that contains the backup directory. When the plain format is used,
           pg_combinebackup will also synchronize the file systems that contain the WAL files and
           each tablespace. See recovery_init_sync_method for information about the caveats to be
           aware of when using syncfs.

           This option has no effect when --no-sync is used.

       -V
       --version
           Prints the pg_combinebackup version and exits.

       -?
       --help
           Shows help about pg_combinebackup command line arguments, and exits.

LIMITATIONS

       pg_combinebackup does not recompute page checksums when writing the output directory.
       Therefore, if any of the backups used for reconstruction were taken with checksums
       disabled, but the final backup was taken with checksums enabled, the resulting directory
       may contain pages with invalid checksums.

       To avoid this problem, taking a new full backup after changing the checksum state of the
       cluster using pg_checksums(1) is recommended. Otherwise, you can disable and then
       optionally reenable checksums on the directory produced by pg_combinebackup in order to
       correct the problem.

ENVIRONMENT

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

       The environment variable PG_COLOR specifies whether to use color in diagnostic messages.
       Possible values are always, auto and never.

SEE ALSO

       pg_basebackup(1)