github/repmgr
1
0
Fork 0
mirror of https://github.com/EnterpriseDB/repmgr.git synced 2026-03-26 08:36:30 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

doc: improve upgrade instructions

Browse Source
This commit is contained in:
Ian Barwick
2018-10-17 14:32:38 +09:00
parent ab6c3d9b6e
commit b70e3b48c8
1 changed files with 120 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
doc/upgrading-repmgr.sgml
View File

@@ -7,9 +7,9 @@
<title>Upgrading repmgr</title> <title>Upgrading repmgr</title>
<para> <para>
&repmgr; is updated regularly with point releases (e.g. 4.0.1 to 4.0.2) &repmgr; is updated regularly with minor releases (e.g. 4.0.1 to 4.0.2)
containing bugfixes and other minor improvements. Any substantial new containing bugfixes and other minor improvements. Any substantial new
functionality will be included in a feature release (e.g. 4.0.x to 4.1.x). functionality will be included in a major release (e.g. 4.0 to 4.1).
</para> </para>
<sect1 id="upgrading-repmgr-extension" xreflabel="Upgrading repmgr 4.x and later"> <sect1 id="upgrading-repmgr-extension" xreflabel="Upgrading repmgr 4.x and later">
@@ -19,83 +19,110 @@
</indexterm> </indexterm>
<title>Upgrading repmgr 4.x and later</title> <title>Upgrading repmgr 4.x and later</title>
<para> <para>
&repmgr; 4.x is implemented as a PostgreSQL extension; normally the upgrade consists From version 4, &repmgr; consists of three elements:
of the following steps: <itemizedlist spacing="compact" mark="bullet">
<orderedlist>
<listitem> <listitem>
<simpara> <simpara>
Stop <application>repmgrd</application> (if in use) on all nodes where it is running the <application>repmgr</application> and <application>repmgrd</application> executables
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
Install the updated package (or compile the updated source) the objects for the &repmgr; PostgreSQL extension (SQL files for creating/updating
</simpara> repmgr metadata, and the extension control file)
</listitem> </simpara>
</listitem>
<listitem> <listitem>
<simpara> <simpara>
For major releases, e.g. from <literal>4.0.x</literal> to <literal>4.1</literal>, the shared library module used by <application>repmgrd</application> which
where the <literal>repmgr</literal> shared object library has been updated, is resident in the PostgreSQL backend
restart PostgreSQL. </simpara>
</simpara> </listitem>
</listitem> </itemizedlist>
</para>
<listitem> <para>
<simpara> With <emphasis>minor releases</emphasis>, usually changes are only made to the <application>repmgr</application>
For major releases, e.g. from <literal>4.0.x</literal> to <literal>4.1</literal>, and <application>repmgrd</application> executables. In this case, the upgrade is quite straightforward,
execute <command>ALTER EXTENSION repmgr UPDATE</command> and is simply a case of installing the new version, and restarting <application>repmgrd</application>
on the primary node in the database where the &repmgr; extension is installed. (if running).
</simpara>
<simpara>
This will update the extension metadata and, if necessary, apply
changes to the &repmgr; extension objects.
</simpara>
</listitem>
<listitem>
<simpara>
Start <application>repmgrd</application> (if in use).
</simpara>
</listitem>
</orderedlist>
</para> </para>
<para> <para>
Always check the <link linkend="appendix-release-notes">release notes</link> for every For <emphasis>major releases</emphasis>, the &repmgr; PostgreSQL extension will need to be updated
release as they may contain upgrade instructions particular to individual versions. to the latest version. Additionally, if the shared library module has been updated (this is sometimes,
but not always the case), PostgreSQL itself will need to be restarted on each node.
</para> </para>
<important>
<para>
Always check the <link linkend="appendix-release-notes">release notes</link> for every
release as they may contain upgrade instructions particular to individual versions.
</para>
</important>
<para> <sect2 id="upgrading-minor-version" xreflabel="Upgrading a minor version release">
Note that it may be necessary to restart the PostgreSQL server if the upgrade contains
changes to the shared object file used by <application>repmgrd</application>; check the
<link linkend="appendix-release-notes">release notes</link> for details.
</para>
<sect2 id="upgrading-replication-cluster" xreflabel="Upgrading a replication cluster">
<indexterm> <indexterm>
<primary>upgrading</primary> <primary>upgrading</primary>
<secondary>repmgr 4.x and later</secondary> <secondary>minor release</secondary>
</indexterm> </indexterm>
<title>Upgrading a replication cluster</title> <title>Upgrading a minor version release</title>
<para>
The process for installing minor version upgrades is quite straightforward:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<simpara>
install the new &repmgr; version
</simpara>
</listitem>
<listitem>
<simpara>
restart <application>repmgrd</application> on all nodes where it is running
</simpara>
</listitem>
</itemizedlist>
</para>
<note>
<para>
Some packaging systems (e.g. <link linkend="packages-debian-ubuntu">Debian/Ubuntu</link>
may restart <application>repmgrd</application> as part of the package upgrade process.
</para>
</note>
<para> <para>
The same &repmgr; &quot;major version&quot; (e.g. <literal>4.2</literal>) must be Minor version upgrades can be performed in any order on the nodes in the replication
installed on all nodes in the replication cluster. While it's possible to have differing cluster.
&repmgr; &quot;minor versions&quot; (e.g. <literal>4.2.1</literal>) on different nodes,
we strongly recommend updating all nodes to the latest minor version.
</para> </para>
<note>
<para>
A PostgreSQL restart is <emphasis>not</emphasis> required for minor version upgrades.
</para>
<note>
<para> <para>
Minor version upgrades can be performed in any order on the nodes in the replicaiton The same &repmgr; &quot;major version&quot; (e.g. <literal>4.2</literal>) must be
cluster. In general it makes sense to start on the primary. installed on all nodes in the replication cluster. While it's possible to have differing
&repmgr; &quot;minor versions&quot; (e.g. <literal>4.2.1</literal>) on different nodes,
we strongly recommend updating all nodes to the latest minor version.
</para> </para>
<para> </note>
A PostgreSQL restart is <emphasis>not</emphasis> required for minor version upgrades.
</para> </sect2>
</note>
<sect2 id="upgrading-major-version" xreflabel="Upgrading a major version release">
<indexterm>
<primary>upgrading</primary>
<secondary>major release</secondary>
</indexterm>
<title>Upgrading a major version release</title>
<para> <para>
&quot;major version&quot; upgrades need to be planned more carefully, as they may include &quot;major version&quot; upgrades need to be planned more carefully, as they may include
changes to the &repmgr; metadata (which need to be propagated from the primary to all changes to the &repmgr; metadata (which need to be propagated from the primary to all
@@ -111,7 +138,14 @@
<listitem> <listitem>
<simpara> <simpara>
Stop <application>repmgrd</application> (if in use) on all nodes where it is running Stop <application>repmgrd</application> (if in use) on all nodes where it is running.
</simpara>
</listitem>
<listitem>
<simpara>
Disable the <application>repmgrd</application> service on all nodes where it is in use;
this is to prevent packages from prematurely restarting <application>repmgrd</application>.
</simpara> </simpara>
</listitem> </listitem>
@@ -121,12 +155,12 @@
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
If necessary, restart PostgreSQL, then <application>repmgrd</application> (if in use) If the &repmgr; shared library module has been updated (check the <link linkend="appendix-release-notes">release notes</link>!),
on each node. The order in which this is applied to individual nodes is not critical, restart PostgreSQL, then <application>repmgrd</application> (if in use) on each node,
and it's also fine to restart on all nodes first before starting <application>repmgrd</application>. The order in which this is applied to individual nodes is not critical,
and it's also fine to restart PostgreSQL on all nodes first before starting <application>repmgrd</application>.
</simpara> </simpara>
<simpara> <simpara>
Note that if the upgrade requires a PostgreSQL restart, <application>repmgrd</application> Note that if the upgrade requires a PostgreSQL restart, <application>repmgrd</application>
@@ -143,6 +177,12 @@
</para> </para>
</listitem> </listitem>
<listitem>
<simpara>
Reenable the <application>repmgrd</application> service on all nodes where it is in use.
</simpara>
</listitem>
</orderedlist> </orderedlist>
</para> </para>
<tip> <tip>
@@ -154,6 +194,17 @@
</tip> </tip>
</sect2> </sect2>
<sect2 id="upgrading-check-repmgrd" xreflabel="Checking repmgrd status after an upgrade">
<indexterm>
<primary>upgrading</primary>
<secondary>checking repmgrd status</secondary>
</indexterm>
<title>Checking repmgrd status after an upgrade</title>
<para>
From &repmgr; 4.2, once the upgrade is complete, execute the <command><link linkend="repmgr-daemon-status">repmgr daemon status</link></command>
command (on any node) to show an overview of the status of <application>repmgrd</application> on all nodes.
</para>
</sect2>
</sect1> </sect1>
<sect1 id="upgrading-and-pg-upgrade" xreflabel="pg_upgrade and repmgr"> <sect1 id="upgrading-and-pg-upgrade" xreflabel="pg_upgrade and repmgr">