db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-01-18 04:58:51 +02:00
Code Issues Releases Activity

Add admonitions to documentation renderers.

Browse Source 
Admonitions call out places where the user should take special care.

Support added for HTML, PDF, Markdown and help text renderers.  XML files have been updated accordingly.

Contributed by Cynthia Shang.
This commit is contained in:
Cynthia Shang 2018-12-30 16:40:20 +02:00 committed by David Steele
parent 3dc327fd05
commit 72865ca33b
15 changed files with 234 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/lib/BackRestDoc/Common/Doc.pm
View File

@ -117,7 +117,8 @@ sub parse
my %oOut;
my $iIndex = 0;
my $bText = $strName eq 'text' || $strName eq 'li' || $strName eq 'p' || $strName eq 'title' ||
$strName eq 'summary' || $strName eq 'table-cell' || $strName eq 'table-column' || $strName eq 'list-item';
$strName eq 'summary' || $strName eq 'table-cell' || $strName eq 'table-column' || $strName eq 'list-item' ||
$strName eq 'admonition';
# Store the node name
$oOut{name} = $strName;
@ -232,7 +233,8 @@ sub build
}
if ($$oDoc{name} eq 'p' || $$oDoc{name} eq 'title' || $$oDoc{name} eq 'summary' ||
$$oDoc{name} eq 'table-cell' || $$oDoc{name} eq 'table-column' || $$oDoc{name} eq 'list-item')
$$oDoc{name} eq 'table-cell' || $$oDoc{name} eq 'table-column' || $$oDoc{name} eq 'list-item' ||
$$oDoc{name} eq 'admonition')
{
$$oOut{field}{text} = $oDoc;
}

109
doc/lib/BackRestDoc/Common/DocRender.pm
View File

@ -51,7 +51,8 @@ my $oRenderTag =
# 'exe' => [undef, ''],
'backrest' => [undef, ''],
'proper' => ['', ''],
'postgres' => ['PostgreSQL', '']
'postgres' => ['PostgreSQL', ''],
'admonition' => ["\n> **", "\n"],
},
'text' =>
@ -77,7 +78,8 @@ my $oRenderTag =
'exe' => [undef, ''],
'backrest' => [undef, ''],
'proper' => ['', ''],
'postgres' => ['PostgreSQL', '']
'postgres' => ['PostgreSQL', ''],
'admonition' => ["\n", "\n\n"],
},
'latex' =>
@ -108,7 +110,8 @@ my $oRenderTag =
# 'exe' => [undef, ''],
'backrest' => [undef, ''],
'proper' => ['\textnormal{\texttt{', '}}'],
'postgres' => ['PostgreSQL', '']
'postgres' => ['PostgreSQL', ''],
'admonition' => ["\n\\begin{leftbar}\n\\textit{\\textbf{", "}\n\\end{leftbar}\n"],
},
'html' =>
@ -136,7 +139,8 @@ my $oRenderTag =
'setting' => ['<span class="br-setting">', '</span>'], # ??? This will need to be fixed
'backrest' => [undef, ''],
'proper' => ['<span class="host">', '</span>'],
'postgres' => ['<span class="postgres">PostgreSQL</span>', '']
'postgres' => ['<span class="postgres">PostgreSQL</span>', ''],
'admonition' => ['<div class="admonition">', '</div>'],
}
};
@ -802,7 +806,15 @@ sub processTag
$strBuffer .= $strStart;
if ($strTag eq 'p' || $strTag eq 'title' || $strTag eq 'li' || $strTag eq 'code-block' || $strTag eq 'summary')
# Admonitions in the reference materials are tags of the text element rather than field elements of the document so special
# handling is required
if ($strTag eq 'admonition')
{
$strBuffer .= $self->processAdmonitionStart($oTag);
}
if ($strTag eq 'p' || $strTag eq 'title' || $strTag eq 'li' || $strTag eq 'code-block' || $strTag eq 'summary'
|| $strTag eq 'admonition')
{
$strBuffer .= $self->processText($oTag);
}
@ -818,6 +830,11 @@ sub processTag
}
}
if ($strTag eq 'admonition')
{
$strBuffer .= $self->processAdmonitionEnd($oTag);
}
$strBuffer .= $strStop;
}
@ -829,6 +846,88 @@ sub processTag
);
}
####################################################################################################################################
# processAdmonitionStart
####################################################################################################################################
sub processAdmonitionStart
{
my $self = shift;
# Assign function parameters, defaults, and log debug info
my
(
$strOperation,
$oTag
) =
logDebugParam
(
__PACKAGE__ . '->processAdmonitionStart', \@_,
{name => 'oTag', trace => true}
);
my $strType = $self->{strType};
my $strBuffer = '';
# Note that any changes to the way the HTML, markdown or latex display tags may also need to be made here
if ($strType eq 'html')
{
my $strType = $oTag->paramGet('type');
$strBuffer = '<div class="' . $strType . '">' . uc($strType) . ':</div>' .
'<div class="' . $strType . '-text">';
}
elsif ($strType eq 'text' || $strType eq 'markdown')
{
$strBuffer = uc($oTag->paramGet('type')) . ": ";
}
elsif ($strType eq 'latex')
{
$strBuffer = uc($oTag->paramGet('type')) . ": }";
}
# Return from function and log return values if any
return logDebugReturn
(
$strOperation,
{name => 'strBuffer', value => $strBuffer, trace => true}
);
}
####################################################################################################################################
# processAdmonitionEnd
####################################################################################################################################
sub processAdmonitionEnd
{
my $self = shift;
# Assign function parameters, defaults, and log debug info
my
(
$strOperation,
$oTag
) =
logDebugParam
(
__PACKAGE__ . '->processAdmonitionEnd', \@_,
{name => 'oTag', trace => true}
);
my $strType = $self->{strType};
my $strBuffer = '';
# Note that any changes to the way the HTML, markdown or latex display tags may also need to be made here
if ($strType eq 'html')
{
$strBuffer = '</div>';
}
# Return from function and log return values if any
return logDebugReturn
(
$strOperation,
{name => 'strBuffer', value => $strBuffer, trace => true}
);
}
####################################################################################################################################
# processText
####################################################################################################################################

