begriffs open source - ai-pg/blob - full-docs/txt/app-pgcombinebackup.txt

   1
   2 pg_combinebackup
   3
   4    pg_combinebackup — reconstruct a full backup from an incremental backup
   5    and dependent backups
   6
   7 Synopsis
   8
   9    pg_combinebackup [option...] [backup_directory...]
  10
  11 Description
  12
  13    pg_combinebackup is used to reconstruct a synthetic full backup from an
  14    incremental backup and the earlier backups upon which it depends.
  15
  16    Specify all of the required backups on the command line from oldest to
  17    newest. That is, the first backup directory should be the path to the
  18    full backup, and the last should be the path to the final incremental
  19    backup that you wish to restore. The reconstructed backup will be
  20    written to the output directory specified by the -o option.
  21
  22    pg_combinebackup will attempt to verify that the backups you specify
  23    form a legal backup chain from which a correct full backup can be
  24    reconstructed. However, it is not designed to help you keep track of
  25    which backups depend on which other backups. If you remove one or more
  26    of the previous backups upon which your incremental backup relies, you
  27    will not be able to restore it. Moreover, pg_combinebackup only
  28    attempts to verify that the backups have the correct relationship to
  29    each other, not that each individual backup is intact; for that, use
  30    pg_verifybackup.
  31
  32    Since the output of pg_combinebackup is a synthetic full backup, it can
  33    be used as an input to a future invocation of pg_combinebackup. The
  34    synthetic full backup would be specified on the command line in lieu of
  35    the chain of backups from which it was reconstructed.
  36
  37 Options
  38
  39    -d
  40           --debug
  41           Print lots of debug logging output on stderr.
  42
  43    -k
  44           --link
  45           Use hard links instead of copying files to the synthetic backup.
  46           Reconstruction of the synthetic backup might be faster (no file
  47           copying) and use less disk space, but care must be taken when
  48           using the output directory, because any modifications to that
  49           directory (for example, starting the server) can also affect the
  50           input directories. Likewise, changes to the input directories
  51           (for example, starting the server on the full backup) could
  52           affect the output directory. Thus, this option is best used when
  53           the input directories are only copies that will be removed after
  54           pg_combinebackup has completed.
  55
  56           Requires that the input backups and the output directory are in
  57           the same file system.
  58
  59           If a backup manifest is not available or does not contain
  60           checksum of the right type, hard links will still be created,
  61           but the file will be also read block-by-block for the checksum
  62           calculation.
  63
  64    -n
  65           --dry-run
  66           The -n/--dry-run option instructs pg_combinebackup to figure out
  67           what would be done without actually creating the target
  68           directory or any output files. It is particularly useful in
  69           combination with --debug.
  70
  71    -N
  72           --no-sync
  73           By default, pg_combinebackup will wait for all files to be
  74           written safely to disk. This option causes pg_combinebackup to
  75           return without waiting, which is faster, but means that a
  76           subsequent operating system crash can leave the output backup
  77           corrupt. Generally, this option is useful for testing but should
  78           not be used when creating a production installation.
  79
  80    -o outputdir
  81           --output=outputdir
  82           Specifies the output directory to which the synthetic full
  83           backup should be written. Currently, this argument is required.
  84
  85    -T olddir=newdir
  86           --tablespace-mapping=olddir=newdir
  87           Relocates the tablespace in directory olddir to newdir during
  88           the backup. olddir is the absolute path of the tablespace as it
  89           exists in the final backup specified on the command line, and
  90           newdir is the absolute path to use for the tablespace in the
  91           reconstructed backup. If either path needs to contain an equal
  92           sign (=), precede that with a backslash. This option can be
  93           specified multiple times for multiple tablespaces.
  94
  95    --clone
  96           Use efficient file cloning (also known as “reflinks” on some
  97           systems) instead of copying files to the new data directory,
  98           which can result in near-instantaneous copying of the data
  99           files.
 100
 101           If a backup manifest is not available or does not contain
 102           checksum of the right type, file cloning will be used to copy
 103           the file, but the file will be also read block-by-block for the
 104           checksum calculation.
 105
 106           File cloning is only supported on some operating systems and
 107           file systems. If it is selected but not supported, the
 108           pg_combinebackup run will error. At present, it is supported on
 109           Linux (kernel 4.5 or later) with Btrfs and XFS (on file systems
 110           created with reflink support), and on macOS with APFS.
 111
 112    --copy
 113           Perform regular file copy. This is the default. (See also
 114           --copy-file-range, --clone, and -k/--link.)
 115
 116    --copy-file-range
 117           Use the copy_file_range system call for efficient copying. On
 118           some file systems this gives results similar to --clone, sharing
 119           physical disk blocks, while on others it may still copy blocks,
 120           but do so via an optimized path. At present, it is supported on
 121           Linux and FreeBSD.
 122
 123           If a backup manifest is not available or does not contain
 124           checksum of the right type, copy_file_range will be used to copy
 125           the file, but the file will be also read block-by-block for the
 126           checksum calculation.
 127
 128    --manifest-checksums=algorithm
 129           Like pg_basebackup, pg_combinebackup writes a backup manifest in
 130           the output directory. This option specifies the checksum
 131           algorithm that should be applied to each file included in the
 132           backup manifest. Currently, the available algorithms are NONE,
 133           CRC32C, SHA224, SHA256, SHA384, and SHA512. The default is
 134           CRC32C.
 135
 136    --no-manifest
 137           Disables generation of a backup manifest. If this option is not
 138           specified, a backup manifest for the reconstructed backup will
 139           be written to the output directory.
 140
 141    --sync-method=method
 142           When set to fsync, which is the default, pg_combinebackup will
 143           recursively open and synchronize all files in the backup
 144           directory. When the plain format is used, the search for files
 145           will follow symbolic links for the WAL directory and each
 146           configured tablespace.
 147
 148           On Linux, syncfs may be used instead to ask the operating system
 149           to synchronize the whole file system that contains the backup
 150           directory. When the plain format is used, pg_combinebackup will
 151           also synchronize the file systems that contain the WAL files and
 152           each tablespace. See recovery_init_sync_method for information
 153           about the caveats to be aware of when using syncfs.
 154
 155           This option has no effect when --no-sync is used.
 156
 157    -V
 158           --version
 159           Prints the pg_combinebackup version and exits.
 160
 161    -?
 162           --help
 163           Shows help about pg_combinebackup command line arguments, and
 164           exits.
 165
 166 Limitations
 167
 168    pg_combinebackup does not recompute page checksums when writing the
 169    output directory. Therefore, if any of the backups used for
 170    reconstruction were taken with checksums disabled, but the final backup
 171    was taken with checksums enabled, the resulting directory may contain
 172    pages with invalid checksums.
 173
 174    To avoid this problem, taking a new full backup after changing the
 175    checksum state of the cluster using pg_checksums is recommended.
 176    Otherwise, you can disable and then optionally reenable checksums on
 177    the directory produced by pg_combinebackup in order to correct the
 178    problem.
 179
 180 Environment
 181
 182    This utility, like most other PostgreSQL utilities, uses the
 183    environment variables supported by libpq (see Section 32.15).
 184
 185    The environment variable PG_COLOR specifies whether to use color in
 186    diagnostic messages. Possible values are always, auto and never.
 187
 188 See Also
 189
 190    pg_basebackup