Hi, The --sync-method entry on the pg_combinebackup reference page was copied from pg_basebackup and still says "When the plain format is used" twice, but pg_combinebackup has no format option: it always writes a plain data directory. It also says the "backup directory" is synchronized, which is ambiguous for a tool whose inputs are backup directories; what it syncs is the output directory (sync_pgdata() on opt.output), always following the WAL directory and tablespace symbolic links.
The attached patch drops the two references to the plain format and says "output directory". The text is the same on REL_17_STABLE and REL_18_STABLE, and the patch applies to both; the docs build and validate. Regards, Sai Pranav
From 5033b6b6d0feea5539e364bb34bc48a159f83bf0 Mon Sep 17 00:00:00 2001 From: Sai Pranav <[email protected]> Date: Wed, 4 Nov 2026 21:06:27 +0530 Subject: [PATCH v1] doc: Fix pg_combinebackup's description of --sync-method The description was copied from pg_basebackup and kept two references to "the plain format", but pg_combinebackup has no output format option: it always writes a plain data directory. It also said that the "backup directory" is synchronized, which is ambiguous for a tool whose inputs are backup directories. pg_combinebackup synchronizes the output directory, always following the WAL directory and tablespace symbolic links (and, with syncfs, syncing the file systems containing them). Backpatch-through: 17 --- doc/src/sgml/ref/pg_combinebackup.sgml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/src/sgml/ref/pg_combinebackup.sgml b/doc/src/sgml/ref/pg_combinebackup.sgml index f5d7e177b36..7368af80c69 100644 --- a/doc/src/sgml/ref/pg_combinebackup.sgml +++ b/doc/src/sgml/ref/pg_combinebackup.sgml @@ -255,16 +255,15 @@ PostgreSQL documentation <para> When set to <literal>fsync</literal>, which is the default, <command>pg_combinebackup</command> 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. + all files in the output directory. The search for files will follow + symbolic links for the WAL directory and each configured tablespace. </para> <para> On Linux, <literal>syncfs</literal> 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, - <command>pg_combinebackup</command> will also synchronize the file systems - that contain the WAL files and each tablespace. See + output directory. <command>pg_combinebackup</command> will also + synchronize the file systems that contain the WAL files and each + tablespace. See <xref linkend="guc-recovery-init-sync-method"/> for information about the caveats to be aware of when using <literal>syncfs</literal>. </para> -- 2.50.1 (Apple Git-155)
