diff --git a/doc/upgrading-repmgr.sgml b/doc/upgrading-repmgr.sgml
index 9cb87614..9da415d7 100644
--- a/doc/upgrading-repmgr.sgml
+++ b/doc/upgrading-repmgr.sgml
@@ -7,9 +7,9 @@
Upgrading repmgr
- &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
- 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).
@@ -19,83 +19,110 @@
Upgrading repmgr 4.x and later
- &repmgr; 4.x is implemented as a PostgreSQL extension; normally the upgrade consists
- of the following steps:
-
+ From version 4, &repmgr; consists of three elements:
+
-
-
- Stop repmgrd (if in use) on all nodes where it is running
-
-
+
+
+ the repmgr and repmgrd executables
+
+
-
-
- Install the updated package (or compile the updated source)
-
-
+
+
+ the objects for the &repmgr; PostgreSQL extension (SQL files for creating/updating
+ repmgr metadata, and the extension control file)
+
+
-
-
- For major releases, e.g. from 4.0.x to 4.1,
- where the repmgr shared object library has been updated,
- restart PostgreSQL.
-
-
-
-
-
- For major releases, e.g. from 4.0.x to 4.1,
- execute ALTER EXTENSION repmgr UPDATE
- on the primary node in the database where the &repmgr; extension is installed.
-
-
- This will update the extension metadata and, if necessary, apply
- changes to the &repmgr; extension objects.
-
-
-
-
-
- Start repmgrd (if in use).
-
-
-
-
+
+
+ the shared library module used by repmgrd which
+ is resident in the PostgreSQL backend
+
+
+
+
+
+ With minor releases, usually changes are only made to the repmgr
+ and repmgrd executables. In this case, the upgrade is quite straightforward,
+ and is simply a case of installing the new version, and restarting repmgrd
+ (if running).
- Always check the release notes for every
- release as they may contain upgrade instructions particular to individual versions.
+ For major releases, the &repmgr; PostgreSQL extension will need to be updated
+ 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.
+
+
+ Always check the release notes for every
+ release as they may contain upgrade instructions particular to individual versions.
+
+
-
- Note that it may be necessary to restart the PostgreSQL server if the upgrade contains
- changes to the shared object file used by repmgrd; check the
- release notes for details.
-
-
-
+ upgrading
- repmgr 4.x and later
+ minor release
- Upgrading a replication cluster
+ Upgrading a minor version release
+
+
+ The process for installing minor version upgrades is quite straightforward:
+
+
+
+
+
+ install the new &repmgr; version
+
+
+
+
+
+ restart repmgrd on all nodes where it is running
+
+
+
+
+
+
+
+
+
+ Some packaging systems (e.g. Debian/Ubuntu
+ may restart repmgrd as part of the package upgrade process.
+
+
+
- The same &repmgr; "major version" (e.g. 4.2) must be
- installed on all nodes in the replication cluster. While it's possible to have differing
- &repmgr; "minor versions" (e.g. 4.2.1) on different nodes,
- we strongly recommend updating all nodes to the latest minor version.
+ Minor version upgrades can be performed in any order on the nodes in the replication
+ cluster.
-
+
+
+ A PostgreSQL restart is not required for minor version upgrades.
+
+
+
- Minor version upgrades can be performed in any order on the nodes in the replicaiton
- cluster. In general it makes sense to start on the primary.
+ The same &repmgr; "major version" (e.g. 4.2) must be
+ installed on all nodes in the replication cluster. While it's possible to have differing
+ &repmgr; "minor versions" (e.g. 4.2.1) on different nodes,
+ we strongly recommend updating all nodes to the latest minor version.
-
- A PostgreSQL restart is not required for minor version upgrades.
-
-
+
+
+
+
+
+
+ upgrading
+ major release
+
+ Upgrading a major version release
"major version" 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
@@ -111,7 +138,14 @@
- Stop repmgrd (if in use) on all nodes where it is running
+ Stop repmgrd (if in use) on all nodes where it is running.
+
+
+
+
+
+ Disable the repmgrd service on all nodes where it is in use;
+ this is to prevent packages from prematurely restarting repmgrd.
@@ -121,12 +155,12 @@
-
- If necessary, restart PostgreSQL, then repmgrd (if in use)
- on each node. The order in which this is applied to individual nodes is not critical,
- and it's also fine to restart on all nodes first before starting repmgrd.
+ If the &repmgr; shared library module has been updated (check the release notes!),
+ restart PostgreSQL, then repmgrd (if in use) on each node,
+ 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 repmgrd.
Note that if the upgrade requires a PostgreSQL restart, repmgrd
@@ -143,6 +177,12 @@
+
+
+ Reenable the repmgrd service on all nodes where it is in use.
+
+
+
@@ -154,6 +194,17 @@
+
+
+ upgrading
+ checking repmgrd status
+
+ Checking repmgrd status after an upgrade
+
+ From &repmgr; 4.2, once the upgrade is complete, execute the repmgr daemon status
+ command (on any node) to show an overview of the status of repmgrd on all nodes.
+
+