Document upgrade process from repmgr3

Also provide unpackaged extension upgrade SQL, and a script to
assist converting repmgr.conf files.

doc/upgrading-from-repmgr3.md

@@ -0,0 +1,122 @@
+Upgrading from repmgr 3
+=======================
+
+The upgrade process consists of two steps:
+
+    1) converting the repmgr.conf configuration files
+    2) upgrading the repmgr schema.
+
+Scripts are provided to assist both with converting repmgr.conf
+and upgrading the schema.
+
+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` → `node_id`), and
+also for consistency with PostgreSQL naming conventions
+(e.g. `loglevel` → `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 oer time.
+
+`repmgr` will issue a warning about deprecated/altered options.
+
+
+### Changed parameters
+
+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:
+
+    - `failover` → `failover_mode`
+    - `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 port=5602
+    pg_ctl_options='-l /tmp/postgres.5602.log'
+    pg_bindir=/home/barwick/devel/builds/HEAD/bin
+    rsync_options=--exclude=postgresql.local.conf --archive
+    log_level=DEBUG
+    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 cronjobs which execute the
+`repmgr` binary.
+
+Install `repmgr4`; any `repmgr3` packages should be uninstalled
+(if not automatically installed already).
+
+### Manually create the repmgr extension
+
+In the database used by the existing `repmgr` configuration, execute:
+
+    CREATE EXTENSION repmgr FROM unpackaged;
+
+This will move and convert all objects from the existing schema
+into the new, standard `repmgr` schema.
+
+> *NOTE* 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.
+
+* * *
+
+> *TIP* 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.
+
+* * *