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]