Debian Codegraph @

doc/src/sgml/ref/pg_combinebackup.sgml

raw
1 <!--
2 doc/src/sgml/ref/pg_combinebackup.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="app-pgcombinebackup">
7 <indexterm zone="app-pgcombinebackup">
8 <primary>pg_combinebackup</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle><application>pg_combinebackup</application></refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>pg_combinebackup</refname>
19 <refpurpose>reconstruct a full backup from an incremental backup and dependent backups</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <cmdsynopsis>
24 <command>pg_combinebackup</command>
25 <arg rep="repeat"><replaceable>option</replaceable></arg>
26 <arg rep="repeat"><replaceable>backup_directory</replaceable></arg>
27 </cmdsynopsis>
28 </refsynopsisdiv>
29
30 <refsect1>
31 <title>Description</title>
32 <para>
33 <application>pg_combinebackup</application> is used to reconstruct a
34 synthetic full backup from an
35 <link linkend="backup-incremental-backup">incremental backup</link> and the
36 earlier backups upon which it depends.
37 </para>
38
39 <para>
40 Specify all of the required backups on the command line from oldest to newest.
41 That is, the first backup directory should be the path to the full backup, and
42 the last should be the path to the final incremental backup
43 that you wish to restore. The reconstructed backup will be written to the
44 output directory specified by the <option>-o</option> option.
45 </para>
46
47 <para>
48 <application>pg_combinebackup</application> will attempt to verify
49 that the backups you specify form a legal backup chain from which a correct
50 full backup can be reconstructed. However, it is not designed to help you
51 keep track of which backups depend on which other backups. If you remove
52 one or more of the previous backups upon which your incremental
53 backup relies, you will not be able to restore it. Moreover,
54 <application>pg_combinebackup</application> only attempts to verify that the
55 backups have the correct relationship to each other, not that each
56 individual backup is intact; for that, use
57 <xref linkend="app-pgverifybackup" />.
58 </para>
59
60 <para>
61 Since the output of <application>pg_combinebackup</application> is a
62 synthetic full backup, it can be used as an input to a future invocation of
63 <application>pg_combinebackup</application>. The synthetic full backup would
64 be specified on the command line in lieu of the chain of backups from which
65 it was reconstructed.
66 </para>
67 </refsect1>
68
69 <refsect1>
70 <title>Options</title>
71
72 <para>
73 <variablelist>
74 <varlistentry>
75 <term><option>-d</option></term>
76 <term><option>--debug</option></term>
77 <listitem>
78 <para>
79 Print lots of debug logging output on <filename>stderr</filename>.
80 </para>
81 </listitem>
82 </varlistentry>
83
84 <varlistentry>
85 <term><option>-k</option></term>
86 <term><option>--link</option></term>
87 <listitem>
88 <para>
89 Use hard links instead of copying files to the synthetic backup.
90 Reconstruction of the synthetic backup might be faster (no file copying)
91 and use less disk space, but care must be taken when using the output
92 directory, because any modifications to that directory (for example,
93 starting the server) can also affect the input directories. Likewise,
94 changes to the input directories (for example, starting the server on
95 the full backup) could affect the output directory. Thus, this option
96 is best used when the input directories are only copies that will be
97 removed after <application>pg_combinebackup</application> has completed.
98 </para>
99
100 <para>
101 Requires that the input backups and the output directory are in the
102 same file system.
103 </para>
104
105 <para>
106 If a backup manifest is not available or does not contain checksum of
107 the right type, hard links will still be created, but the file will be
108 also read block-by-block for the checksum calculation.
109 </para>
110 </listitem>
111 </varlistentry>
112
113 <varlistentry>
114 <term><option>-n</option></term>
115 <term><option>--dry-run</option></term>
116 <listitem>
117 <para>
118 The <option>-n</option>/<option>--dry-run</option> option instructs
119 <command>pg_combinebackup</command> to figure out what would be done
120 without actually creating the target directory or any output files.
121 It is particularly useful in combination with <option>--debug</option>.
122 </para>
123 </listitem>
124 </varlistentry>
125
126 <varlistentry>
127 <term><option>-N</option></term>
128 <term><option>--no-sync</option></term>
129 <listitem>
130 <para>
131 By default, <command>pg_combinebackup</command> will wait for all files
132 to be written safely to disk. This option causes
133 <command>pg_combinebackup</command> to return without waiting, which is
134 faster, but means that a subsequent operating system crash can leave
135 the output backup corrupt. Generally, this option is useful for testing
136 but should not be used when creating a production installation.
137 </para>
138 </listitem>
139 </varlistentry>
140
141 <varlistentry>
142 <term><option>-o <replaceable class="parameter">outputdir</replaceable></option></term>
143 <term><option>--output=<replaceable class="parameter">outputdir</replaceable></option></term>
144 <listitem>
145 <para>
146 Specifies the output directory to which the synthetic full backup
147 should be written. Currently, this argument is required.
148 </para>
149 </listitem>
150 </varlistentry>
151
152 <varlistentry>
153 <term><option>-T <replaceable class="parameter">olddir</replaceable>=<replaceable class="parameter">newdir</replaceable></option></term>
154 <term><option>--tablespace-mapping=<replaceable class="parameter">olddir</replaceable>=<replaceable class="parameter">newdir</replaceable></option></term>
155 <listitem>
156 <para>
157 Relocates the tablespace in directory <replaceable>olddir</replaceable>
158 to <replaceable>newdir</replaceable> during the backup.
159 <replaceable>olddir</replaceable> is the absolute path of the tablespace
160 as it exists in the final backup specified on the command line,
161 and <replaceable>newdir</replaceable> is the absolute path to use for the
162 tablespace in the reconstructed backup. If either path needs to contain
163 an equal sign (<literal>=</literal>), precede that with a backslash.
164 This option can be specified multiple times for multiple tablespaces.
165 </para>
166 </listitem>
167 </varlistentry>
168
169 <varlistentry>
170 <term><option>--clone</option></term>
171 <listitem>
172 <para>
173 Use efficient file cloning (also known as <quote>reflinks</quote> on
174 some systems) instead of copying files to the new data directory,
175 which can result in near-instantaneous copying of the data files.
176 </para>
177
178 <para>
179 If a backup manifest is not available or does not contain checksum of
180 the right type, file cloning will be used to copy the file, but the
181 file will be also read block-by-block for the checksum calculation.
182 </para>
183
184 <para>
185 File cloning is only supported on some operating systems and file
186 systems. If it is selected but not supported, the
187 <application>pg_combinebackup</application> run will error. At present,
188 it is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on
189 file systems created with reflink support), and on macOS with APFS.
190 </para>
191 </listitem>
192 </varlistentry>
193
194 <varlistentry>
195 <term><option>--copy</option></term>
196 <listitem>
197 <para>
198 Perform regular file copy. This is the default. (See also
199 <option>--copy-file-range</option>, <option>--clone</option>, and
200 <option>-k</option>/<option>--link</option>.)
201 </para>
202 </listitem>
203 </varlistentry>
204
205 <varlistentry>
206 <term><option>--copy-file-range</option></term>
207 <listitem>
208 <para>
209 Use the <function>copy_file_range</function> system call for efficient
210 copying. On some file systems this gives results similar to
211 <option>--clone</option>, sharing physical disk blocks, while on others
212 it may still copy blocks, but do so via an optimized path. At present,
213 it is supported on Linux and FreeBSD.
214 </para>
215
216 <para>
217 If a backup manifest is not available or does not contain checksum of
218 the right type, <function>copy_file_range</function> will be used to
219 copy the file, but the file will be also read block-by-block for the
220 checksum calculation.
221 </para>
222 </listitem>
223 </varlistentry>
224
225 <varlistentry>
226 <term><option>--manifest-checksums=<replaceable class="parameter">algorithm</replaceable></option></term>
227 <listitem>
228 <para>
229 Like <xref linkend="app-pgbasebackup"/>,
230 <application>pg_combinebackup</application> writes a backup manifest
231 in the output directory. This option specifies the checksum algorithm
232 that should be applied to each file included in the backup manifest.
233 Currently, the available algorithms are <literal>NONE</literal>,
234 <literal>CRC32C</literal>, <literal>SHA224</literal>,
235 <literal>SHA256</literal>, <literal>SHA384</literal>,
236 and <literal>SHA512</literal>. The default is <literal>CRC32C</literal>.
237 </para>
238 </listitem>
239 </varlistentry>
240
241 <varlistentry>
242 <term><option>--no-manifest</option></term>
243 <listitem>
244 <para>
245 Disables generation of a backup manifest. If this option is not
246 specified, a backup manifest for the reconstructed backup will be
247 written to the output directory.
248 </para>
249 </listitem>
250 </varlistentry>
251
252 <varlistentry>
253 <term><option>--sync-method=<replaceable class="parameter">method</replaceable></option></term>
254 <listitem>
255 <para>
256 When set to <literal>fsync</literal>, which is the default,
257 <command>pg_combinebackup</command> will recursively open and synchronize
258 all files in the backup directory. When the plain format is used, the
259 search for files will follow symbolic links for the WAL directory and
260 each configured tablespace.
261 </para>
262 <para>
263 On Linux, <literal>syncfs</literal> may be used instead to ask the
264 operating system to synchronize the whole file system that contains the
265 backup directory. When the plain format is used,
266 <command>pg_combinebackup</command> will also synchronize the file systems
267 that contain the WAL files and each tablespace. See
268 <xref linkend="guc-recovery-init-sync-method"/> for information about
269 the caveats to be aware of when using <literal>syncfs</literal>.
270 </para>
271 <para>
272 This option has no effect when <option>--no-sync</option> is used.
273 </para>
274 </listitem>
275 </varlistentry>
276
277 <varlistentry>
278 <term><option>-V</option></term>
279 <term><option>--version</option></term>
280 <listitem>
281 <para>
282 Prints the <application>pg_combinebackup</application> version and
283 exits.
284 </para>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry>
289 <term><option>-?</option></term>
290 <term><option>--help</option></term>
291 <listitem>
292 <para>
293 Shows help about <application>pg_combinebackup</application> command
294 line arguments, and exits.
295 </para>
296 </listitem>
297 </varlistentry>
298
299 </variablelist>
300 </para>
301
302 </refsect1>
303
304 <refsect1 id="app-pgcombinebackup-limitations">
305 <title>Limitations</title>
306
307 <para>
308 <literal>pg_combinebackup</literal> does not recompute page checksums when
309 writing the output directory. Therefore, if any of the backups used for
310 reconstruction were taken with checksums disabled, but the final backup was
311 taken with checksums enabled, the resulting directory may contain pages
312 with invalid checksums.
313 </para>
314
315 <para>
316 To avoid this problem, taking a new full backup after changing the checksum
317 state of the cluster using <xref linkend="app-pgchecksums"/> is
318 recommended. Otherwise, you can disable and then optionally reenable
319 checksums on the directory produced by <literal>pg_combinebackup</literal>
320 in order to correct the problem.
321 </para>
322 </refsect1>
323
324 <refsect1>
325 <title>Environment</title>
326
327 <para>
328 This utility, like most other <productname>PostgreSQL</productname> utilities,
329 uses the environment variables supported by <application>libpq</application>
330 (see <xref linkend="libpq-envars"/>).
331 </para>
332
333 <para>
334 The environment variable <envar>PG_COLOR</envar> specifies whether to use
335 color in diagnostic messages. Possible values are
336 <literal>always</literal>, <literal>auto</literal> and
337 <literal>never</literal>.
338 </para>
339 </refsect1>
340
341 <refsect1>
342 <title>See Also</title>
343
344 <simplelist type="inline">
345 <member><xref linkend="app-pgbasebackup"/></member>
346 </simplelist>
347 </refsect1>
348
349 </refentry>