begriffs open source - ai-pg/blob - full-docs/man1/pg_combinebackup.1

   1 '\" t
   2 .\"     Title: pg_combinebackup
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "PG_COMBINEBACKUP" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 pg_combinebackup \- reconstruct a full backup from an incremental backup and dependent backups
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBpg_combinebackup\fR\ 'u
  34 \fBpg_combinebackup\fR [\fIoption\fR...] [\fIbackup_directory\fR...]
  35 .SH "DESCRIPTION"
  36 .PP
  37 pg_combinebackup
  38 is used to reconstruct a synthetic full backup from an
  39 incremental backup
  40 and the earlier backups upon which it depends\&.
  41 .PP
  42 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
  43 \fB\-o\fR
  44 option\&.
  45 .PP
  46 pg_combinebackup
  47 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,
  48 pg_combinebackup
  49 only attempts to verify that the backups have the correct relationship to each other, not that each individual backup is intact; for that, use
  50 \fBpg_verifybackup\fR(1)\&.
  51 .PP
  52 Since the output of
  53 pg_combinebackup
  54 is a synthetic full backup, it can be used as an input to a future invocation of
  55 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\&.
  56 .SH "OPTIONS"
  57 .PP
  58 .PP
  59 \fB\-d\fR
  60 .br
  61 \fB\-\-debug\fR
  62 .RS 4
  63 Print lots of debug logging output on
  64 stderr\&.
  65 .RE
  66 .PP
  67 \fB\-k\fR
  68 .br
  69 \fB\-\-link\fR
  70 .RS 4
  71 Use hard links instead of copying files to the synthetic backup\&. Reconstruction of the synthetic backup might be faster (no file copying) and use less disk space, but care must be taken when using the output directory, because any modifications to that directory (for example, starting the server) can also affect the input directories\&. Likewise, changes to the input directories (for example, starting the server on the full backup) could affect the output directory\&. Thus, this option is best used when the input directories are only copies that will be removed after
  72 pg_combinebackup
  73 has completed\&.
  74 .sp
  75 Requires that the input backups and the output directory are in the same file system\&.
  76 .sp
  77 If a backup manifest is not available or does not contain checksum of the right type, hard links will still be created, but the file will be also read block\-by\-block for the checksum calculation\&.
  78 .RE
  79 .PP
  80 \fB\-n\fR
  81 .br
  82 \fB\-\-dry\-run\fR
  83 .RS 4
  84 The
  85 \fB\-n\fR/\fB\-\-dry\-run\fR
  86 option instructs
  87 \fBpg_combinebackup\fR
  88 to figure out what would be done without actually creating the target directory or any output files\&. It is particularly useful in combination with
  89 \fB\-\-debug\fR\&.
  90 .RE
  91 .PP
  92 \fB\-N\fR
  93 .br
  94 \fB\-\-no\-sync\fR
  95 .RS 4
  96 By default,
  97 \fBpg_combinebackup\fR
  98 will wait for all files to be written safely to disk\&. This option causes
  99 \fBpg_combinebackup\fR
 100 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\&.
 101 .RE
 102 .PP
 103 \fB\-o \fR\fB\fIoutputdir\fR\fR
 104 .br
 105 \fB\-\-output=\fR\fB\fIoutputdir\fR\fR
 106 .RS 4
 107 Specifies the output directory to which the synthetic full backup should be written\&. Currently, this argument is required\&.
 108 .RE
 109 .PP
 110 \fB\-T \fR\fB\fIolddir\fR\fR\fB=\fR\fB\fInewdir\fR\fR
 111 .br
 112 \fB\-\-tablespace\-mapping=\fR\fB\fIolddir\fR\fR\fB=\fR\fB\fInewdir\fR\fR
 113 .RS 4
 114 Relocates the tablespace in directory
 115 \fIolddir\fR
 116 to
 117 \fInewdir\fR
 118 during the backup\&.
 119 \fIolddir\fR
 120 is the absolute path of the tablespace as it exists in the final backup specified on the command line, and
 121 \fInewdir\fR
 122 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\&.
 123 .RE
 124 .PP
 125 \fB\-\-clone\fR
 126 .RS 4
 127 Use efficient file cloning (also known as
 128 \(lqreflinks\(rq
 129 on some systems) instead of copying files to the new data directory, which can result in near\-instantaneous copying of the data files\&.
 130 .sp
 131 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\&.
 132 .sp
 133 File cloning is only supported on some operating systems and file systems\&. If it is selected but not supported, the
 134 pg_combinebackup
 135 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\&.
 136 .RE
 137 .PP
 138 \fB\-\-copy\fR
 139 .RS 4
 140 Perform regular file copy\&. This is the default\&. (See also
 141 \fB\-\-copy\-file\-range\fR,
 142 \fB\-\-clone\fR, and
 143 \fB\-k\fR/\fB\-\-link\fR\&.)
 144 .RE
 145 .PP
 146 \fB\-\-copy\-file\-range\fR
 147 .RS 4
 148 Use the
 149 \fBcopy_file_range\fR
 150 system call for efficient copying\&. On some file systems this gives results similar to
 151 \fB\-\-clone\fR, 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\&.
 152 .sp
 153 If a backup manifest is not available or does not contain checksum of the right type,
 154 \fBcopy_file_range\fR
 155 will be used to copy the file, but the file will be also read block\-by\-block for the checksum calculation\&.
 156 .RE
 157 .PP
 158 \fB\-\-manifest\-checksums=\fR\fB\fIalgorithm\fR\fR
 159 .RS 4
 160 Like
 161 \fBpg_basebackup\fR(1),
 162 pg_combinebackup
 163 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
 164 NONE,
 165 CRC32C,
 166 SHA224,
 167 SHA256,
 168 SHA384, and
 169 SHA512\&. The default is
 170 CRC32C\&.
 171 .RE
 172 .PP
 173 \fB\-\-no\-manifest\fR
 174 .RS 4
 175 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\&.
 176 .RE
 177 .PP
 178 \fB\-\-sync\-method=\fR\fB\fImethod\fR\fR
 179 .RS 4
 180 When set to
 181 fsync, which is the default,
 182 \fBpg_combinebackup\fR
 183 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\&.
 184 .sp
 185 On Linux,
 186 syncfs
 187 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,
 188 \fBpg_combinebackup\fR
 189 will also synchronize the file systems that contain the WAL files and each tablespace\&. See
 190 recovery_init_sync_method
 191 for information about the caveats to be aware of when using
 192 syncfs\&.
 193 .sp
 194 This option has no effect when
 195 \fB\-\-no\-sync\fR
 196 is used\&.
 197 .RE
 198 .PP
 199 \fB\-V\fR
 200 .br
 201 \fB\-\-version\fR
 202 .RS 4
 203 Prints the
 204 pg_combinebackup
 205 version and exits\&.
 206 .RE
 207 .PP
 208 \fB\-?\fR
 209 .br
 210 \fB\-\-help\fR
 211 .RS 4
 212 Shows help about
 213 pg_combinebackup
 214 command line arguments, and exits\&.
 215 .RE
 216 .SH "LIMITATIONS"
 217 .PP
 218 pg_combinebackup
 219 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\&.
 220 .PP
 221 To avoid this problem, taking a new full backup after changing the checksum state of the cluster using
 222 \fBpg_checksums\fR(1)
 223 is recommended\&. Otherwise, you can disable and then optionally reenable checksums on the directory produced by
 224 pg_combinebackup
 225 in order to correct the problem\&.
 226 .SH "ENVIRONMENT"
 227 .PP
 228 This utility, like most other
 229 PostgreSQL
 230 utilities, uses the environment variables supported by
 231 libpq
 232 (see
 233 Section\ \&32.15)\&.
 234 .PP
 235 The environment variable
 236 \fBPG_COLOR\fR
 237 specifies whether to use color in diagnostic messages\&. Possible values are
 238 always,
 239 auto
 240 and
 241 never\&.
 242 .SH "SEE ALSO"
 243 \fBpg_basebackup\fR(1)