PG_COMBINEBACKUP(1)

💅 PG_COMBINEBACKUP — reconstruct a full backup from an incremental backup and dependent backups ✨

okay so welcome to the <pink>pg_combinebackup</pink> page, part of the PostgreSQL 17.11 Documentation bestie. this is the tool that glues your incremental backups back into one whole full backup. she's giving restoration era. 🦋

---

✨ SYNOPSIS ✨

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

---

💖 DESCRIPTION 💖

pg_combinebackup reconstructs a synthetic full backup from an incremental backup plus all the earlier backups it depends on. it's giving frankenstein but make it ✨legitimate✨.

so here's the vibe: you list all the required backups on the command line, oldest to newest. yes, in that order, i'm serious 🙈. 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 actually want to restore. the reconstructed backup gets written to the output directory you specify with the -o option. periodt.

pg_combinebackup will attempt to verify that the backups you specify form a legal backup chain — like, one from which a correct full backup can actually be reconstructed. but listen 👀 — she is not designed to help you keep track of which backups depend on which other backups. if you delete one or more of the previous backups that your incremental backup relies on, you will not be able to restore it. that's it, that's the tragedy. 😭

and also — and this is the part people skip — pg_combinebackup only tries to verify that the backups have the correct relationship to each other. it does not check that each individual backup is intact. for that, use pg_verifybackup(1). two different jobs, bestie, don't conflate them 💅.

here's the cute part though: since the output of pg_combinebackup is itself a synthetic full backup, it can absolutely be used as an input to a future invocation of pg_combinebackup. iconic. you'd just specify that synthetic full backup on the command line in lieu of the whole chain of backups it was reconstructed from. slay. 👑

---

🎀 OPTIONS 🎀

• -d, --debug — prints lots of debug logging output on stderr. wordy queen. 🗣️
• -n, --dry-run — this option instructs pg_combinebackup to figure out what would be done, without actually creating the target directory or any output files. it's especially useful in combination with --debug. a little preview era, no commitment. 🙈
• -N, --no-sync — by default, pg_combinebackup waits for all files to be written safely to disk. this option makes her return without waiting, which is faster, but means that a subsequent operating system crash can leave the output backup corrupt. generally this one is useful for testing but should not be used when creating a production installation. bestie i'm begging you 😭
• -o outputdir, --output=outputdir — specifies the output directory where the synthetic full backup should be written. currently, this argument is required. no output dir, no backup, no vibes.
• -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. yes, multiple times. go off. 💫
• --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 a checksum of the right type, file cloning will be used to copy the file, but the file will also be read block-by-block for the checksum calculation.

file cloning is only supported on some operating systems and file systems. if it's selected but not supported, the pg_combinebackup run will error. at present, it's supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on file systems created with reflink support), and on macOS with APFS. know your filesystem before you commit, iykyk. 🧚

• --copy — perform regular file copy. this is the default. (see also --copy-file-range and --clone.) the reliable friend. 🫶
• --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's supported on Linux and FreeBSD. 🌈

if a backup manifest is not available, or does not contain a checksum of the right type, copy_file_range will be used to copy the file, but the file will also be 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. (yes, she writes one by default. very thorough of her.)
• --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. (obvi.)

• -V, --version — prints the pg_combinebackup version and exits. short and sweet. 💅
• -?, --help — shows help about pg_combinebackup command line arguments, and exits. when in doubt, -?. 🎀

---

⚠️ LIMITATIONS ⚠️

pg_combinebackup does not recompute page checksums when writing the output directory. soooo 😬 — 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. that's the whole limitation, and it's lowkey a big deal.

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. either way, handle it. don't just leave it there being broken. 🙏

---

🌸 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. aesthetic choices matter, bestie 🌈

---

🦋 SEE ALSO 🦋

pg_basebackup(1)

---

psst — and honestly, also go peek at pg_verifybackup(1) and pg_checksums(1) if you're doing any of the stuff mentioned above. the page said it, not me. 💜

---

okay that's the whole page, mwah 💋 — brought to you by PostgreSQL 17.11, dated 2026. go forth and combine those backups, you absolute icon. 👑✨