You've already forked pgbackrest
mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2025-06-14 23:44:58 +02:00
Rename master to primary in documentation to align with PostgreSQL convention.
This commit is contained in:
David Steele
@ -193,7 +193,7 @@
|
||||
<config-key id="protocol-timeout" name="Protocol Timeout">
|
||||
<summary>Protocol timeout.</summary>
|
||||
|
||||
<text>Sets the timeout, in seconds, that the master or remote process will wait for a new message to be received on the protocol layer. This prevents processes from waiting indefinitely for a message. The <br-option>protocol-timeout</br-option> option must be greater than the <br-option>db-timeout</br-option> option.</text>
|
||||
<text>Sets the timeout, in seconds, that the local or remote process will wait for a new message to be received on the protocol layer. This prevents processes from waiting indefinitely for a message. The <br-option>protocol-timeout</br-option> option must be greater than the <br-option>db-timeout</br-option> option.</text>
|
||||
|
||||
<example>630</example>
|
||||
</config-key>
|
||||
@ -392,7 +392,7 @@
|
||||
<config-key id="backup-standby" name="Backup from Standby">
|
||||
<summary>Backup from the standby cluster.</summary>
|
||||
|
||||
<text>Enable backup from standby to reduce load on the master cluster. This option requires that both the <host>master</host> and <host>standby</host> hosts be configured.</text>
|
||||
<text>Enable backup from standby to reduce load on the primary cluster. This option requires that both the <host>primary</host> and <host>standby</host> hosts be configured.</text>
|
||||
|
||||
<example>y</example>
|
||||
</config-key>
|
||||
|
||||
@ -22,6 +22,14 @@
|
||||
</release-item>
|
||||
</release-feature-list>
|
||||
</release-core-list>
|
||||
|
||||
<release-doc-list>
|
||||
<release-refactor-list>
|
||||
<release-item>
|
||||
<p>Rename <proper>master</proper> to <proper>primary</proper> in documentation to align with <postgres/> convention.</p>
|
||||
</release-item>
|
||||
</release-refactor-list>
|
||||
</release-doc-list>
|
||||
</release>
|
||||
|
||||
<release date="2017-09-03" version="1.23" title="Multiple Standbys and PostgreSQL 10 Support">
|
||||
@ -423,7 +431,7 @@
|
||||
<release-item-contributor id="shang.cynthia"/>
|
||||
</release-item-contributor-list>
|
||||
|
||||
<p>Fixed the <cmd>backup</cmd> command so the <br-setting>backup-standby</br-setting> option is reset (and the backup proceeds on the master) if the standby is not configured and/or reachable.</p>
|
||||
<p>Fixed the <cmd>backup</cmd> command so the <br-setting>backup-standby</br-setting> option is reset (and the backup proceeds on the primary) if the standby is not configured and/or reachable.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
@ -1153,7 +1161,7 @@
|
||||
<release-item-contributor id="shang.cynthia"/>
|
||||
</release-item-contributor-list>
|
||||
|
||||
<p>Abstracted code to determine which database cluster is the master and which are standbys.</p>
|
||||
<p>Abstracted code to determine which database cluster is the primary and which are standbys.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
@ -1569,7 +1577,7 @@
|
||||
<release-core-list>
|
||||
<release-bug-list>
|
||||
<release-item>
|
||||
<p>Fixed an issue where tablespaces were copied from the master during standby backup.</p>
|
||||
<p>Fixed an issue where tablespaces were copied from the primary during standby backup.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
@ -1595,7 +1603,7 @@
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
<p>Exclude contents of <path>$PGDATA/pg_replslot</path> directory so that replication slots on the master do not become part of the backup.</p>
|
||||
<p>Exclude contents of <path>$PGDATA/pg_replslot</path> directory so that replication slots on the primary do not become part of the backup.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
@ -1701,11 +1709,11 @@
|
||||
|
||||
<release-feature-list>
|
||||
<release-item>
|
||||
<p>Backup from a standby cluster. A connection to the primary cluster is still required to start/stop the backup and copy files that are not replicated, but the vast majority of files are copied from the standby in order to reduce load on the master.</p>
|
||||
<p>Backup from a standby cluster. A connection to the primary cluster is still required to start/stop the backup and copy files that are not replicated, but the vast majority of files are copied from the standby in order to reduce load on the primary.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
<p>More flexible configuration for databases. Master and standby can both be configured on the backup server and <backrest/> will automatically determine which is the master. This means no configuration changes for backup are required after failing over from a master to standby when a separate backup server is used.</p>
|
||||
<p>More flexible configuration for databases. Master and standby can both be configured on the backup server and <backrest/> will automatically determine which is the primary. This means no configuration changes for backup are required after failing over from a primary to standby when a separate backup server is used.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
|
||||
@ -76,14 +76,14 @@
|
||||
|
||||
<variable key="host-s3-server">s3-server</variable>
|
||||
|
||||
<variable key="host-db-master">db-master</variable>
|
||||
<variable key="host-db-master-user">{[host-user]}</variable>
|
||||
<variable key="host-db-master-image">{[image-repo]}:{[host-os]}-doc-db</variable>
|
||||
<variable key="host-db-master-mount">{[host-mount]}</variable>
|
||||
<variable key="host-db-primary">db-primary</variable>
|
||||
<variable key="host-db-primary-user">{[host-user]}</variable>
|
||||
<variable key="host-db-primary-image">{[image-repo]}:{[host-os]}-doc-db</variable>
|
||||
<variable key="host-db-primary-mount">{[host-mount]}</variable>
|
||||
|
||||
<variable key="host-db-standby">db-standby</variable>
|
||||
<variable key="host-db-standby-user">{[host-db-master-user]}</variable>
|
||||
<variable key="host-db-standby-image">{[host-db-master-image]}</variable>
|
||||
<variable key="host-db-standby-user">{[host-db-primary-user]}</variable>
|
||||
<variable key="host-db-standby-image">{[host-db-primary-image]}</variable>
|
||||
<variable key="host-db-standby-mount">{[host-mount]}</variable>
|
||||
|
||||
<variable key="host-backup">backup</variable>
|
||||
@ -185,7 +185,7 @@
|
||||
<host-add name="{[host-s3-server]}" user="root" image="{[image-repo]}:{[host-os]}-s3-server" os="{[host-os]}">
|
||||
</host-add>
|
||||
|
||||
<host-add name="{[host-db-master]}" user="{[host-db-master-user]}" image="{[host-db-master-image]}" os="{[host-os]}" mount="{[host-db-master-mount]}">
|
||||
<host-add name="{[host-db-primary]}" user="{[host-db-primary-user]}" image="{[host-db-primary-image]}" os="{[host-os]}" mount="{[host-db-primary-mount]}">
|
||||
<execute user="root">
|
||||
<exe-cmd>mkdir /root/pgbackrest-release-{[version]}</exe-cmd>
|
||||
</execute>
|
||||
@ -208,7 +208,7 @@
|
||||
|
||||
<p keyword="default"><backrest/> is written in Perl which is included with {[user-guide-os]} by default. The <id>DBD::Pg</id> module must also be installed.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}" keyword="default">
|
||||
<execute-list host="{[host-db-primary]}" keyword="default">
|
||||
<title>Install the <id>DBD::Pg</id> module</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -219,7 +219,7 @@
|
||||
|
||||
<p keyword="co6"><backrest/> is written in Perl which is not included with {[user-guide-os]} by default, however all required modules are available as standard packages.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}" keyword="co6">
|
||||
<execute-list host="{[host-db-primary]}" keyword="co6">
|
||||
<title>Install required Perl packages</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -233,7 +233,7 @@
|
||||
|
||||
<p keyword="co6">{[user-guide-os]} packages for <backrest/> are available from <link url="{[crunchy-url-base]}">Crunchy Data</link> or <link url="http://yum.postgresql.org">yum.postgresql.org</link>, but it is also easy to download the source and install manually.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Download version <id>{[version]}</id> of <backrest/></title>
|
||||
|
||||
<execute user="root" skip="y">
|
||||
@ -245,7 +245,7 @@
|
||||
|
||||
<p>If <backrest/> has been installed before it's best to be sure that no prior copies of it are still installed. Depending on how old the version of pgBackRest is it may have been installed in a few different locations. The following commands will remove all prior versions of pgBackRest.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Remove prior <backrest/> installations</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -270,7 +270,7 @@
|
||||
|
||||
<p>The new version can now be installed.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Install <backrest/></title>
|
||||
|
||||
<execute user="root">
|
||||
@ -309,7 +309,7 @@
|
||||
<!-- LibC installation - disabled for better testing of the C/Perl failback mechanism -->
|
||||
<!-- <p><backrest/> includes an optional companion C library that enhances performance and enables the `checksum-page` option. Pre-built packages are generally a better option than building the C library manually but the steps required are given below for completeness. Depending on the distribution a number of packages may be required which will not be enumerated here.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Build and Install C Library</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -326,7 +326,7 @@
|
||||
|
||||
<p><backrest/> should now be properly installed but it is best to check. If any dependencies were missed then you will get an error when running <backrest/> from the command line.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Make sure the installation worked</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -347,7 +347,7 @@
|
||||
|
||||
<p>Creating the demo cluster is optional but is strongly recommended, especially for new users, since the example commands in the user guide reference the demo cluster; the examples assume the demo cluster is running on the default port (i.e. 5432). The cluster will not be started until a later section because there is still some configuration to do.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create the demo cluster</title>
|
||||
|
||||
<execute keyword="default" user="postgres">
|
||||
@ -362,7 +362,7 @@
|
||||
|
||||
<p>By default <postgres/> will only accept local connections. The examples in this guide will require connections from other servers so <pg-option>listen_addresses</pg-option> is configured to listen on all interfaces. This may not be appropriate for secure installations.</p>
|
||||
|
||||
<postgres-config host="{[host-db-master]}" file="{[postgres-config-demo]}">
|
||||
<postgres-config host="{[host-db-primary]}" file="{[postgres-config-demo]}">
|
||||
<title>Set <pg-option>listen_addresses</pg-option></title>
|
||||
|
||||
<postgres-config-option key="listen_addresses">'*'</postgres-config-option>
|
||||
@ -370,7 +370,7 @@
|
||||
|
||||
<p>For demonstration purposes the <pg-option>log_line_prefix</pg-option> setting will be minimally configured. This keeps the log output as brief as possible to better illustrate important information.</p>
|
||||
|
||||
<postgres-config host="{[host-db-master]}" file="{[postgres-config-demo]}">
|
||||
<postgres-config host="{[host-db-primary]}" file="{[postgres-config-demo]}">
|
||||
<title>Set <pg-option>log_line_prefix</pg-option></title>
|
||||
|
||||
<postgres-config-option key="log_line_prefix">''</postgres-config-option>
|
||||
@ -378,7 +378,7 @@
|
||||
|
||||
<p keyword="co6">By default {[user-guide-os]} includes the day of the week in the log filename. This makes automating the user guide a bit more complicated so the <pg-option>log_filename</pg-option> is set to a constant.</p>
|
||||
|
||||
<postgres-config host="{[host-db-master]}" keyword="co6" file="{[postgres-config-demo]}">
|
||||
<postgres-config host="{[host-db-primary]}" keyword="co6" file="{[postgres-config-demo]}">
|
||||
<title>Set <pg-option>log_filename</pg-option></title>
|
||||
|
||||
<postgres-config-option key="log_filename">'postgresql.log'</postgres-config-option>
|
||||
@ -399,7 +399,7 @@
|
||||
|
||||
<p>When creating the <file>{[backrest-config-demo]}</file> file, the database owner (usually <id>postgres</id>) must be granted read privileges.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure the <postgres/> cluster data directory</title>
|
||||
|
||||
<backrest-config-option section="demo" key="db-path">{[db-path]}</backrest-config-option>
|
||||
@ -419,7 +419,7 @@
|
||||
|
||||
<p>For this demonstration the repository will be stored on the same host as the <postgres/> server. This is the simplest configuration and is useful in cases where traditional backup software is employed to backup the database host.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create the <backrest/> repository</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -435,7 +435,7 @@
|
||||
|
||||
<p>The repository path must be configured so <backrest/> knows where to find it.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure the <backrest/> repository path</title>
|
||||
|
||||
<backrest-config-option section="global" key="repo-path">{[backrest-repo-path]}</backrest-config-option>
|
||||
@ -448,7 +448,7 @@
|
||||
|
||||
<p>Backing up a running <postgres/> cluster requires WAL archiving to be enabled. Note that <i>at least</i> one WAL segment will be created during the backup process even if no explicit writes are made to the cluster.</p>
|
||||
|
||||
<postgres-config host="{[host-db-master]}" file="{[postgres-config-demo]}">
|
||||
<postgres-config host="{[host-db-primary]}" file="{[postgres-config-demo]}">
|
||||
<title>Configure archive settings</title>
|
||||
|
||||
<postgres-config-option key="archive_command">'{[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} archive-push %p'</postgres-config-option>
|
||||
@ -457,11 +457,11 @@
|
||||
<postgres-config-option key="max_wal_senders">3</postgres-config-option>
|
||||
</postgres-config>
|
||||
|
||||
<p>The <pg-option>wal_level</pg-option> setting must be set to <pg-setting>archive</pg-setting> at a minimum but <pg-setting>hot_standby</pg-setting> and <pg-setting>logical</pg-setting> also work fine for backups. Setting <pg-option>wal_level</pg-option> to <pg-setting>hot_standy</pg-setting> and increasing <pg-option>max_wal_senders</pg-option> is a good idea even if you do not currently run a hot standby as this will allow them to be added later without restarting the master cluster.</p>
|
||||
<p>The <pg-option>wal_level</pg-option> setting must be set to <pg-setting>archive</pg-setting> at a minimum but <pg-setting>hot_standby</pg-setting> and <pg-setting>logical</pg-setting> also work fine for backups. Setting <pg-option>wal_level</pg-option> to <pg-setting>hot_standy</pg-setting> and increasing <pg-option>max_wal_senders</pg-option> is a good idea even if you do not currently run a hot standby as this will allow them to be added later without restarting the primary cluster.</p>
|
||||
|
||||
<p>The <postgres/> cluster must be restarted after making these changes and before performing a backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Restart the {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -482,7 +482,7 @@
|
||||
|
||||
<p><backrest/> expires backups based on retention options.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure retention to 2 full backups</title>
|
||||
|
||||
<backrest-config-option section="global" key="retention-full">2</backrest-config-option>
|
||||
@ -497,7 +497,7 @@
|
||||
|
||||
<p>The <cmd>stanza-create</cmd> command must be run on the host where the repository is located to initialize the stanza. It is recommended that the <cmd>check</cmd> command be run after <cmd>stanza-create</cmd> to ensure archiving and backups are properly configured.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create the stanza and check the configuration</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -512,7 +512,7 @@
|
||||
<title>Check the Configuration</title>
|
||||
<cmd-description key="check"/>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Check the configuration</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -522,7 +522,7 @@
|
||||
</execute-list>
|
||||
|
||||
<!-- Decided not to show the error in this part of the user guide but added as a debug statement for reference. -->
|
||||
<execute-list keyword="debug" host="{[host-db-master]}">
|
||||
<execute-list keyword="debug" host="{[host-db-primary]}">
|
||||
<title>Example of an invalid configuration</title>
|
||||
|
||||
<execute output="y" err-expect="82">
|
||||
@ -538,7 +538,7 @@
|
||||
|
||||
<p>To perform a backup of the <postgres/> cluster run <backrest/> with the <cmd>backup</cmd> command.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Backup the {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -556,7 +556,7 @@
|
||||
|
||||
<p>The <br-option>type</br-option> option can be used to specify a full or differential backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Differential backup of the {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -594,7 +594,7 @@
|
||||
|
||||
<p>Use the <cmd>info</cmd> command to get information about backups.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Get info for the {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute filter="n" output="y">
|
||||
@ -622,7 +622,7 @@
|
||||
|
||||
<p>Backups can protect you from a number of disaster scenarios, the most common of which are hardware failure and data corruption. The easiest way to simulate data corruption is to remove an important <postgres/> cluster file.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop the {[postgres-cluster-demo]} cluster and delete the <file>pg_control</file> file</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -636,7 +636,7 @@
|
||||
|
||||
<p>Starting the cluster without this important file will result in an error.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Attempt to start the corrupted {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute keyword="default" user="root" output="y" err-expect="1">
|
||||
@ -665,7 +665,7 @@
|
||||
|
||||
<p>To restore a backup of the <postgres/> cluster run <backrest/> with the <cmd>restore</cmd> command. The cluster needs to be stopped (in this case it is already stopped) and all files must be removed from the <postgres/> data directory.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Remove old files from {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute>
|
||||
@ -673,7 +673,7 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Restore the {[postgres-cluster-demo]} cluster and start <postgres/></title>
|
||||
|
||||
<execute>
|
||||
@ -707,7 +707,7 @@
|
||||
|
||||
<p>By default <backrest/> will wait for the next regularly scheduled checkpoint before starting a backup. Depending on the <pg-option>checkpoint_timeout</pg-option> and <pg-option>checkpoint_segments</pg-option> settings in <postgres/> it may be quite some time before a checkpoint completes and the backup can begin.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Incremental backup of the {[postgres-cluster-demo]} cluster with the regularly scheduled checkpoint</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -719,13 +719,13 @@
|
||||
|
||||
<p>When <br-setting>{[dash]}-start-fast</br-setting> is passed on the command-line or <br-setting>start-fast=y</br-setting> is set in <file>{[backrest-config-demo]}</file> an immediate checkpoint is requested and the backup will start more quickly. This is convenient for testing and for ad-hoc backups. For instance, if a backup is being taken at the beginning of a release window it makes no sense to wait for a checkpoint. Since regularly scheduled backups generally only happen once per day it is unlikely that enabling the <br-option>start-fast</br-option> in <file>{[backrest-config-demo]}</file> will negatively affect performance, however for high-volume transactional systems you may want to pass <br-setting>{[dash]}-start-fast</br-setting> on the command-line instead. Alternately, it is possible to override the setting in the configuration file by passing <br-setting>{[dash]}-no-start-fast</br-setting> on the command-line.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Enable the <br-option>start-fast</br-option> option</title>
|
||||
|
||||
<backrest-config-option section="global" key="start-fast">y</backrest-config-option>
|
||||
</backrest-config>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Incremental backup of the {[postgres-cluster-demo]} cluster with an immediate checkpoint</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -744,7 +744,7 @@
|
||||
|
||||
<p>Here an error is intentionally caused by removing repository permissions.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Revoke write privileges in the <backrest/> repository and attempt a backup</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -760,7 +760,7 @@
|
||||
|
||||
<p>Even when the permissions are fixed <backrest/> will still be unable to perform a backup because the <postgres/> cluster is stuck in backup mode.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Restore write privileges in the <backrest/> repository and attempt a backup</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -776,7 +776,7 @@
|
||||
|
||||
<p>Enabling the <br-option>stop-auto</br-option> option allows <backrest/> to stop the current backup if it detects that no other <backrest/> backup process is running.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Enable the <br-option>stop-auto</br-option> option</title>
|
||||
|
||||
<backrest-config-option section="global" key="stop-auto">y</backrest-config-option>
|
||||
@ -784,7 +784,7 @@
|
||||
|
||||
<p>Now <backrest/> will stop the old backup and start a new one so the process completes successfully.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform an incremental backup</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -819,7 +819,7 @@
|
||||
|
||||
<p>Set <br-option>retention-full</br-option> to the number of full backups required. New backups must be completed before expiration will occur &mdash; that means if <br-setting>retention-full=2</br-setting> then there will be three full backups stored before the oldest one is expired.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure <br-option>retention-full</br-option></title>
|
||||
|
||||
<backrest-config-option section="global" key="retention-full">2</backrest-config-option>
|
||||
@ -827,7 +827,7 @@
|
||||
|
||||
<p>Backup <br-setting>retention-full=2</br-setting> but currently there is only one full backup so the next full backup to run will not expire any full backups.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform a full backup</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -843,7 +843,7 @@
|
||||
|
||||
<p>Archive <i>is</i> expired because WAL segments were generated before the oldest backup. These are not useful for recovery &mdash; only WAL segments generated after a backup can be used to recover that backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform a full backup</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -862,7 +862,7 @@
|
||||
|
||||
<p>Set <br-option>retention-diff</br-option> to the number of differential backups required. Differentials only rely on the prior full backup so it is possible to create a <quote>rolling</quote> set of differentials for the last day or more. This allows quick restores to recent points-in-time but reduces overall space consumption.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure <br-option>retention-diff</br-option></title>
|
||||
|
||||
<backrest-config-option section="global" key="retention-diff">1</backrest-config-option>
|
||||
@ -870,7 +870,7 @@
|
||||
|
||||
<p>Backup <br-setting>retention-diff=1</br-setting> so two differentials will need to be performed before one is expired. An incremental backup is added to demonstrate incremental expiration. Incremental backups cannot be expired independently &mdash; they are always expired with their related full or differential backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform differential and incremental backups</title>
|
||||
|
||||
<execute>
|
||||
@ -888,7 +888,7 @@
|
||||
|
||||
<p>Now performing a differential backup will expire the previous differential and incremental backups leaving only one differential backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform a differential backup</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -907,13 +907,13 @@
|
||||
|
||||
<p>Expiring archive will never remove WAL segments that are required to make a backup consistent. However, since Point-in-Time-Recovery (PITR) only works on a continuous WAL stream, care should be taken when aggressively expiring archive outside of the normal backup expiration process.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure <br-option>retention-diff</br-option></title>
|
||||
|
||||
<backrest-config-option section="global" key="retention-diff">2</backrest-config-option>
|
||||
</backrest-config>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform differential backup</title>
|
||||
|
||||
<execute show="n" variable-key="backup-diff-first">
|
||||
@ -938,7 +938,7 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Expire archive</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -966,7 +966,7 @@
|
||||
|
||||
<p><link section="/quickstart/perform-restore">Restore a Backup</link> in <link section="/quickstart">Quick Start</link> required the database cluster directory to be cleaned before the <cmd>restore</cmd> could be performed. The <br-option>delta</br-option> option allows <backrest/> to automatically determine which files in the database cluster directory can be preserved and which ones need to be restored from the backup &mdash; it also <i>removes</i> files not present in the backup manifest so it will dispose of divergent changes. This is accomplished by calculating a <link url="https://en.wikipedia.org/wiki/SHA-1">SHA-1</link> cryptographic hash for each file in the database cluster directory. If the <id>SHA-1</id> hash does not match the hash stored in the backup then that file will be restored. This operation is very efficient when combined with the <br-option>process-max</br-option> option. Since the <postgres/> server is shut down during the restore, a larger number of processes can be used than might be desirable during a backup when the <postgres/> server is running.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop the {[postgres-cluster-demo]} cluster, perform delta restore</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -980,7 +980,7 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Restart <postgres/></title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1001,7 +1001,7 @@
|
||||
|
||||
<p>To demonstrate this feature two databases are created: test1 and test2. A fresh backup is run so <backrest/> is aware of the new databases.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create two test databases and perform a backup</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1023,7 +1023,7 @@
|
||||
|
||||
<p>Each test database will be seeded with tables and data to demonstrate that recovery works with selective restore.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create a test table in each database</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1043,7 +1043,7 @@
|
||||
|
||||
<p>One of the main reasons to use selective restore is to save space. The size of the test1 database is shown here so it can be compared with the disk utilization after a selective restore.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Show space used by test1 database</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1055,7 +1055,7 @@
|
||||
|
||||
<p>Stop the cluster and restore only the test2 database. Built-in databases (<id>template0</id>, <id>template1</id>, and <id>postgres</id>) are always restored.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Restore from last backup including only the test2 database</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1078,7 +1078,7 @@
|
||||
|
||||
<p>Once recovery is complete the test2 database will contain all previously created tables and data.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Demonstrate that the test2 database was recovered</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1090,7 +1090,7 @@
|
||||
|
||||
<p>The test1 database, despite successful recovery, is not accessible. This is because the entire database was restored as sparse, zeroed files. <postgres/> can successfully apply WAL on the zeroed files but the database as a whole will not be valid because key files contain no data. This is purposeful to prevent the database from being accidentally used when it might contain partial data that was applied during WAL replay.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Attempting to connect to the test1 database will produce an error</title>
|
||||
|
||||
<execute output="y" filter="n" err-expect="2">
|
||||
@ -1105,7 +1105,7 @@
|
||||
|
||||
<p>It is clear that the test1 database uses far less disk space during the selective restore than it would have if the entire database had been restored.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Show space used by test1 database after recovery</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1117,7 +1117,7 @@
|
||||
|
||||
<p>At this point the only action that can be taken on the invalid test1 database is <id>drop database</id>. <backrest/> does not automatically drop the database since this cannot be done until recovery is complete and the cluster is accessible.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Drop the test1 database</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1129,7 +1129,7 @@
|
||||
|
||||
<p>Now that the invalid test1 database has been dropped only the test2 and built-in databases remain.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>List remaining databases</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1150,7 +1150,7 @@
|
||||
|
||||
<p>Point-in-Time Recovery (PITR) allows the WAL to be played from the last backup to a specified time, transaction id, or recovery point. For common recovery scenarios time-based recovery is arguably the most useful. A typical recovery scenario is to restore a table that was accidentally dropped or data that was accidentally deleted. Recovering a dropped table is more dramatic so that's the example given here but deleted data would be recovered in exactly the same way.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Backup the {[postgres-cluster-demo]} cluster and create a table with very important data</title>
|
||||
|
||||
<execute>
|
||||
@ -1171,7 +1171,7 @@
|
||||
|
||||
<p>It is important to represent the time as reckoned by <postgres/> and to include timezone offsets. This reduces the possibility of unintended timezone conversions and an unexpected recovery result.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Get the time from <postgres/></title>
|
||||
|
||||
<execute output="y" filter="n" variable-key="time-recovery-timestamp">
|
||||
@ -1183,7 +1183,7 @@
|
||||
|
||||
<p>Now that the time has been recorded the table is dropped. In practice finding the exact time that the table was dropped is a lot harder than in this example. It may not be possible to find the exact time, but some forensic work should be able to get you close.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Drop the important table</title>
|
||||
|
||||
<execute output="y" err-expect="1">
|
||||
@ -1197,7 +1197,7 @@
|
||||
|
||||
<p>Now the restore can be performed with time-based recovery to bring back the missing table.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop <postgres/>, restore the {[postgres-cluster-demo]} cluster to <id>{[time-recovery-timestamp]}</id>, and display <file>recovery.conf</file></title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1221,7 +1221,7 @@
|
||||
|
||||
<p>The <file>recovery.conf</file> file has been automatically generated by <backrest/> so <postgres/> can be started immediately. Once <postgres/> has finished recovery the table will exist again and can be queried.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Start <postgres/> and check that the important table exists</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1240,7 +1240,7 @@
|
||||
|
||||
<p>The <postgres/> log also contains valuable information. It will indicate the time and transaction where the recovery stopped and also give the time of the last transaction to be applied.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Examine the <postgres/> log output</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -1251,7 +1251,7 @@
|
||||
|
||||
<p>This example was rigged to give the correct result. If a backup after the required time is chosen then <postgres/> will not be able to recover the lost table. <postgres/> can only play forward, not backward. To demonstrate this the important table must be dropped (again).</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Drop the important table (again)</title>
|
||||
|
||||
<execute output="y" err-expect="1">
|
||||
@ -1265,7 +1265,7 @@
|
||||
|
||||
<p>Now take a new backup and attempt recovery from the new backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Perform a backup then attempt recovery from that backup</title>
|
||||
|
||||
<execute show="n" variable-key="backup-last">
|
||||
@ -1305,7 +1305,7 @@
|
||||
|
||||
<p>Looking at the log output it's not obvious that recovery failed to restore the table. The key is to look for the presence of the <quote>recovery stopping before...</quote> and <quote>last completed transaction...</quote> log messages. If they are not present then the recovery to the specified point-in-time was not successful.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Examine the <postgres/> log output to discover the recovery was not successful</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -1316,7 +1316,7 @@
|
||||
|
||||
<p>Using an earlier backup will allow <postgres/> to play forward to the correct time. The <cmd>info</cmd> command can be used to find the next to last backup.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Get backup info for the {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute filter="n" output="y">
|
||||
@ -1327,7 +1327,7 @@
|
||||
|
||||
<p>The default behavior for restore is to use the last backup but an earlier backup can be specified with the <br-option>{[dash]}-set</br-option> option.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop <postgres/>, restore from the selected backup, and start <postgres/></title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1362,7 +1362,7 @@
|
||||
|
||||
<p>Now the the log output will contain the expected <quote>recovery stopping before...</quote> and <quote>last completed transaction...</quote> messages showing that the recovery was successful.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Examine the <postgres/> log output for log messages indicating success</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -1378,7 +1378,7 @@
|
||||
|
||||
<p><backrest/> supports storing repositories in <proper>Amazon S3</proper>.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure <proper>S3</proper></title>
|
||||
|
||||
<backrest-config-option section="global" key="repo-type">s3</backrest-config-option>
|
||||
@ -1395,7 +1395,7 @@
|
||||
|
||||
<p>Commands are run exactly as if the repository were stored on a local disk.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create the stanza</title>
|
||||
|
||||
<!-- set host entries to redirect aws to local s3 server -->
|
||||
@ -1416,7 +1416,7 @@
|
||||
|
||||
<p>File creation time in <proper>S3</proper> is relatively slow so commands benefit by increasing <br-option>process-max</br-option> to parallelize file creation.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Backup the {[postgres-cluster-demo]} cluster</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -1494,13 +1494,13 @@
|
||||
<backrest-config-option section="global" key="repo-path">{[backrest-repo-path]}</backrest-config-option>
|
||||
</backrest-config>
|
||||
|
||||
<p>For this example a new host named <host>backup</host> has been created to store the cluster backups. Follow the instructions in <link section="/installation">Installation</link> to install <backrest/>, <link section="/quickstart/create-repository">Create the Repository</link> to create the <backrest/> repository and <link section="/quickstart/create-stanza">Create the Stanza</link> to create the stanza. The <host>backup</host> host must also be configured with the <host>db-master</host> host/user and database path. The master database will be configured as <id>db1</id> to allow a standby to be added later.</p>
|
||||
<p>For this example a new host named <host>backup</host> has been created to store the cluster backups. Follow the instructions in <link section="/installation">Installation</link> to install <backrest/>, <link section="/quickstart/create-repository">Create the Repository</link> to create the <backrest/> repository and <link section="/quickstart/create-stanza">Create the Stanza</link> to create the stanza. The <host>backup</host> host must also be configured with the <host>db-primary</host> host/user and database path. The primary will be configured as <id>db1</id> to allow a standby to be added later.</p>
|
||||
|
||||
<backrest-config host="{[host-backup]}" owner="backrest:postgres" file="{[backrest-config-demo]}">
|
||||
<title>Configure <br-option>db1-host</br-option>/<br-option>db1-user</br-option> and <br-option>db1-path</br-option></title>
|
||||
|
||||
<backrest-config-option section="demo" key="db1-path">{[db-path]}</backrest-config-option>
|
||||
<backrest-config-option section="demo" key="db1-host">{[host-db-master]}</backrest-config-option>
|
||||
<backrest-config-option section="demo" key="db1-host">{[host-db-primary]}</backrest-config-option>
|
||||
<backrest-config-option section="demo" key="db1-user">postgres</backrest-config-option>
|
||||
|
||||
<backrest-config-option section="global" key="start-fast">y</backrest-config-option>
|
||||
@ -1512,7 +1512,7 @@
|
||||
|
||||
<p>The database host must be configured with the backup host/user. The default for the <br-option>backup-user</br-option> option is <id>backrest</id>. If the <id>postgres</id> user does restores on the backup host it is best not to also allow the <id>postgres</id> user to perform backups. However, the <id>postgres</id> user can read the repository directly if it is in the same group as the <id>backrest</id> user.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}" reset="y">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}" reset="y">
|
||||
<title>Configure <br-option>backup-host</br-option>/<br-option>backup-user</br-option></title>
|
||||
|
||||
<backrest-config-option section="demo" key="db-path">{[db-path]}</backrest-config-option>
|
||||
@ -1528,7 +1528,7 @@
|
||||
|
||||
<p>The repository directory will also be removed from the database host. It will not be used anymore so leaving it around may be confusing later on.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Remove repository now that it will be located on the backup host server</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1550,7 +1550,7 @@
|
||||
|
||||
<p>Check that the configuration is correct on both the <host>database</host> and <host>backup</host> hosts. More information about the <cmd>check</cmd> command can be found in <link section="/quickstart/check-configuration">Check the Configuration</link>.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Check the configuration</title>
|
||||
|
||||
<execute output="y" filter="n" >
|
||||
@ -1590,7 +1590,7 @@
|
||||
|
||||
<p>To perform a restore of the <postgres/> cluster run <backrest/> with the <cmd>restore</cmd> command on the <host>database</host> host.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop the {[postgres-cluster-demo]} cluster, restore, and restart <postgres/></title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1631,7 +1631,7 @@
|
||||
|
||||
<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 <id>v1.12</id> or prior, read the <id>v1.13</id> release notes carefully before upgrading.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create the spool directory</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -1644,7 +1644,7 @@
|
||||
|
||||
<p>The spool path must be configured and asynchronous archiving enabled. Asynchronous archiving automatically confers some benefit by reducing the number of ssh connections made to the backup server, but setting <br-option>process-max</br-option> can drastically improve performance. Be sure not to set <br-option>process-max</br-option> so high that it affects normal database operations.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure the spool path and asynchronous archiving</title>
|
||||
|
||||
<backrest-config-option section="global" key="spool-path">{[spool-path]}</backrest-config-option>
|
||||
@ -1654,7 +1654,7 @@
|
||||
|
||||
<p>The <file>archive-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>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Test parallel asynchronous archiving</title>
|
||||
|
||||
<execute output="n" show="n">
|
||||
@ -1680,7 +1680,7 @@
|
||||
|
||||
<p>Now the log file will contain parallel, asynchronous activity.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Check results in the log</title>
|
||||
|
||||
<execute output="y">
|
||||
@ -1748,9 +1748,9 @@
|
||||
<section id="start-stop" depend="/backup-host/install-config">
|
||||
<title>Starting and Stopping</title>
|
||||
|
||||
<p>Sometimes it is useful to prevent <backrest/> from running on a system. For example, when failing over from a master to a standby it's best to prevent <backrest/> from running on the old master in case <postgres/> gets restarted or can't be completely killed. This will also prevent <backrest/> from running on <id>cron</id>.</p>
|
||||
<p>Sometimes it is useful to prevent <backrest/> from running on a system. For example, when failing over from a primary to a standby it's best to prevent <backrest/> from running on the old primary in case <postgres/> gets restarted or can't be completely killed. This will also prevent <backrest/> from running on <id>cron</id>.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop the <backrest/> services</title>
|
||||
|
||||
<execute>
|
||||
@ -1771,7 +1771,7 @@
|
||||
|
||||
<p>Specify the <br-option>--force</br-option> option to terminate any <backrest/> process that are currently running. If <backrest/> is already stopped then stopping again will generate a warning.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop the <backrest/> services again</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -1781,7 +1781,7 @@
|
||||
|
||||
<p>Start <backrest/> processes again with the <cmd>start</cmd> command.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Start the <backrest/> services</title>
|
||||
|
||||
<execute>
|
||||
@ -1791,7 +1791,7 @@
|
||||
|
||||
<p>It is also possible to stop <backrest/> for a single stanza.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop <backrest/> services for the <id>demo</id> stanza</title>
|
||||
|
||||
<execute>
|
||||
@ -1812,7 +1812,7 @@
|
||||
|
||||
<p>The stanza must also be specified when starting the <backrest/> processes for a single stanza.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Start the <backrest/> services for the <id>demo</id> stanza</title>
|
||||
|
||||
<execute>
|
||||
@ -1825,7 +1825,7 @@
|
||||
<section id="replication" depend="/backup-host/perform-backup">
|
||||
<title>Replication</title>
|
||||
|
||||
<p>Replication allows multiple copies of a <postgres/> cluster (called standbys) to be created from a single master. The standbys are useful for balancing reads and to provide redundancy in case the master host fails.</p>
|
||||
<p>Replication allows multiple copies of a <postgres/> cluster (called standbys) to be created from a single primary. The standbys are useful for balancing reads and to provide redundancy in case the primary host fails.</p>
|
||||
|
||||
<!-- SECTION => REPLICATION - HOT-STANDBY -->
|
||||
<section id="hot-standby">
|
||||
@ -1910,7 +1910,7 @@
|
||||
<postgres-config-option key="log_filename">'postgresql.log'</postgres-config-option>
|
||||
</postgres-config>
|
||||
|
||||
<p><backrest/> configuration is very similar to <host>db-master</host> except that the <pg-option>standby_mode</pg-option> setting will be enabled to keep the cluster in recovery mode when the end of the WAL stream has been reached.</p>
|
||||
<p><backrest/> configuration is very similar to <host>db-primary</host> except that the <pg-option>standby_mode</pg-option> setting will be enabled to keep the cluster in recovery mode when the end of the WAL stream has been reached.</p>
|
||||
|
||||
<backrest-config host="{[host-db-standby]}" file="{[backrest-config-demo]}">
|
||||
<title>Configure <backrest/> on the standby</title>
|
||||
@ -1976,10 +1976,10 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>An easy way to test that replication is properly configured is to create a table on <host>db-master</host>.</p>
|
||||
<p>An easy way to test that replication is properly configured is to create a table on <host>db-primary</host>.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<title>Create a new table on the master</title>
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create a new table on the primary</title>
|
||||
|
||||
<execute output="y">
|
||||
<exe-cmd>
|
||||
@ -2005,11 +2005,11 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>So, what went wrong? Since <postgres/> is pulling WAL segments from the archive to perform replication, changes won't be seen on the standby until the WAL segment that contains those changes is pushed from <host>db-master</host>.</p>
|
||||
<p>So, what went wrong? Since <postgres/> is pulling WAL segments from the archive to perform replication, changes won't be seen on the standby until the WAL segment that contains those changes is pushed from <host>db-primary</host>.</p>
|
||||
|
||||
<p>This can be done manually by calling <code>pg_switch_xlog()</code> which pushes the current WAL segment to the archive (a new WAL segment is created to contain further changes).</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Call <code>pg_switch_xlog()</code></title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -2047,11 +2047,11 @@
|
||||
<section id="streaming">
|
||||
<title>Streaming Replication</title>
|
||||
|
||||
<p>Instead of relying solely on the WAL archive, streaming replication makes a direct connection to the master and applies changes as soon as they are made on the master. This results in much less lag between the master and standby.</p>
|
||||
<p>Instead of relying solely on the WAL archive, streaming replication makes a direct connection to the primary and applies changes as soon as they are made on the primary. This results in much less lag between the primary and standby.</p>
|
||||
|
||||
<p>Streaming replication requires a user with the replication privilege.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create replication user</title>
|
||||
|
||||
<execute output="y" filter="n">
|
||||
@ -2062,9 +2062,9 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>The <file>pg_hba.conf</file> file must be updated to allow the standby to connect as the replication user. Be sure to replace the IP address below with the actual IP address of your <host>db-master</host>. A reload will be required after modifying the <file>pg_hba.conf</file> file.</p>
|
||||
<p>The <file>pg_hba.conf</file> file must be updated to allow the standby to connect as the replication user. Be sure to replace the IP address below with the actual IP address of your <host>db-primary</host>. A reload will be required after modifying the <file>pg_hba.conf</file> file.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create <file>pg_hba.conf</file> entry for replication user</title>
|
||||
|
||||
<execute>
|
||||
@ -2080,15 +2080,15 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<!-- <p>The <pg-option>max_wal_senders</pg-option> setting must be increased (the default is 0) to allow standbys to connect to the master. It will be set to 3 to allow more standbys to be created later. <postgres/> must restarted for this setting to take effect.</p>
|
||||
<!-- <p>The <pg-option>max_wal_senders</pg-option> setting must be increased (the default is 0) to allow standbys to connect to the primary. It will be set to 3 to allow more standbys to be created later. <postgres/> must restarted for this setting to take effect.</p>
|
||||
|
||||
<postgres-config host="{[host-db-master]}" file="{[postgres-config-demo]}">
|
||||
<postgres-config host="{[host-db-primary]}" file="{[postgres-config-demo]}">
|
||||
<title>Increase <pg-option>max_wal_senders</pg-option></title>
|
||||
|
||||
<postgres-config-option key="max_wal_senders">3</postgres-config-option>
|
||||
</postgres-config>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Restart <postgres/></title>
|
||||
|
||||
<execute user="root">
|
||||
@ -2096,12 +2096,12 @@
|
||||
</execute>
|
||||
</execute-list> -->
|
||||
|
||||
<p>The standby needs to know how to contact the master so the <pg-option>primary_conninfo</pg-option> setting will be configured in <backrest/>.</p>
|
||||
<p>The standby needs to know how to contact the primary so the <pg-option>primary_conninfo</pg-option> setting will be configured in <backrest/>.</p>
|
||||
|
||||
<backrest-config host="{[host-db-standby]}" file="{[backrest-config-demo]}">
|
||||
<title>Set <pg-option>primary_conninfo</pg-option></title>
|
||||
|
||||
<backrest-config-option section="demo" key="recovery-option">primary_conninfo=host={[host-db-master-ip]} port=5432 user=replicator</backrest-config-option>
|
||||
<backrest-config-option section="demo" key="recovery-option">primary_conninfo=host={[host-db-primary-ip]} port=5432 user=replicator</backrest-config-option>
|
||||
</backrest-config>
|
||||
|
||||
<p>It is possible to configure a password in the <pg-option>primary_conninfo</pg-option> setting but using a <file>.pgpass</file> file is more flexible and secure.</p>
|
||||
@ -2112,7 +2112,7 @@
|
||||
<execute>
|
||||
<exe-cmd>
|
||||
sh -c 'echo
|
||||
"{[host-db-master-ip]}:*:replication:replicator:jw8s0F4"
|
||||
"{[host-db-primary-ip]}:*:replication:replicator:jw8s0F4"
|
||||
>> {[postgres-pgpass]}'
|
||||
</exe-cmd>
|
||||
</execute>
|
||||
@ -2140,7 +2140,7 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p keyword="co6">By default {[user-guide-os]} stores the <file>postgresql.conf</file> file in the <postgres/> data directory. That means the change made to <file>postgresql.conf</file> was overwritten by the last restore and the <pg-option>hot_standby</pg-option> setting must be enabled again. Other solutions to this problem are to store the <file>postgresql.conf</file> file elsewhere or to enable the <pg-option>hot_standby</pg-option> setting on the <host>db-master</host> host where it will be ignored.</p>
|
||||
<p keyword="co6">By default {[user-guide-os]} stores the <file>postgresql.conf</file> file in the <postgres/> data directory. That means the change made to <file>postgresql.conf</file> was overwritten by the last restore and the <pg-option>hot_standby</pg-option> setting must be enabled again. Other solutions to this problem are to store the <file>postgresql.conf</file> file elsewhere or to enable the <pg-option>hot_standby</pg-option> setting on the <host>db-primary</host> host where it will be ignored.</p>
|
||||
|
||||
<postgres-config host="{[host-db-standby]}" keyword="co6" file="{[postgres-config-demo]}">
|
||||
<title>Enable <pg-option>hot_standby</pg-option></title>
|
||||
@ -2175,10 +2175,10 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>Now when a table is created on <host>db-master</host> it will appear on <host>db-standby</host> quickly and without the need to call <code>pg_switch_xlog()</code>.</p>
|
||||
<p>Now when a table is created on <host>db-primary</host> it will appear on <host>db-standby</host> quickly and without the need to call <code>pg_switch_xlog()</code>.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<title>Create a new table on the master</title>
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Create a new table on the primary</title>
|
||||
|
||||
<execute output="y">
|
||||
<exe-cmd>
|
||||
@ -2209,7 +2209,7 @@
|
||||
<section id="standby-backup" depend="/replication/streaming">
|
||||
<title>Backup from a Standby</title>
|
||||
|
||||
<p><backrest/> can perform backups on a standby instead of the master. Standby backups require the <host>db-standby</host> host to be configured and the <br-option>backup-standby</br-option> option enabled. If more than one standby is configured then the first running standby found will be used for the backup.</p>
|
||||
<p><backrest/> can perform backups on a standby instead of the primary. Standby backups require the <host>db-standby</host> host to be configured and the <br-option>backup-standby</br-option> option enabled. If more than one standby is configured then the first running standby found will be used for the backup.</p>
|
||||
|
||||
<backrest-config host="{[host-backup]}" owner="backrest:postgres" file="{[backrest-config-demo]}">
|
||||
<title>Configure <br-option>db2-host</br-option>/<br-option>db2-user</br-option> and <br-option>db2-path</br-option></title>
|
||||
@ -2221,20 +2221,20 @@
|
||||
<backrest-config-option section="global" key="backup-standby">y</backrest-config-option>
|
||||
</backrest-config>
|
||||
|
||||
<p>Both the master and standby databases are required to perform the backup, though the vast majority of the files will be copied from the standby to reduce load on the master. The database hosts can be configured in any order. <backrest/> will automatically determine which is the master and which is the standby.</p>
|
||||
<p>Both the primary and standby databases are required to perform the backup, though the vast majority of the files will be copied from the standby to reduce load on the primary. The database hosts can be configured in any order. <backrest/> will automatically determine which is the primary and which is the standby.</p>
|
||||
|
||||
<execute-list host="{[host-backup]}">
|
||||
<title>Backup the {[postgres-cluster-demo]} cluster from <host>db-standby</host></title>
|
||||
|
||||
<execute user="backrest" output="y" filter="y">
|
||||
<exe-cmd>{[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} --log-level-console=detail backup</exe-cmd>
|
||||
<exe-highlight>backup file db-master|replay on the standby</exe-highlight>
|
||||
<exe-highlight>backup file db-primary|replay on the standby</exe-highlight>
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>This incremental backup shows that most of the files are copied from the <host>db-standby</host> host and only a few are copied from the <host>db-master</host> host.</p>
|
||||
<p>This incremental backup shows that most of the files are copied from the <host>db-standby</host> host and only a few are copied from the <host>db-primary</host> host.</p>
|
||||
|
||||
<p><backrest/> creates a standby backup that is identical to a backup performed on the master. It does this by starting/stopping the backup on the <host>db-master</host> host, copying only files that are replicated from the <host>db-standby</host> host, then copying the remaining few files from the <host>db-master</host> host. This means that logs and statistics from the master database will be included in the backup.</p>
|
||||
<p><backrest/> creates a standby backup that is identical to a backup performed on the primary. It does this by starting/stopping the backup on the <host>db-primary</host> host, copying only files that are replicated from the <host>db-standby</host> host, then copying the remaining few files from the <host>db-primary</host> host. This means that logs and statistics from the primary database will be included in the backup.</p>
|
||||
</section>
|
||||
|
||||
<!-- SECTION => STANZA UPGRADE -->
|
||||
@ -2242,9 +2242,9 @@
|
||||
<title>Upgrading <postgres/></title>
|
||||
<cmd-description key="stanza-upgrade"/>
|
||||
|
||||
<p>The following instructions are not meant to be a comprehensive guide for upgrading <postgres/>, rather they will outline the general process for upgrading a master and standby with the intent of demonstrating the steps required to reconfigure <backrest/>. It is recommended that a backup be taken prior to upgrading.</p>
|
||||
<p>The following instructions are not meant to be a comprehensive guide for upgrading <postgres/>, rather they will outline the general process for upgrading a primary and standby with the intent of demonstrating the steps required to reconfigure <backrest/>. It is recommended that a backup be taken prior to upgrading.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Install new <postgres/> version</title>
|
||||
|
||||
<execute user="root" err-suppress="y">
|
||||
@ -2255,7 +2255,7 @@
|
||||
|
||||
<p>Create the new cluster. If the <postgres/> install creates a default cluster, then remove it to avoid confusion.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Drop default cluster and create the new demo cluster</title>
|
||||
|
||||
<execute user="root" keyword="default" err-suppress="y">
|
||||
@ -2273,7 +2273,7 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>Stop the old cluster on the standby since it will be restored from the newly upgraded cluster to ensure the database system id is identical on both the master and standby.</p>
|
||||
<p>Stop the old cluster on the standby since it will be restored from the newly upgraded cluster to ensure the database system id is identical on both the primary and standby.</p>
|
||||
|
||||
<execute-list host="{[host-db-standby]}">
|
||||
<title>Stop old cluster and drop default cluster if created</title>
|
||||
@ -2292,9 +2292,9 @@
|
||||
</execute>
|
||||
</execute-list>
|
||||
|
||||
<p>Stop the old cluster on the master and perform the upgrade.</p>
|
||||
<p>Stop the old cluster on the primary and perform the upgrade.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Stop old cluster and perform the upgrade</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -2330,7 +2330,7 @@
|
||||
|
||||
<p>Configure the new cluster settings and port.</p>
|
||||
|
||||
<postgres-config host="{[host-db-master]}" file="{[postgres-config-demo-upgrade]}">
|
||||
<postgres-config host="{[host-db-primary]}" file="{[postgres-config-demo-upgrade]}">
|
||||
<title>Configure <postgres/></title>
|
||||
|
||||
<postgres-config-option key="archive_command">'{[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} archive-push %p'</postgres-config-option>
|
||||
@ -2344,7 +2344,7 @@
|
||||
|
||||
<p>Update the <backrest/> configuration on all systems to point to the new cluster.</p>
|
||||
|
||||
<backrest-config host="{[host-db-master]}" file="{[backrest-config-demo]}">
|
||||
<backrest-config host="{[host-db-primary]}" file="{[backrest-config-demo]}">
|
||||
<title>Upgrade the <br-option>db-path</br-option></title>
|
||||
|
||||
<backrest-config-option section="demo" key="db-path">{[db-path-upgrade]}</backrest-config-option>
|
||||
@ -2365,7 +2365,7 @@
|
||||
<backrest-config-option section="global" key="backup-standby">n</backrest-config-option>
|
||||
</backrest-config>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Copy hba configuration</title>
|
||||
|
||||
<execute user="root">
|
||||
@ -2388,7 +2388,7 @@
|
||||
|
||||
<p>Start the new cluster and confirm it is successfully installed.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Start new cluster</title>
|
||||
|
||||
<execute user="root" output="y">
|
||||
@ -2398,7 +2398,7 @@
|
||||
|
||||
<p>Test configuration using the <cmd>check</cmd> command. The warning on the <host>backup</host> host regarding the standby being down is expected and can be ignored.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Check configuration</title>
|
||||
|
||||
<execute output="y" filter="n" >
|
||||
@ -2420,7 +2420,7 @@
|
||||
|
||||
<p>Remove the old cluster.</p>
|
||||
|
||||
<execute-list host="{[host-db-master]}">
|
||||
<execute-list host="{[host-db-primary]}">
|
||||
<title>Remove old cluster</title>
|
||||
|
||||
<execute keyword="default" user="root">
|
||||
|
||||
Reference in New Issue
Block a user