From 39e8a560b01fd6356894c16b9fd64eb0452ee274 Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Tue, 10 Oct 2017 10:51:46 +0900 Subject: [PATCH] Update upgrade document --- doc/upgrading-repmgr.sgml | 202 +++++++++++++++++++++++++++++++++++++- 1 file changed, 200 insertions(+), 2 deletions(-) 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. + + + + +