8
doc/lib/BackRestDoc/Html/DocHtmlPage.pm
View File

@ -552,6 +552,14 @@ sub sectionProcess
$iSectionNo++;
}
# Add an admonition (e.g. NOTE, WARNING, etc)
elsif ($oChild->nameGet() eq 'admonition')
{
my $oAdmonition = $oSectionBodyElement->addNew(HTML_DIV, 'admonition');
$oAdmonition->addNew(HTML_DIV, $oChild->paramGet('type'), {strContent => uc($oChild->paramGet('type')) . ": "});
$oAdmonition->addNew(HTML_DIV, $oChild->paramGet('type') . '-text',
{strContent => $self->processText($oChild->textGet())});
}
# Check if the child can be processed by a parent
else
{

8
doc/lib/BackRestDoc/Latex/DocLatexSection.pm
View File

@ -399,6 +399,14 @@ sub sectionProcess
{
$strLatex .= "\n" . $self->sectionProcess($oChild, $strSection, $iDepth + 1);
}
# Add an admonition (e.g. NOTE, WARNING, etc)
elsif ($oChild->nameGet() eq 'admonition')
{
$strLatex .= "\n\\begin{leftbar}";
$strLatex .= "\n\\textit{\\textbf{" . uc($oChild->paramGet('type')) . ": }";
$strLatex .= $self->processText($oChild->textGet()) . "}";
$strLatex .= "\n\\end{leftbar}\n";
}
# Check if the child can be processed by a parent
else
{

5
doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm
View File

@ -430,6 +430,11 @@ sub sectionProcess
(($iRowCellIdx < @oRowCellList -1) ? " | " : " |\n");
}
}
}
# Add an admonition (e.g. NOTE, WARNING, etc)
elsif ($oChild->nameGet() eq 'admonition')
{
$strMarkdown .= "\n> **" . uc($oChild->paramGet('type')) . ":** " . $self->processText($oChild->textGet());
}
# Check if the child can be processed by a parent
else

22
doc/resource/html/default.css
View File

