pgbackrest.git / summary / log / commit / refs
commit 21c8c8a66cb06eba714bfa41bed7239af3d14f08
Author: David Steele <david@pgmasters.net>
Commit: GitHub <noreply@github.com>
Date: Sat Oct 14 20:22:09 2023 +0000
Document maintainer options.
Document maintainer options in a separate section with appropriate explanation and caveats.
Also make the pg-version-force option user visible now that maintainer caveats have been documented.
doc/src/command/build/reference.c | 5 ++-
doc/xml/release/2023/2.49.xml | 13 ++++++
src/build/config/config.yaml | 1 -
src/build/help/help.xml | 84 ++++++++++++++++++++++----------------
src/command/help/help.c | 4 +-
test/src/module/command/helpTest.c | 4 ++
test/src/module/doc/buildTest.c | 1 +
7 files changed, 72 insertions(+), 40 deletions(-)
diff --git a/doc/src/command/build/reference.c b/doc/src/command/build/reference.c
index 88b30ca3c..4e8c69fb6 100644
--- a/doc/src/command/build/reference.c
+++ b/doc/src/command/build/reference.c
@@ -205,8 +205,11 @@ referenceCommandSection(const String *const section)
if (section == NULL)
FUNCTION_TEST_RETURN(STRING, strNewZ("general"));
- if (!strEqZ(section, "general") && !strEqZ(section, "log") && !strEqZ(section, "repository") && !strEqZ(section, "stanza"))
+ if (!strEqZ(section, "general") && !strEqZ(section, "log") && !strEqZ(section, "maintainer") &&
+ !strEqZ(section, "repository") && !strEqZ(section, "stanza"))
+ {
FUNCTION_TEST_RETURN(STRING, strNewZ("command"));
+ }
FUNCTION_TEST_RETURN(STRING, strDup(section));
}
diff --git a/doc/xml/release/2023/2.49.xml b/doc/xml/release/2023/2.49.xml
index 4adb4ba0e..c5e6763d2 100644
--- a/doc/xml/release/2023/2.49.xml
+++ b/doc/xml/release/2023/2.49.xml
@@ -1,5 +1,18 @@
<release date="XXXX-XX-XX" version="2.49dev" title="UNDER DEVELOPMENT">
<release-doc-list>
+ <release-feature-list>
+ <release-item>
+ <github-pull-request id="2202"/>
+
+ <release-item-contributor-list>
+ <release-item-contributor id="david.steele"/>
+ <release-item-reviewer id="stefan.fercot"/>
+ </release-item-contributor-list>
+
+ <p>Document maintainer options.</p>
+ </release-item>
+ </release-feature-list>
+
<release-development-list>
<release-item>
<commit subject="Add new XML functions required for building documentation."/>
diff --git a/src/build/config/config.yaml b/src/build/config/config.yaml
index 013dff08c..a8ff09b30 100644
--- a/src/build/config/config.yaml
+++ b/src/build/config/config.yaml
@@ -1607,7 +1607,6 @@ option:
pg-version-force:
section: stanza
type: string
- internal: true
required: false
command:
archive-get: {}
diff --git a/src/build/help/help.xml b/src/build/help/help.xml
index 9550da641..3fe68e79d 100644
--- a/src/build/help/help.xml
+++ b/src/build/help/help.xml
@@ -432,6 +432,54 @@
</config-key-list>
</config-section>
+ <config-section id="maintainer" name="Maintainer">
+ <text>
+ <p>Maintainer options are intended to support <postgres/> forks. The proper settings should be determined by the fork maintainer and then communicated to users of the fork.</p>
+
+ <admonition type="warning">Improper use of these options may lead to unexpected behavior or data corruption.</admonition>
+
+ <p>It is the responsibility of the fork maintainer to test <backrest/> with the required options. <backrest/> does not guarantee compatibility with any fork.</p>
+ </text>
+
+ <config-key-list>
+ <config-key id="archive-header-check" name="Check WAL Headers">
+ <summary>Check PostgreSQL version/id in WAL headers.</summary>
+
+ <text>
+ <p>Enabled by default, this option checks the WAL header against the <postgres/> version and system identifier to ensure that the WAL is being copied to the correct stanza. This is in addition to checking <file>pg_control</file> against the stanza and verifying that WAL is being copied from the same <postgres/> data directory where <file>pg_control</file> is located.</p>
+
+ <p>Therefore, disabling this check is fairly safe but should only be done when needed, e.g. if the WAL is encrypted.</p>
+ </text>
+
+ <example>n</example>
+ </config-key>
+
+ <config-key id="page-header-check" name="Page Header Check">
+ <summary>Check PostgreSQL page headers.</summary>
+
+ <text>
+ <p>Enabled by default, this option adds page header checks.</p>
+
+ <p>Disabling this option should be avoided except when necessary, e.g. if pages are encrypted.</p>
+ </text>
+
+ <example>n</example>
+ </config-key>
+
+ <config-key id="pg-version-force" name="Force PostgreSQL Version">
+ <summary>Force <postgres/> version.</summary>
+
+ <text>
+ <p>The specified <postgres/> version will be used instead of the version automatically detected by reading <file>pg_control</file> or WAL headers. This is mainly useful for <postgres/> forks or development versions where those values are different from the release version. The version reported by <postgres/> via `server_version_num` must match the forced version.</p>
+
+ <admonition type="warning">Be cautious when using this option because <file>pg_control</file> and WAL headers will still be read with the expected format for the specified version, i.e. the format from the official open-source version of <postgres/>. If the fork or development version changes the format of the fields that <backrest/> depends on it will lead to unexpected behavior. In general, this option will only work as expected if the fork adds all custom struct members <i>after</i> the standard <postgres/> members.</admonition>
+ </text>
+
+ <example>15</example>
+ </config-key>
+ </config-key-list>
+ </config-section>
+
<config-section id="repository" name="Repository">
<text>
<p>The <setting>repository</setting> section defines options used to configure the repository.</p>
@@ -1375,18 +1423,6 @@
<example>y</example>
</config-key>
- <config-key id="page-header-check" name="Page Header Check">
- <summary>Check PostgreSQL page headers.</summary>
-
- <text>
- <p>Enabled by default, this option adds page header checks.</p>
-
- <p>Disabling this option should be avoided except when necessary, e.g. if pages are encrypted.</p>
- </text>
-
- <example>n</example>
- </config-key>
-
<config-key id="resume" name="Resume">
<summary>Allow resume of failed backup.</summary>
@@ -1453,18 +1489,6 @@
<example>1GiB</example>
</config-key>
- <config-key id="archive-header-check" name="Check WAL Headers">
- <summary>Check PostgreSQL version/id in WAL headers.</summary>
-
- <text>
- <p>Enabled by default, this option checks the WAL header against the <postgres/> version and system identifier to ensure that the WAL is being copied to the correct stanza. This is in addition to checking <file>pg_control</file> against the stanza and verifying that WAL is being copied from the same <postgres/> data directory where <file>pg_control</file> is located.</p>
-
- <p>Therefore, disabling this check is fairly safe but should only be done when needed, e.g. if the WAL is encrypted.</p>
- </text>
-
- <example>n</example>
- </config-key>
-
<config-key id="archive-missing-retry" name="Retry Missing WAL Segment">
<summary>Retry missing WAL segment</summary>
@@ -1892,18 +1916,6 @@
<example>25</example>
</config-key>
-
- <config-key id="pg-version-force" name="Force PostgreSQL version">
- <summary>Force <postgres/> version.</summary>
-
- <text>
- <p>The specified <postgres/> version will be used instead of the version automatically detected by reading <file>pg_control</file> or WAL headers. This is mainly useful for <postgres/> forks or development versions where those values are different from the release version. The version reported by <postgres/> via `server_version_num` must match the forced version.</p>
-
- <admonition type="warning">Be cautious when using this option because <file>pg_control</file> and WAL headers will still be read with expected format for the specified version, i.e. the format from the official open-source version of <postgres/>. If the fork or development version changes the format of the fields that <backrest/> depends on it will lead to unexpected behavior.</admonition>
- </text>
-
- <example>15</example>
- </config-key>
</config-key-list>
</config-section>
</config-section-list>
diff --git a/src/command/help/help.c b/src/command/help/help.c
index 4107365d6..5979dcd84 100644
--- a/src/command/help/help.c
+++ b/src/command/help/help.c
@@ -429,8 +429,8 @@ helpRender(const Buffer *const helpData)
const String *section = optionData[optionId].section;
if (section == NULL ||
- (!strEqZ(section, "general") && !strEqZ(section, "log") && !strEqZ(section, "repository") &&
- !strEqZ(section, "stanza")))
+ (!strEqZ(section, "general") && !strEqZ(section, "log") && !strEqZ(section, "maintainer") &&
+ !strEqZ(section, "repository") && !strEqZ(section, "stanza")))
{
section = strNewZ("command");
}
diff --git a/test/src/module/command/helpTest.c b/test/src/module/command/helpTest.c
index eab2e5a60..b37879752 100644
--- a/test/src/module/command/helpTest.c
+++ b/test/src/module/command/helpTest.c
@@ -266,6 +266,10 @@ testRun(void)
" --log-subprocess enable logging in subprocesses [default=n]\n"
" --log-timestamp enable timestamp in logging [default=y]\n"
"\n",
+ "Maintainer Options:\n"
+ "\n"
+ " --pg-version-force force PostgreSQL version\n"
+ "\n"
"Repository Options:\n"
"\n"
" --repo set repository\n"
diff --git a/test/src/module/doc/buildTest.c b/test/src/module/doc/buildTest.c
index 35f37e169..31ba9a381 100644
--- a/test/src/module/doc/buildTest.c
+++ b/test/src/module/doc/buildTest.c
@@ -26,6 +26,7 @@ testRun(void)
TEST_RESULT_STR_Z(referenceCommandSection(STRDEF("general")), "general", "general section no remap");
TEST_RESULT_STR_Z(referenceCommandSection(STRDEF("log")), "log", "log section no remap");
+ TEST_RESULT_STR_Z(referenceCommandSection(STRDEF("maintainer")), "maintainer", "maintainer section no remap");
TEST_RESULT_STR_Z(referenceCommandSection(STRDEF("repository")), "repository", "repository section no remap");
TEST_RESULT_STR_Z(referenceCommandSection(STRDEF("stanza")), "stanza", "stanza section no remap");
[parent: 81536cd486d7]