# Upgrading repmgr

&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 major release (e.g. 4.0 to 4.1).

## Upgrading repmgr 4.x and later

From version 4, &repmgr; consists of three elements:

- the repmgr and &repmgrd; executables

- the objects for the &repmgr; PostgreSQL extension (SQL files for creating/updating repmgr metadata, and the extension control file)

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

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.

### Upgrading a minor version release

A minor release upgrade involves updating &repmgr; from one minor release to another minor release within the same major release (e.g. `5.3.1` to `5.3.2`). An upgrade between minor releases of differing major releases (e.g. `5.2.1` to `5.3.2`) is a major upgrade.

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.

Minor version upgrades can be performed in any order on the nodes in the replication cluster.

A PostgreSQL restart is usually not required for minor version upgrades within the same major version (e.g. `5.3.1` to `5.3.2`). Be sure to check the release notes.

The same &repmgr; "major version" (e.g. `5.3`) must be installed on all nodes in the replication cluster. While it's possible to have differing &repmgr; "minor versions" (e.g. `5.3.1` and `5.3.2`) on different nodes, we strongly recommend updating all nodes to the latest minor version.

### 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 standbys) and/or changes to the shared object file used by &repmgrd; (which require a PostgreSQL restart).

With this in mind,

1. Stop &repmgrd; (if in use) on all nodes where it is running.

2. Disable the &repmgrd; service on all nodes where it is in use; this is to prevent packages from prematurely restarting &repmgrd;.

3. Install the updated package (or compile the updated source) on all nodes.

4. If running a `systemd`-based Linux distribution, execute (as `root`, or with appropriate `sudo` permissions):

       systemctl daemon-reload

5. 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; will only function correctly once all nodes have been restarted.

6. On the primary node, execute

       ALTER EXTENSION repmgr UPDATE

   in the database where &repmgr; is installed.

7. Reenable the &repmgrd; service on all nodes where it is in use, and ensure it is running.

If the &repmgr; upgrade requires a PostgreSQL restart, combine the &repmgr; upgrade with a PostgreSQL minor version upgrade, which will require a restart in any case.

New PostgreSQL minor versions are usually released every couple of months; see the Roadmap for the current schedule.

### Checking repmgrd status after an upgrade

From repmgr 4.2, once the upgrade is complete, execute the `repmgr service status` (&repmgr; 4.2 - 4.4: `repmgr daemon status`) command (on any node) to show an overview of the status of &repmgrd; on all nodes.

## pg_upgrade and repmgr

pg_upgrade requires that if any functions are dependent on a shared library, this library must be present in both the old and new installations before pg_upgrade can be executed.

To minimize the risk of any upgrade issues (particularly if an upgrade to a new major &repmgr; version is involved), we recommend upgrading &repmgr; on the old server before running pg_upgrade to ensure that old and new versions are the same.

This issue applies to any PostgreSQL extension which has dependencies on a shared library.

For further details please see the pg_upgrade documentation.

If replication slots are in use, bear in mind these will not be recreated by pg_upgrade. These will need to be recreated manually.

Use `repmgr node check` to determine which replication slots need to be recreated.

### Upgrading standbys with pg_upgrade and rsync

If you are intending to upgrade a standby using the `rsync` method described in the pg_upgrade documentation, you must ensure the standby's replication configuration is present and correct before starting the standby.

Use repmgr standby clone --replication-conf-only to generate the correct replication configuration.

If upgrading from PostgreSQL 11 or earlier, be sure to delete `recovery.conf`, if present, otherwise PostgreSQL will refuse to start.

## 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` (PostgreSQL 12 and earlier)

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'

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

#### 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`
`barman_server` | `barman_host`
`master_reponse_timeout` | `async_query_timeout`

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 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`

#### 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 from &repmgr; 4. This must be manually modified to contain the correct data directory.

### Upgrading the repmgr schema (PostgreSQL 12 and earlier)

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

Install the latest &repmgr; package; any `repmgr 3.x` packages should be uninstalled (if not automatically uninstalled already by your packaging system).

#### Upgrading from repmgr 3.1.1 or earlier

If you don't care about any data from the existing &repmgr; installation, (e.g. the contents of the events and monitoring tables), the following steps can be skipped; proceed to .

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:

- repmgr3.0_repmgr3.1.sql

- repmgr3.1.1_repmgr3.1.2.sql

For more details see the repmgr 3 upgrade notes.

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

### Upgrading the repmgr schema (PostgreSQL 13 and later)

Beginning with PostgreSQL 13, the `CREATE EXTENSION ... FROM unpackaged` syntax is no longer available. In the unlikely event you have ended up with an installation running PostgreSQL 13 or later and containing the legacy &repmgr; schema, there is no convenient way of upgrading this; instead you'll just need to re-register the nodes as detailed in the following section, which will create the &repmgr; extension automatically.

Any historical data you wish to retain (e.g. the contents of the events and monitoring tables) will need to be exported manually.

### 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

If not already present (e.g. after executing `CREATE EXTENSION repmgr FROM unpackaged`), the &repmgr; extension will be automatically created by `repmgr primary register`.

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.

### Drop the legacy repmgr schema

Once the cluster has been registered with the current &repmgr; version, the legacy `repmgr_$cluster` schema can be dropped at any time with:

        DROP SCHEMA repmgr_$cluster CASCADE

(substitute `$cluster` with the value of the `clustername` variable used in &repmgr; 3.x).