db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-11-06 08:49:29 +02:00
Code Issues Releases Activity

Document maintainer options.

Browse Source 
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.
This commit is contained in:
David Steele
2023-10-14 16:22:09 -04:00
committed by GitHub
parent 81536cd486
commit 21c8c8a66c
7 changed files with 72 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/src/command/build/reference.c
View File

@@ -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));
}

13
doc/xml/release/2023/2.49.xml
View File

@@ -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."/>

1
src/build/config/config.yaml
View File

@@ -1607,7 +1607,6 @@ option:
pg-version-force:
section: stanza
type: string
internal: true
required: false
command:
archive-get: {}

84
src/build/help/help.xml
View File

@@ -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>

4
src/command/help/help.c
View File

@@ -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");
}

4
test/src/module/command/helpTest.c
View File

@@ -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"

1
test/src/module/doc/buildTest.c
View File

@@ -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");