11.3. Upgrading from repmgr 3.x

The upgrade process consists of two steps:

  1. converting the repmgr.conf configuration files

  2. upgrading the repmgr schema using CREATE EXTENSION

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.

The shared library has been renamed from repmgr_funcs to repmgr - if it's set in shared_preload_libraries in postgresql.conf it will need to be updated to the new name:

    shared_preload_libraries = 'repmgr'

11.3.1. Converting repmgr.conf configuration files

With a completely new repmgr version, we've taken the opportunity to rename some configuration items 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.

11.3.1.1. 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:

Table 11-1. Parameters renamed in repmgr4

repmgr3repmgr4
nodenode_id
loglevellog_level
logfacilitylog_facility
logfilelog_file
barman_serverbarman_host
master_reponse_timeoutasync_query_timeout

Note: From repmgr 4, barman_server refers to the server configured in Barman (in repmgr 3, the deprecated cluster parameter was used for this); the physical Barman hostname is configured with barman_host (see Section 5.1.1 for details).

Following parameters have been removed:

  • cluster: is no longer required and will be ignored.
  • upstream_node: is replaced by the command-line parameter --upstream-node-id

11.3.1.2. 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=node2 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 the conversion script will add an empty placeholder parameter for data_directory, which is a required parameter in repmgr4 and which must be provided.

11.3.2. Upgrading the repmgr schema

Ensure repmgrd is not running, or any cron jobs which execute the repmgr binary.

Install repmgr 4 packages; any repmgr 3.x packages should be uninstalled (if not automatically uninstalled already by your packaging system).

11.3.2.1. Upgrading from repmgr 3.1.1 or earlier

If your repmgr version is 3.1.1 or earlier, you will need to update the schema to the latest version in the 3.x series (3.3.2) before converting the installation to repmgr 4.

To do this, apply the following upgrade scripts as appropriate for your current version:

For more details see the repmgr 3 upgrade notes.

11.3.2.2. 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.

Note: there must be only one schema matching repmgr_% in the database, otherwise this step may not work.

11.3.2.3. 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.