v5-0003-Doc-Warn-about-pg_control-corruption-in-low-level.patch

From 3b28603553bf483c3cda280eeae6790693b930b6 Mon Sep 17 00:00:00 2001
From: Thomas Munro <thomas.munro@gmail.com>
Date: Tue, 25 Jul 2023 11:11:17 +1200
Subject: [PATCH v5 3/4] Doc: Warn about pg_control corruption in low-level
 backups.

On some file systems (ext4, ntfs), copying the control file while it's
being modified to can result in a corrupted file with a bad checksum,
and then recovery fails.  Document a way to test for this problem as
part of the low-level-backup procedure.

Discussion: https://postgr.es/m/20221123014224.xisi44byq3cf5psi%40awork3.anarazel.de
---
 doc/src/sgml/backup.sgml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 8cb24d6ae5..60e110ea0a 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -920,6 +920,23 @@ SELECT pg_backup_start(label => 'label', fast => false);
      consider during this backup.
     </para>
    </listitem>
+   <listitem>
+    <para>
+     One file copied by the previous step requires special consideration.
+     For all other files, the effects of concurrent modification will be
+     corrected by WAL replay, but <literal>global/pg_control</literal> must
+     be self-consistent before replay begins.  On some systems, it might be
+     corrupted by a concurrent modification during the backup.  It can be
+     verified by installing it (after extracting from archive file if
+     applicable) into an otherwise empty directory (e.g.
+     <literal>test_pgdata/global/pg_control</literal>) and then
+     passing the path of the top directory to the
+     <application>pg_controldata</application> program.
+     <application>pg_controldata</application> will verify
+     the internal checksum, and fail if corruption is detected.  In that
+     unlikely case, the file should be backed up again and re-tested.
+    </para>
+   </listitem>
    <listitem>
     <para>
      In the same connection as before, issue the command:
-- 
2.39.2