diff --git a/doc/upgrading-repmgr.sgml b/doc/upgrading-repmgr.sgml
index 732a0a4e..71cda746 100644
--- a/doc/upgrading-repmgr.sgml
+++ b/doc/upgrading-repmgr.sgml
@@ -7,16 +7,214 @@
&repmgr; is implemented as a PostgreSQL extension; to upgrade it, first
- install the updated package, then in the database where the &repmgr;
- extension is installed, execute ALTER EXTENSION repmgr UPDATE.
+ install the updated package (or compile the updated source), then in the
+ database where the &repmgr; extension is installed, execute
+ ALTER EXTENSION repmgr UPDATE.
If repmgrd is running, 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 from repmgr 3
+
+ The upgrade process consists of two steps:
+
+
+
+ converting the repmgr.conf configuration files
+
+
+
+
+ upgrading the repmgr schema
+
+
+
+
+
+ A script is provided to assist with converting repmgr.conf.
+
+
+ The schema upgrade (which converts the &repmgr; metadata into
+ a packaged PostgreSQL extension) is normally carried out
+ automatically when the &repmgr; extension is created.
+
+
+ Converting repmgr.conf configuration files
+
+ With a completely new repmgr version, we've taken the opportunity
+ to rename some configuration items have had their names changed for
+ clarity and consistency, both between the configuration file and
+ the column names in repmgr.nodes
+ (e.g. node to node_id), and
+ also for consistency with PostgreSQL naming conventions
+ (e.g. loglevel to log_level).
+
+
+ Other configuration items have been changed to command line options,
+ and vice-versa, e.g. to avoid hard-coding items such as a a node's
+ upstream ID, which might change over time.
+
+
+ &repmgr; will issue a warning about deprecated/altered options.
+
+
+ Changed parameters in "repmgr.conf"
+
+ Following parameters have been added:
+
+
+ data_directory: this is mandatory and must
+ contain the path to the node's data directory
+
+
+ monitoring_history: this replaces the
+ repmgrd command line option
+ --monitoring-history
+
+
+
+
+ Following parameters have been renamed:
+
+
+ Parameters renamed in repmgr4
+
+
+
+ repmgr3
+ repmgr4
+
+
+
+
+ node
+ node_id
+
+
+ loglevel
+ log_level
+
+
+ logfacility
+ log_facility
+
+
+ logfile
+ log_file
+
+
+ master_reponse_timeout
+ async_query_timeout
+
+
+
+
+
+ Following parameters have been removed:
+
+
+ cluster: is no longer required and will
+ be ignored.
+
+
+ upstream_node_id: is replaced by the
+ command-line parameter --upstream-node-id
+
+
+
+
+
+ Conversion script
+
+ To assist with conversion of repmgr.conf files, a Perl script
+ is provided in contrib/convert-config.pl.
+ Use like this:
+
+ $ ./convert-config.pl /etc/repmgr.conf
+ node_id=2
+ node_name=node2
+ conninfo=host=localhost dbname=repmgr user=repmgr connect_timeout=2
+ pg_ctl_options='-l /var/log/postgres/startup.log'
+ rsync_options=--exclude=postgresql.local.conf --archive
+ log_level=INFO
+ pg_basebackup_options=--no-slot
+ data_directory=
+
+
+ The converted file is printed to STDOUT and the original file is not
+ changed.
+
+
+ Please note that the parameter data_directory must
+ be provided; if not already present, the conversion script will add an empty
+ placeholder parameter.
+
+
+
+
+ Upgrading the repmgr schema
+
+ Ensure repmgrd is not running, or any cron jobs which execute the
+ repmgr binary.
+
+
+ Install repmgr4; any repmgr3 packages should be uninstalled
+ (if not automatically uninstalled already).
+
+
+ Manually create the repmgr extension
+
+ In the database used by the existing &repmgr; installation, execute:
+
+ CREATE EXTENSION repmgr FROM unpackaged;
+
+
+ This will move and convert all objects from the existing schema
+ into the new, standard repmgr schema.
+
+
+ there must be only one schema matching repmgr_% in the
+ database, otherwise this step may not work.
+
+
+
+ Re-register each node
+
+ This is necessary to update the repmgr metadata with some additional items.
+
+
+ On the primary node, execute e.g.
+
+ repmgr primary register -f /etc/repmgr.conf --force
+
+
+ On each standby node, execute e.g.
+
+ repmgr standby register -f /etc/repmgr.conf --force
+
+
+ Check the data is updated as expected by examining the repmgr.nodes
+ table; restart repmgrd if required.
+
+
+ The original repmgr_$cluster schema can be dropped at any time.
+
+
+
+ If you don't care about any data from the existing &repmgr; installation,
+ (e.g. the contents of the events and monitoring
+ tables), the manual CREATE EXTENSION step can be skipped; just re-register
+ each node, starting with the primary node, and the repmgr extension will be
+ automatically created.
+
+
+
+
+