@ -482,6 +482,28 @@ li.list-unordered
margin-top: .5em;
}
/*******************************************************************************
Admonition
*******************************************************************************/
.admonition
{
padding-left: 20px;
font-style: italic;
margin: 10px 0px;
}
.admonition>.note, .admonition>.warning, .admonition>.caution, .admonition>.important, .admonition>.tip
{
font-weight: bold;
float: left;
padding-right: 10px;
}
.admonition>.note-text, .admonition>.warning-text, .admonition>.caution-text, .admonition>.important-text, .admonition>.tip-text
{
overflow: hidden;
}
/*******************************************************************************
Keywords
*******************************************************************************/

4
doc/resource/latex/preamble.tex
View File

@ -115,6 +115,10 @@
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
% Use framed package for admonition
% ----------------------------------------------------------------------------------------------------------------------------------
\usepackage{framed}
% ----------------------------------------------------------------------------------------------------------------------------------
% Begin document
% ----------------------------------------------------------------------------------------------------------------------------------

7
doc/xml/dtd/doc.dtd
View File

@ -118,7 +118,7 @@
<!ELEMENT section (title?,
((p|list|table|host-add|execute-list|backrest-config|postgres-config|cmd-description|
option-description|code-block|block|section)*))>
option-description|code-block|block|section|admonition)*))>
<!ATTLIST section id CDATA #REQUIRED>
<!ATTLIST section if CDATA "">
<!ATTLIST section depend CDATA "">
@ -222,13 +222,16 @@
br-setting|pg-option|pg-setting|link|user|proper)*>
<!-- Formatted elements -->
<!-- adminition type can be note, important, warning, caution and tip -->
<!ELEMENT admonition ANY>
<!ATTLIST admonition type CDATA #REQUIRED>
<!ELEMENT summary (#PCDATA|quote|b|i|ul|ol|id|code|code-block|host|file|path|cmd|setting|exe|backrest|postgres|br-option|
br-setting|pg-option|pg-setting|link|user|proper)*>
<!ELEMENT p (#PCDATA|quote|b|i|id|code|code-block|host|file|path|cmd|setting|exe|backrest|postgres|br-option|br-setting|
pg-option|pg-setting|link|user|proper)*>
<!ATTLIST p if CDATA "">
<!ELEMENT text (#PCDATA|quote|b|i|ul|ol|id|code|code-block|host|file|path|cmd|setting|exe|backrest|postgres|br-option|
br-setting|pg-option|pg-setting|link|user|proper)*>
br-setting|pg-option|pg-setting|link|user|proper|admonition)*>
<!ELEMENT i (#PCDATA)>
<!ELEMENT b (#PCDATA)>
<!ELEMENT ul (li+)>

33
doc/xml/reference.xml
View File

@ -10,9 +10,7 @@
<config-section-list title="Settings">
<!-- CONFIG - LOG -->
<config-section id="log" name="Log">
<text>The <setting>log</setting> section defines logging-related settings.
<b>IMPORTANT NOTE</b>: Trace-level logging may expose secrets such as keys and passwords. Use with caution!</text>
<text>The <setting>log</setting> section defines logging-related settings.<admonition type="caution">Trace-level logging may expose secrets such as keys and passwords. Use with caution!</admonition></text>
<!-- CONFIG - LOG SECTION - LOG-LEVEL-FILE KEY -->
<config-key-list>
@ -358,9 +356,7 @@
<config-key id="repo-retention-archive" name="Archive Retention">
<summary>Number of backups worth of continuous WAL to retain.</summary>
<text>Note that the WAL segments required to make a backup consistent are always retained until the backup is expired regardless of how this option is configured.
If this value is not set, then the archive to expire will default to the <setting>repo-retention-full</setting> (or <setting>repo-retention-diff</setting>) value corresponding to the <setting>repo-retention-archive-type</setting> if set to <setting>full</setting> (or <setting>diff</setting>). This will ensure that WAL is only expired for backups that are already expired.
<text><admonition type="note">WAL segments required to make a backup consistent are always retained until the backup is expired regardless of how this option is configured.</admonition>If this value is not set, then the archive to expire will default to the <setting>repo-retention-full</setting> (or <setting>repo-retention-diff</setting>) value corresponding to the <setting>repo-retention-archive-type</setting> if set to <setting>full</setting> (or <setting>diff</setting>). This will ensure that WAL is only expired for backups that are already expired.
This option must be set if <setting>repo-retention-archive-type</setting> is set to <setting>incr</setting>. If disk space is at a premium, then this setting, in conjunction with <setting>repo-retention-archive-type</setting>, can be used to aggressively expire WAL segments. However, doing so negates the ability to perform PITR from the backups with expired WAL and is therefore <b>not</b> recommended.</text>
@ -555,11 +551,7 @@
<b>Be careful using this feature -- it is very easy to exclude something critical that will make the backup inconsistent. Be sure to test your restores!</b>
All excluded files will be logged at <id>info</id> level along with the exclusion rule. Be sure to audit the list of excluded files to ensure nothing unexpected is being excluded.
Note that exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will be <i>removed</i> on delta restore.
This option should not be used to exclude <postgres/> logs from a backup. Logs can be moved out of the <id>PGDATA</id> directory using the <postgres/> <setting>log_directory</setting> setting, which has the benefit of allowing logs to be preserved after a restore.
All excluded files will be logged at <id>info</id> level along with the exclusion rule. Be sure to audit the list of excluded files to ensure nothing unexpected is being excluded.<admonition type="note">Exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will be <i>removed</i> on delta restore.</admonition>This option should not be used to exclude <postgres/> logs from a backup. Logs can be moved out of the <id>PGDATA</id> directory using the <postgres/> <setting>log_directory</setting> setting, which has the benefit of allowing logs to be preserved after a restore.
Multiple exclusions may be specified on the command-line or in a configuration file.</text>
@ -679,11 +671,7 @@
<config-key id="db-include" name="Include Database">
<summary>Restore only specified databases.</summary>
<text>This feature allows only selected databases to be restored. Databases not specifically included will be restored as sparse, zeroed files to save space but still allow <postgres/> to perform recovery. After recovery the databases that were not included will not be accessible but can be removed with the <id>drop database</id> command.
Note that built-in databases (<id>template0</id>, <id>template1</id>, and <id>postgres</id>) are always restored.
The <setting>{[dash]}-db-include</setting> option can be passed multiple times to specify more than one database to include.</text>
<text>This feature allows only selected databases to be restored. Databases not specifically included will be restored as sparse, zeroed files to save space but still allow <postgres/> to perform recovery. After recovery the databases that were not included will not be accessible but can be removed with the <id>drop database</id> command. <admonition type="note">built-in databases (<id>template0</id>, <id>template1</id>, and <id>postgres</id>) are always restored.</admonition>The <setting>{[dash]}-db-include</setting> option can be passed multiple times to specify more than one database to include.</text>
<example>db_main</example>
</config-key>
@ -710,11 +698,7 @@
<config-key id="recovery-option" name="Recovery Option">
<summary>Set an option in <file>recovery.conf</file>.</summary>
<text>See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on recovery.conf options (replace X.X with your <postgres/> version). This option can be used multiple times.
Note: The <setting>restore_command</setting> option will be automatically generated but can be overridden with this option. Be careful about specifying your own <setting>restore_command</setting> as <backrest/> is designed to handle this for you. Target Recovery options (recovery_target_name, recovery_target_time, etc.) are generated automatically by <backrest/> and should not be set with this option.
Since <backrest/> does not start <postgres/> after writing the <file>recovery.conf</file> file, it is always possible to edit/check <file>recovery.conf</file> before manually restarting.</text>
<text>See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on recovery.conf options (replace X.X with your <postgres/> version). This option can be used multiple times.<admonition type="note">The <setting>restore_command</setting> option will be automatically generated but can be overridden with this option. Be careful about specifying your own <setting>restore_command</setting> as <backrest/> is designed to handle this for you. Target Recovery options (recovery_target_name, recovery_target_time, etc.) are generated automatically by <backrest/> and should not be set with this option.</admonition>Since <backrest/> does not start <postgres/> after writing the <file>recovery.conf</file> file, it is always possible to edit/check <file>recovery.conf</file> before manually restarting.</text>
<example>primary_conninfo=db.mydomain.com</example>
</config-key>
@ -1262,9 +1246,7 @@
<option id="force" name="Force">
<summary>Force stanza creation.</summary>
<text><b>Caution</b>: Use <br-option>--force</br-option> only as a last resort, when all else fails. If data is missing from the repository then the recreated <file>.info</file> files will likely be corrupt.
If the required stanza <file>.info</file> files do not exist in the repository but backups or WAL segments do exist, then this option can be used to force the stanza to be created from the existing data in the repository. This is most likely to be useful after corruption or an incomplete restore of the repository from elsewhere.</text>
<text><admonition type="caution">Use <br-option>--force</br-option> only as a last resort, when all else fails. If data is missing from the repository then the recreated <file>.info</file> files will likely be corrupt.</admonition>If the required stanza <file>.info</file> files do not exist in the repository but backups or WAL segments do exist, then this option can be used to force the stanza to be created from the existing data in the repository. This is most likely to be useful after corruption or an incomplete restore of the repository from elsewhere.</text>
<example>n</example>
</option>
@ -1322,8 +1304,7 @@
<command id="stanza-delete" name="Stanza Delete">
<summary>Delete a stanza.</summary>
<text>The <cmd>stanza-delete</cmd> command removes data in the repository associated with a stanza. Use this command with caution &amp;mdash; it will permanently remove all backups and archives from the <backrest/> repository for the specified stanza.
<text>The <cmd>stanza-delete</cmd> command removes data in the repository associated with a stanza.<admonition type="warning">Use this command with caution &amp;mdash; it will permanently remove all backups and archives from the <backrest/> repository for the specified stanza.</admonition>
To delete a stanza:
<ul>
<li>Shut down the <postgres/> cluster associated with the stanza (or use --force to override).</li>

8
doc/xml/release.xml
View File

@ -243,6 +243,14 @@
</release-improvement-list>
<release-development-list>
<release-item>
<release-item-contributor-list>
<release-item-contributor id="cynthia.shang"/>
</release-item-contributor-list>
<p>Add <code>admonitions</code> to all documentation renderers (HTML, PDF, Markdown and help text) and update <file>xml</file> files accordingly.</p>
</release-item>
<release-item>
<release-item-contributor-list>
<release-item-contributor id="cynthia.shang"/>

6
doc/xml/test.xml
View File

@ -10,7 +10,7 @@
<p>A `Vagrantfile` is provided that contains the complete configuration required to run <backrest/> tests and build documentation. If Vagrant is not suitable then the `Vagrantfile` still contains the configuration steps required to build a test system.</p>
<p>Note that this is not required for normal operation of <backrest/>.</p>
<admonition type="note">this is not required for normal operation of <backrest/>.</admonition>
</section>
<section id="testing">
@ -50,13 +50,13 @@ vagrant ssh
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4
</code-block>
<p>Note that process-max is only applicable to the <id>synthetic</id> and <id>full</id> tests in the <id>backup</id> module.</p>
<admonition type="note">process-max is only applicable to the <id>synthetic</id> and <id>full</id> tests in the <id>backup</id> module.</admonition>
<code-block title="Run Tests for a Specific OS, Module, Test, Process Max, and Database Version">
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4 --pg-version=9.4
</code-block>
<p>Note that pg-version is only applicable to the <id>full</id> test in the <id>backup</id> module.</p>
<admonition type="note">pg-version is only applicable to the <id>full</id> test in the <id>backup</id> module.</admonition>
<code-block title="Iterate All Possible Test Combinations">
/backrest/test/test.pl --dry-run

16
doc/xml/user-guide.xml
View File

@ -838,7 +838,7 @@
<list-item>[global]</list-item>
</list>
<p><b>Note:</b> <br-option>--config</br-option>, <br-option>--config-include-path</br-option> and <br-option>--config-path</br-option> are command-line only options.</p>
<admonition type="note"><br-option>--config</br-option>, <br-option>--config-include-path</br-option> and <br-option>--config-path</br-option> are command-line only options.</admonition>
<p><backrest/> can also be configured using environment variables as described in the <link url="command.html">command reference</link>.</p>
@ -1261,7 +1261,7 @@
<p>Although useful this feature may not be appropriate when another third-party backup solution is being used to take online backups as <backrest/> will not recognize that the other software is running and may terminate a backup started by that software. However, it would be unusual to run more than one third-party backup solution at the same time so this is not likely to be a problem.</p>
<p>Note that <id>pg_dump</id> and <id>pg_basebackup</id> do not take online backups so are not affected. It is safe to run them in conjunction with <backrest/>.</p>
<admonition type="note"><id>pg_dump</id> and <id>pg_basebackup</id> do not take online backups so are not affected. It is safe to run them in conjunction with <backrest/>.</admonition>
</section>
<!-- SECTION => BACKUP - ARCHIVE-TIMEOUT -->
@ -1373,7 +1373,7 @@
</execute>
</execute-list>
<p>Note that this syntax requires <proper>jq v1.5</proper>.</p>
<admonition type="note">This syntax requires <proper>jq v1.5</proper>.</admonition>
</section>
</section>
@ -1998,7 +1998,7 @@
<backrest-config-option section="global" key="process-max">4</backrest-config-option>
</backrest-config>
<p>Note that the region and endpoint will need to be configured to where the bucket is located. The values given here are for the <id>us-east-1</id> region.</p>
<admonition type="note">The region and endpoint will need to be configured to where the bucket is located. The values given here are for the <id>us-east-1</id> region.</admonition>
<p>A role should be created to run <backrest/> and the bucket permissions should be set as restrictively as possible. This sample policy will restrict all reads and writes to the bucket and repository path.</p>
@ -2191,7 +2191,7 @@
<block-variable-replace key="setup-ssh-user-home-path">{[pg-home-path]}</block-variable-replace>
</block>
<p>Note that ssh has been configured to only allow <backrest/> to be run via passwordless ssh. This enhances security in the event that one of the service accounts is hijacked.</p>
<admonition type="note">ssh has been configured to only allow <backrest/> to be run via passwordless ssh. This enhances security in the event that one of the service accounts is hijacked.</admonition>
<!-- <block if="{[pg-version]} >= 11" id="setup-ssh">
<block-variable-replace key="setup-ssh-host">{[host-pg1]}</block-variable-replace>
@ -2581,7 +2581,7 @@
</execute>
</execute-list>
<p>Note that the <pg-setting>standby_mode</pg-setting> setting has been written into the <file>recovery.conf</file> file. Configuring recovery settings in <backrest/> means that the <file>recovery.conf</file> file does not need to be stored elsewhere since it will be properly recreated with each restore. The <br-setting>--type=preserve</br-setting> option can be used with the <cmd>restore</cmd> to leave the existing <file>recovery.conf</file> file in place if that behavior is preferred.</p>
<admonition type="note">The <pg-setting>standby_mode</pg-setting> setting has been written into the <file>recovery.conf</file> file. Configuring recovery settings in <backrest/> means that the <file>recovery.conf</file> file does not need to be stored elsewhere since it will be properly recreated with each restore. The <br-setting>--type=preserve</br-setting> option can be used with the <cmd>restore</cmd> to leave the existing <file>recovery.conf</file> file in place if that behavior is preferred.</admonition>
<p>The <pg-setting>hot_standby</pg-setting> setting must be enabled before starting <postgres/> to allow read-only connections on <host>{[host-pg2]}</host>. Otherwise, connection attempts will be refused. The rest of the configuration is in case the standby is promoted to a primary.</p>
@ -2887,7 +2887,7 @@
<backrest-config-option section="global:archive-get" key="process-max">2</backrest-config-option>
</backrest-config>
<p>Note that <br-option>process-max</br-option> is configured using command sections so that the option is not used by backup and restore. This also allows different values for <cmd>archive-push</cmd> and <cmd>archive-get</cmd>.</p>
<admonition type="note"><br-option>process-max</br-option> is configured using command sections so that the option is not used by backup and restore. This also allows different values for <cmd>archive-push</cmd> and <cmd>archive-get</cmd>.</admonition>
<p>For demonstration purposes streaming replication will be broken to force <postgres/> to get WAL using the <pg-option>restore_command</pg-option>.</p>
@ -2916,7 +2916,7 @@
<p>The spool path holds the current status of WAL archiving. Status files written into the spool directory are typically zero length and should consume a minimal amount of space (a few MB at most) and very little IO. All the information in this directory can be recreated so it is not necessary to preserve the spool directory if the cluster is moved to new hardware.</p>
<p><b>NOTE:</b> In the original implementation of asynchronous archiving, WAL segments were copied to the spool directory before compression and transfer. The new implementation copies WAL directly from the <path>pg_xlog</path> directory. If asynchronous archiving was utilized in <proper>v1.12</proper> or prior, read the <proper>v1.13</proper> release notes carefully before upgrading.</p>
<admonition type="important">In the original implementation of asynchronous archiving, WAL segments were copied to the spool directory before compression and transfer. The new implementation copies WAL directly from the <path>pg_xlog</path> directory. If asynchronous archiving was utilized in <proper>v1.12</proper> or prior, read the <proper>v1.13</proper> release notes carefully before upgrading.</admonition>
<p>The <file>[stanza]-archive-push-async.log</file> file can be used to monitor the activity of the asynchronous process. A good way to test this is to quickly push a number of WAL segments.</p>

25
src/config/define.auto.c
View File

@ -145,8 +145,10 @@ static ConfigDefineCommandData configDefineCommandData[] = CFGDEFDATA_COMMAND_LI
CFGDEFDATA_COMMAND_HELP_SUMMARY("Delete a stanza.")
CFGDEFDATA_COMMAND_HELP_DESCRIPTION
(
"The stanza-delete command removes data in the repository associated with a stanza. Use this command with caution -- "
"it will permanently remove all backups and archives from the pgBackRest repository for the specified stanza.\n"
"The stanza-delete command removes data in the repository associated with a stanza.\n"
"WARNING: Use this command with caution -- it will permanently remove all backups and archives from the pgBackRest "
"repository for the specified stanza.\n"
"\n"
"\n"
"To delete a stanza:\n"
"\n"
@ -914,9 +916,8 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
(
"This feature allows only selected databases to be restored. Databases not specifically included will be restored as "
"sparse, zeroed files to save space but still allow PostgreSQL to perform recovery. After recovery the databases "
"that were not included will not be accessible but can be removed with the drop database command.\n"
"\n"
"Note that built-in databases (template0, template1, and postgres) are always restored.\n"
"that were not included will not be accessible but can be removed with the drop database command. \n"
"NOTE: built-in databases (template0, template1, and postgres) are always restored.\n"
"\n"
"The --db-include option can be passed multiple times to specify more than one database to include."
)
@ -1030,9 +1031,8 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
"\n"
"All excluded files will be logged at info level along with the exclusion rule. Be sure to audit the list of excluded "
"files to ensure nothing unexpected is being excluded.\n"
"\n"
"Note that exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will "
"be removed on delta restore.\n"
"NOTE: Exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will be "
"removed on delta restore.\n"
"\n"
"This option should not be used to exclude PostgreSQL logs from a backup. Logs can be moved out of the PGDATA "
"directory using the PostgreSQL log_directory setting, which has the benefit of allowing logs to be preserved "
@ -1119,7 +1119,7 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
CFGDEFDATA_OPTION_OPTIONAL_HELP_SUMMARY("Force stanza creation.")
CFGDEFDATA_OPTION_OPTIONAL_HELP_DESCRIPTION
(
"Caution: Use --force only as a last resort, when all else fails. If data is missing from the repository then "
"CAUTION: Use --force only as a last resort, when all else fails. If data is missing from the repository then "
"the recreated .info files will likely be corrupt.\n"
"\n"
"If the required stanza .info files do not exist in the repository but backups or WAL segments do exist, then "
@ -2433,8 +2433,7 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
(
"See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on recovery.conf options (replace X.X "
"with your PostgreSQL version). This option can be used multiple times.\n"
"\n"
"Note: The restore_command option will be automatically generated but can be overridden with this option. Be careful "
"NOTE: The restore_command option will be automatically generated but can be overridden with this option. Be careful "
"about specifying your own restore_command as pgBackRest is designed to handle this for you. Target Recovery "
"options (recovery_target_name, recovery_target_time, etc.) are generated automatically by pgBackRest and should "
"not be set with this option.\n"
@ -2987,8 +2986,8 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
CFGDEFDATA_OPTION_HELP_SUMMARY("Number of backups worth of continuous WAL to retain.")
CFGDEFDATA_OPTION_HELP_DESCRIPTION
(
"Note that the WAL segments required to make a backup consistent are always retained until the backup is expired "
"regardless of how this option is configured.\n"
"NOTE: WAL segments required to make a backup consistent are always retained until the backup is expired regardless of "
"how this option is configured.\n"
"\n"
"If this value is not set, then the archive to expire will default to the repo-retention-full (or repo-retention-diff) "
"value corresponding to the repo-retention-archive-type if set to full (or diff). This will ensure that WAL is "

7
test/README.md
View File

@ -5,8 +5,7 @@
pgBackRest uses Docker to run tests and generate documentation. Docker's light-weight virualization provides the a good balance between proper OS emulation and performance (especially startup)
A `Vagrantfile` is provided that contains the complete configuration required to run pgBackRest tests and build documentation. If Vagrant is not suitable then the `Vagrantfile` still contains the configuration steps required to build a test system.
Note that this is not required for normal operation of pgBackRest.
> **NOTE:** this is not required for normal operation of pgBackRest.
## Testing
@ -44,13 +43,13 @@ _Run Tests for a Specific OS, Module, Test, and Process Max_:
```
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4
```
Note that process-max is only applicable to the `synthetic` and `full` tests in the `backup` module.
> **NOTE:** process-max is only applicable to the `synthetic` and `full` tests in the `backup` module.
_Run Tests for a Specific OS, Module, Test, Process Max, and Database Version_:
```
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4 --pg-version=9.4
```
Note that pg-version is only applicable to the `full` test in the `backup` module.
> **NOTE:** pg-version is only applicable to the `full` test in the `backup` module.
_Iterate All Possible Test Combinations_:
```

33
test/src/module/help/helpTest.c
View File

@ -332,6 +332,39 @@ testRun(void)
TEST_RESULT_VOID(
configParse(strLstSize(argList), strLstPtr(argList), false), "help for backup command, repo-hardlink option");
TEST_RESULT_STR(strPtr(helpRender()), optionHelp, " check text");
// Check admonition
// -------------------------------------------------------------------------------------------------------------------------
optionHelp = strPtr(strNewFmt(
"%s - 'backup' command - 'repo-retention-archive' option help\n"
"\n"
"Number of backups worth of continuous WAL to retain.\n"
"\n"
"NOTE: WAL segments required to make a backup consistent are always retained\n"
"until the backup is expired regardless of how this option is configured.\n"
"\n"
"If this value is not set, then the archive to expire will default to the\n"
"repo-retention-full (or repo-retention-diff) value corresponding to the\n"
"repo-retention-archive-type if set to full (or diff). This will ensure that WAL\n"
"is only expired for backups that are already expired.\n"
"\n"
"This option must be set if repo-retention-archive-type is set to incr. If disk\n"
"space is at a premium, then this setting, in conjunction with\n"
"repo-retention-archive-type, can be used to aggressively expire WAL segments.\n"
"However, doing so negates the ability to perform PITR from the backups with\n"
"expired WAL and is therefore not recommended.\n"
"\n"
"deprecated name: retention-archive\n",
helpVersion));
argList = strLstNew();
strLstAddZ(argList, "/path/to/pgbackrest");
strLstAddZ(argList, "help");
strLstAddZ(argList, "backup");
strLstAddZ(argList, "repo-retention-archive");
TEST_RESULT_VOID(
configParse(strLstSize(argList), strLstPtr(argList), false), "help for backup command, repo-retention-archive option");
TEST_RESULT_STR(strPtr(helpRender()), optionHelp, " check admonition text");
}
// *****************************************************************************************************************************