# Release notes

Changes to each &repmgr; release are documented in the release notes. Please read the release notes for all versions between your current version and the version you are plan to upgrade to before performing an upgrade, as there may be version-specific upgrade steps.

See also: upgrading-repmgr

## Release 5.5.0

Wed 20 November, 2024

&repmgr; 5.5.0 is a major release.

This release adds support for PostgreSQL 17

Fixes warnings detected by the -Wshadow gcc flag added in PostgreSQL 16.

## Release 5.4.1

Tue 04 Jul, 2023

&repmgr; 5.4.1 is a minor release providing ...

### Bug fixes

- &repmgrd;: ensure witness node metadata is updated if the primary node changed while the witness &repmgrd; was not running.

## Release 5.4.0

Thu 15 March, 2023

&repmgr; 5.4.0 is a major release.

This release provides support for cloning standbys using backups taken with barman with the use of pg-backup-api.

Minor fixes to the documentation.

## Release 5.3.3

Mon 17 October, 2022

&repmgr; 5.3.3 is a minor release providing support for PostgreSQL 15 and a &repmgrd; bug fix.

If upgrading from an earlier &repmgr; version, any running &repmgrd; instances should be restarted.

If upgrading from &repmgr; 5.2.1 or earlier, a PostgreSQL restart is required.

### Bug fixes

- &repmgrd;: ensure event notification script is called for event `repmgrd_upstream_disconnect`. GitHub #760.

## Release 5.3.2

Wed 25 May, 2022

&repmgr; 5.3.2 is a minor release.

Any running &repmgrd; instances should be restarted following this upgrade.

If upgrading from &repmgr; 5.2.1 or earlier, a PostgreSQL restart is required.

### Bug fixes

- `repmgr node status`: fix output with `--downstream` `--nagios` option combination. GitHub #749.

- `repmgr standby clone`: don't treat inability to determine the cluster size as a fatal error.

  The cluster size is displayed for informational purposes and is not essential for execution of the clone operation. As the &repmgr; user may not have permissions for all databases in the cluster, ignore the cluster size query if it fails.

- &repmgrd;: ensure the witness node record on the primary is always marked as `active` if previously marked `inactive`. GitHub #754.

- &repmgrd;: if `standby_disconnect_on_failover` is set, verify &repmgr; is a superuser before attempting to disable the WAL receiver.

- If the &repmgr; user is a non-superuser, and a replication-only user exists, ensure redundant replication slots are dropped correctly even if the `-S/--superuser` option is not provided.

## Release 5.3.1

Tue 15 February, 2022

&repmgr; 5.3.1 is a minor release.

If &repmgrd; is in use, it should be restarted on all nodes where it is running.

If upgrading from &repmgr; 5.2.1 or earlier, a PostgreSQL restart is required.

### Bug fixes

- Fix upgrade path from &repmgr; 4.2 and 4.3 to &repmgr; 5.3.

- &repmgrd;: ensure potentially open connections are closed.

  In some cases, when recovering from degraded state in local node monitoring, new connection was opened to the local node without closing the old one, which will result in memory leakage.

## Release 5.3.0

Tue 12 October, 2021

&repmgr; 5.3.0 is a major release.

This release provides support for PostgreSQL 14, released in September 2021.

Note that this release includes changes to the &repmgr; shared library module, meaning a PostgreSQL restart is required on all nodes where &repmgr; is installed.

### Improvements

- `repmgr standby switchover`: Improve handling of node rejoin failure on the demotion candidate.

  Previously &repmgr; did not check whether `repmgr node rejoin` actually succeeded on the demotion candidate, and would always wait up to `node_rejoin_timeout` seconds for it to attach to the promotion candidate, even if this would never happen.

  This makes it easier to identify unexpected events during a switchover operation, such as the demotion candidate being unexpectedly restarted by an external process.

  Note that the output of the `repmgr node rejoin` operation on the demotion candidate will now be logged to a temporary file on that node; the location of the file will be reported in the error message, if one is emitted.

- &repmgrd;: at startup, if node record is marked as "inactive", attempt to set it to "active".

  This behaviour can be overridden by setting the configuration parameter `repmgrd_exit_on_inactive_node` to `true`.

- `repmgr node rejoin`: emit rejoin target note information as `NOTICE`.

  This makes it clearer what &repmgr; is trying to do.

- repmgr node check: option `--repmgrd` added to check &repmgrd; status.

- Add `%p` event notification parameter providing the node ID of the former primary for the `repmgrd_failover_promote` event.

### Bug fixes

- `repmgr standby clone`: if using `--replication-conf-only` on a node which was set up without replication slots, but the &repmgr; configuration was since changed to `use_replication_slots=1`, &repmgr; will now set `slot_name` in the node record, if it was previously empty.

- &repmgrd;: rename internal shared library functions to minimize the risk of clashes with other shared libraries.

  This does not affect user-facing SQL functions. Howe

- &repmgrd;: ensure short option `-s` is accepted.

## Release 5.2.1

Mon 7 December, 2020

&repmgr; 5.2.1 is a minor release.

### Improvements

- repmgr standby clone: option `--recovery-min-apply-delay` added, overriding any setting present in `repmgr.conf`.

### Bug fixes

- Configuration: fix parsing of `replication_type` configuration parameter. GitHub #672.

- repmgr standby clone: handle case where `postgresql.auto.conf` is absent on the source node.

- repmgr standby clone: in PostgreSQL 11 and later, an existing data directory's permissions will not be changed to `0700` if they are already set to `0750`.

- &repmgrd;: prevent termination when local node not available and `standby_disconnect_on_failover` is set. GitHub #675.

- &repmgrd;: ensure `reconnect_interval` is correctly handled. GitHub #673.

- `repmgr witness --help`: fix `witness unregister` description. GitHub #676.

## Release 5.2.0

Thu 22 October, 2020

&repmgr; 5.2.0 is a major release.

This release provides support for PostgreSQL 13, released in September 2020.

This release removes support for PostgreSQL 9.3, which was designated EOL in November 2018.

### General improvements

- Configuration: support `include`, `include_dir` and `include_if_exists` directives (see configuration-file-include-directives).

- `repmgr standby switchover`: Improve sanity check failure log output from the demotion candidate.

  If database connection configuration is not consistent across all nodes, it's possible remote &repmgr; invocations (e.g. during switchover, from the promotion candidate to the demotion candidate) will not be able to connect to the database. This will now be explicitly reported as a database connection failure, rather than as a failure of the respective sanity check.

- repmgr cluster crosscheck / repmgr cluster matrix: improve text mode output format, in particular so that node identifiers of arbitrary length are displayed correctly.

- repmgr primary unregister: the `--force` can be provided to unregister an active primary node, provided it has no registered standby nodes.

- repmgr standby clone: new option `--verify-backup` to run PostgreSQL's pg_verifybackup utility after cloning a standby to verify the integrity of the copied data (PostgreSQL 13 and later).

- repmgr standby clone: when cloning from Barman, setting `--waldir` (PostgreSQL 9.6 and earlier: `--xlogdir`) in `pg_basebackup_options` will cause &repmgr; to create a WAL directory outside of the main data directory and symlink it from there, in the same way as would happen when cloning using pg_basebackup.

- repmgr standby follow: In PostgreSQL 13 and later, a standby no longer requires a restart to follow a new upstream node.

  The old behaviour (always restarting the standby to follow a new node) can be restored by setting the configuration file parameter `standby_follow_restart` to `true`.

- repmgr node rejoin: enable a node to attach to a target node even the target node has a lower timeline (PostgreSQL 9.6 and later).

- repmgr node rejoin: in PostgreSQL 13 and later, support pg_rewind's ability to automatically run crash recovery on a PostgreSQL instance which was not shut down cleanly.

- repmgr node check: option `--db-connection` added to check if &repmgr; can connect to the database on the local node.

- repmgr node check: report database connection error if the `--optformat` was provided.

- Improve handling of pg_control read errors.

- It is now possible to dump the contents of &repmgr; metadata tables with pg_dump.

### repmgrd enhancements

- Following additional parameters can be provided to `failover_validation_command`:

  - `%n`: node ID

  - `%a`: node name

  - `%v`: number of visible nodes

  - `%u`: number of shared upstream nodes

  - `%t`: total number of nodes

- Configuration option `always_promote` (default: `false`) to control whether a node should be promoted if the &repmgr; metadata is not up-to-date on that node.

### Bug fixes

- repmgr standby clone: fix issue with cloning from Barman where the tablespace mapping file was not flushed to disk before attempting to retrieve files from Barman. GitHub #650.

- repmgr node rejoin: ensure that when verifying a standby node has attached to its upstream, the node has started streaming before confirming the success of the rejoin operation.

- &repmgrd;: ensure primary connection is reset if same as upstream. GitHub #633.

## Release 5.1.0

Mon 13 April, 2020

&repmgr; 5.1.0 is a major release.

For details on how to upgrade an existing &repmgr; installation, see documentation section Upgrading a major version release.

If &repmgrd; is in use, a PostgreSQL restart is required; in that case we suggest combining this &repmgr; upgrade with the next PostgreSQL minor release, which will require a PostgreSQL restart in any case.

### Compatibility changes

The `repmgr standby clone` `--recovery-conf-only` option has been renamed to `--replication-conf-only`. `--recovery-conf-only` will still be accepted as an alias.

### General improvements

- The requirement that the &repmgr; user is a database superuser has been removed as far as possible.

  In theory, &repmgr; can be operated with a normal database user for managing the &repmgr; database, and a separate replication user for managing replication connections (and replication slots, if these are in use).

  Some operations will still require superuser permissions, e.g. for issuing a `CHECKPOINT` as par of a switchover operation; in this case a valid superuser should be provided with the `-S`/`--superuser` option.

- `repmgr standby clone`: Warn if neither of data page checksums or `wal_log_hints` are active, as this will preclude later usage of `pg_rewind`.

- `repmgr standby promote`: when executed with `--dry-run`, the method which would be used to promote the node will be displayed.

- `repmgr standby follow`: Improve logging and checking of potential failure situations.

- `repmgr standby switchover`: Replication configuration files (PostgreSQL 11 and earlier: `recovery.conf`; PostgreSQL 12 and later: `postgresql.auto.conf`) will be checked to ensure they are owned by the same user who owns the PostgreSQL data directory.

- `repmgr standby switchover`: Provide additional information in `--dry-run mode` output.

- `repmgr standby switchover`: Checks that the demotion candidate's registered repmgr.conf file can be found, to prevent confusing references to an incorrectly configured data directory. GitHub 615.

- `repmgr node check`: accept option `-S`/`--superuser`. GitHub #621.

- `repmgr node check`: add `--upstream` option to check whether the node is attached to the expected upstream node.

### Bug fixes

- Ensure `repmgr node rejoin` checks for available replication slots on the rejoin target.

- `repmgr standby follow` and `repmgr node rejoin` will now return an error code if the operation fails if a replication slot is not available or cannot be created on the follow/rejoin target.

- `repmgr standby promote`: in `--dry-run mode`, display promote command which will be executed.

- `repmgr standby promote` will check if the `repmgr` user has permission to execute `pg_promote()` and fall back to `pg_ctl promote` if necessary.

- `repmgr standby switchover`: check for demotion candidate reattachment as late as possible to avoid spurious failure reports.

- &repmgrd;: check for presence of `promote_command` and `follow_command` on receipt of `SIGHUP`. GitHub 614.

- Fix situation where replication connections were not created correctly, which could lead to spurious replication connection failures in some situations, e.g. where password files are used.

- Ensure `postgresql.auto.conf` is created with correct permissions (PostgreSQL 12 and later).

## Release 5.0

Tue 15 October, 2019

&repmgr; 5.0 is a major release.

For details on how to upgrade an existing &repmgr; installation, see documentation section Upgrading a major version release.

If &repmgrd; is in use, a PostgreSQL restart is required; in that case we suggest combining this &repmgr; upgrade with the next PostgreSQL minor release, which will require a PostgreSQL restart in any case.

### Compatibility changes

#### Configuration file parsing has been made stricter

&repmgr; now parses configuration files in the same way that PostgreSQL itself does, which means some files used with earlier &repmgr; versions may need slight modification before they can be used with &repmgr; 5 and later.

The main change is that string parameters should always be enclosed in single quotes.

For example, in &repmgr; 4.4 and earlier, the following `repmgr.conf` entry was valid:

    conninfo=host=node1 user=repmgr dbname=repmgr connect_timeout=2

This must now be changed to:

    conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'

Note that simple string identifiers (e.g. `node_name=node1`) may remain unquoted, though we recommend always enclosing strings in single quotes.

Additionally, leading/trailing white space between single quotes will no longer be trimmed; the entire string between single quotes will be taken literally.

Strings enclosed in double quotes (e.g. `node_name="node1"`) will now be rejected; previously they were accepted, but the double quotes were interpreted as part of the string, which was a frequent cause of confusion.

This syntax matches that used by PostgreSQL itself.

#### Some "repmgr daemon ..." commands renamed

Some "`repmgr daemon ...`" commands have been renamed to "`repmgr service ...`" as they have a cluster-wide effect and to avoid giving the impression they affect only the local &repmgr; daemon.

The following commands are affected:

- `repmgr daemon pause` (now `repmgr service pause`)

- `repmgr daemon unpause` (now `repmgr service unpause`)

- `repmgr daemon status` (now `repmgr service status`)

The "`repmgr daemon ...`" form will still be accepted for backwards compatibility.

#### Some deprecated command line options removed

The following command line options, which have been deprecated since &repmgr; 3.3 (and which no longer had any effect other than to generate a warning about their use) have been removed:

- `--data-dir`

- `--no-conninfo-password`

- `--recovery-min-apply-delay`

### General enhancements

- Support for PostgreSQL 12 added.

  Beginning with PostgreSQL 12, replication configuration has been integrated into the main PostgreSQL configuraton system and the conventional `recovery.conf` file is no longer valid.

  &repmgr; has been modified to be compatible with this change.

  &repmgr; additionally takes advantage of the new `pg_promote()` function, which enables a standby to be promoted to primary using an SQL command.

  For an overview of general changes to replication configuration, see this blog entry: Replication configuration changes in PostgreSQL 12

- The &repmgr; configuration file is now parsed using `flex`, meaning it will be parsed in the same way as PostgreSQL parses its own configuration files.

  This makes configuration file parsing more robust and consistent.

  See item Configuration file parsing has been made stricter for details.

- `repmgr standby clone`: checks for availability of the &repmgr; extension on the upstream node have been improved and error messages improved.

- When executing &repmgr; remotely, if the &repmgr; log level was explicitly provided (with `-L`/`--log-level`), that log level will be passed to the remote &repmgr;.

  This makes it possible to return log output when executing repmgr remotely at a different level to the one defined in the remote &repmgr;'s `repmgr.conf`.

  This is particularly useful when `DEBUG` output is required.

### Bug fixes

- Check role membership when trying to read `pg_settings`.

  Previously &repmgr; assumed only superusers could read `pg_settings`, but from PostgreSQL 10, all members of the roles `pg_read_all_settings` or `pg_monitor` are permitted to do this as well.

- &repmgrd;: Fix handling of upstream node change check.

  &repmgrd; has a check to see if the upstream node has unexpectedly changed, e.g. if the repmgrd service is paused and the PostgreSQL instance has been pointed to another node.

  However this check was relying on the node record on the local node being up-to-date, which may not be the case immediately after a failover, when the node is still replaying records updated prior to the node's own record being updated. In this case it will mistakenly assume the node is following the original primary and attempt to restart monitoring, which will fail as the original primary is no longer available.

  To prevent this, the node's record on the upstream node is checked to see if the reported upstream `node_id` matches the expected `node_id`. GitHub #587/#588.

## Release 4.4

Thu 27 June, 2019

&repmgr; 4.4 is a major release.

For details on how to upgrade an existing &repmgr; installation, see documentation section Upgrading a major version release.

If &repmgrd; is in use, a PostgreSQL restart is required; in that case we suggest combining this &repmgr; upgrade with the next PostgreSQL minor release, which will require a PostgreSQL restart in any case.

On Debian-based systems, including Ubuntu, if using &repmgrd; please ensure that in the file `/etc/init.d/repmgrd`, the parameter `REPMGRD_OPTS` contains "`--daemonize=false`", e.g.:

    # additional options
    REPMGRD_OPTS="--daemonize=false"

For further details, see repmgrd configuration on Debian/Ubuntu.

### repmgr client enhancements

- `repmgr standby clone`: prevent a standby from being cloned from a witness server (PostgreSQL 9.6 and later only).

- `repmgr witness register`: prevent a witness server from being registered on the replication cluster primary server (PostgreSQL 9.6 and later only).

  Registering a witness on the primary node would defeat the purpose of having a witness server, which is intended to remain running even if the cluster's primary goes down.

- `repmgr standby follow`: note that an active, reachable cluster primary is required for this command; and provide a more helpful error message if no reachable primary could be found.

- &repmgr;: when executing `repmgr standby switchover`, if `--siblings-follow` is not supplied, list all nodes which repmgr considers to be siblings (this will include the witness server, if in use), and which will remain attached to the old primary.

- &repmgr;: when executing `repmgr standby switchover`, ignore nodes which are unreachable and marked as inactive. Previously it would abort if any node was unreachable, as that means it was unable to check if repmgrd is running.

  However if the node has been marked as inactive in the repmgr metadata, it's reasonable to assume the node is no longer part of the replication cluster and does not need to be checked.

- `repmgr standby switchover` and `repmgr standby promote`: when executing with the `--dry-run` option, continue checks as far as possible even if errors are encountered.

- `repmgr standby promote`: add `--siblings-follow` (similar to `repmgr standby switchover`).

  If using &repmgrd;, when invoking `repmgr standby promote` (either directly via the `promote_command`, or in a script called via `promote_command`), `--siblings-follow` must not be included as a command line option for `repmgr standby promote`.

- `repmgr standby switchover`: add `--repmgrd-force-unpause` to unpause all &repmgrd; instances after executing a switchover. This will ensure that any &repmgrd; instances which were paused before the switchover will be unpaused.

- `repmgr daemon status`: make output similar to that of `repmgr cluster show` for consistency and to make it easier to identify nodes not in the expected state.

- `repmgr cluster show`: display each node's timeline ID (PostgreSQL 9.6 and later only).

- `repmgr cluster show` and `repmgr daemon status`: show the upstream node name as reported by each individual node - this helps visualise situations where the cluster is in an unexpected state, and provide a better idea of the actual cluster state.

  For example, if a cluster has divided somehow and a set of nodes are following a new primary, when running either of these commands, &repmgr; will now show the name of the primary those nodes are actually following, rather than the now outdated node name recorded on the other side of the "split". A warning will also be issued about the unexpected situation.

- `repmgr cluster show` and `repmgr daemon status`: check if a node is attached to its advertised upstream node, and issue a warning if the node is not attached.

### repmgrd enhancements

- On the primary node, &repmgrd; is now able to monitor standby connections and, if the number of nodes connected falls below a certain (configurable) value, execute a custom script.

  This provided an additional method for fencing an isolated primary node, and/or taking other action if one or more standys become disconnected.

  See section Monitoring standby disconnections on the primary node for more details.

- In a failover situation, &repmgrd; nodes on the standbys of the failed primary are now able confirm among themselves that none can still see the primary before continuing with the failover.

  The `repmgr.conf` option `primary_visibility_consensus` must be set to `true` to enable this functionality.

  See section repmgrd-primary-visibility-consensus for more details.

### Bug fixes

- Ensure BDR2-specific functionality cannot be used on BDR3 and later.

  The BDR support present in &repmgr; is for specific BDR2 use cases.

- &repmgr;: when executing `repmgr standby clone` in `--dry-run` mode, ensure provision of the `--force` option does not result in an existing data directory being modified in any way.

- &repmgr;: when executing `repmgr primary register` with the `--force` option, if another primary record exists but the associated node is unreachable (or running as a standby), set that node's record to inactive to enable the current node to be registered as a primary.

- &repmgr;: when executing `repmgr standby clone` with the `--upstream-conninfo`, ensure that `application_name` is set correctly in `primary_conninfo`.

- &repmgr;: when executing `repmgr standby switchover`, don't abort if one or more nodes are not reachable and they are marked as inactive.

- &repmgr;: canonicalize the data directory path when parsing the configuration file, so the provided path matches the path PostgreSQL reports as its data directory. Otherwise, if e.g. the data directory is configured with a trailing slash, `repmgr node check --data-directory-config` will return a spurious error.

- &repmgrd;: fix memory leak which occurs while the monitored PostgreSQL node is not running.

### Other

- The &repmgr; documentation has been converted to DocBook XML format, as currently used by the main PostgreSQL project. This means it can now be built against any PostgreSQL version from 9.5 (previously it was not possible to build the documentation against PostgreSQL 10 or later), and makes it easier to provide the documentation in other formats such as PDF.

  For further details see: installation-build-repmgr-docs

## Release 4.3

Tue April 2, 2019

&repmgr; 4.3 is a major release.

For details on how to upgrade an existing &repmgr; installation, see documentation section Upgrading a major version release.

If &repmgrd; is in use, a PostgreSQL restart is required; in that case we suggest combining this &repmgr; upgrade with the next PostgreSQL minor release, which will require a PostgreSQL restart in any case.

On Debian-based systems, including Ubuntu, if using &repmgrd; please ensure that in the file `/etc/init.d/repmgrd`, the parameter `REPMGRD_OPTS` contains "`--daemonize=false`", e.g.:

    # additional options
    REPMGRD_OPTS="--daemonize=false"

For further details, see repmgrd configuration on Debian/Ubuntu.

### repmgr client enhancements

- `repmgr standby follow`: option `--upstream-node-id` can now be used to specify another standby to follow.

- `repmgr standby follow`: verify that it is actually possible to follow another node.

- `repmgr node rejoin`: verify that it is actually possible to attach the node to the current primary.

- New commands `repmgr daemon start` and `repmgr daemon stop`: these provide a standardized way of starting and stopping &repmgrd;. GitHub #528.

  These commands require the configuration file settings `repmgrd_service_start_command` and `repmgrd_service_stop_command` in `repmgr.conf` to be set.

- `repmgr daemon status` additionally displays the node priority and the interval (in seconds) since the &repmgrd; instance last verified its upstream node was available.

- Add `--compact` option to `repmgr cluster show` (GitHub #521).

  This makes it easier to copy the output into emails, chats etc. as a compact table.

- `repmgr cluster show`: differentiate between unreachable nodes and nodes which are running but rejecting connections.

  This makes it possible to see whether a node is unreachable at network level, or if it is running but rejecting connections for some reason.

- Add `--dry-run` to `repmgr standby promote` (GitHub #522).

- `repmgr --version-number` outputs the "raw" repmgr version number (e.g. `40300`). This is intended for use by scripts etc. requiring an easily parseable representation of the &repmgr; version.

- `repmgr node check --data-directory-config` option added; this is to confirm &repmgr; is correctly configured. GitHub #523.

- Add check to `repmgr standby switchover` to ensure the data directory on the demotion candidate is configured correctly in `repmgr.conf`. This is to ensure that &repmgr;, when remotely executed on the demotion candidate, can correctly verify that PostgreSQL on the demotion candidate was shut down cleanly. GitHub #523.

### repmgrd enhancements

- &repmgrd; will no longer consider nodes where &repmgrd; is not running as promotion candidates.

  Previously, if &repmgrd; was not running on a node, but that node qualified as the promotion candidate, it would never be promoted due to the absence of a running &repmgrd;.

- Add option `connection_check_type` to enable selection of the method &repmgrd; uses to determine whether the upstream node is available.

  Possible values are `ping` (default; uses `PQping()` to determine server availability), `connection` (attempts to make a new connection to the upstream node), and `query` (determines server availability by executing an SQL statement on the node via the existing connection).

- New configuration option `failover_validation_command` to allow an external mechanism to validate the failover decision made by &repmgrd;.

- New configuration option `standby_disconnect_on_failover` to force standbys to disconnect their WAL receivers before making a failover decision.

- In a failover situation, &repmgrd; will not attempt to promote a node if another primary has already appeared (e.g. by being promoted manually). GitHub #420.

### Bug fixes

- `repmgr cluster show`: fix display of node IDs with multiple digits.

- ensure `repmgr primary unregister` behaves correctly when executed on a witness server. GitHub #548.

- ensure `repmgr standby register` fails when `--upstream-node-id` is the same as the local node ID.

- &repmgr;: when executing `repmgr standby clone`, recheck primary/upstream connection(s) after the data copy operation is complete, as these may have gone away.

- &repmgr;: when executing `repmgr standby switchover`, prevent escaping issues with connection URIs when executing `repmgr node rejoin` on the demotion candidate. GitHub #525.

- &repmgr;: when executing `repmgr standby switchover`, verify the standby (promotion candidate) is currently attached to the primary (demotion candidate). GitHub #519.

- &repmgr;: when executing `repmgr standby switchover`, avoid a potential race condition when comparing received WAL on the standby to the primary's shutdown location, as the standby's walreceiver may not have yet flushed all received WAL to disk. GitHub #518.

- &repmgr;: when executing `repmgr witness register`, check the node to connected is actually the primary (i.e. not the witness server). GitHub #528.

- `repmgr node check` will only consider physical replication slots, as the purpose of slot checks is to warn about potential issues with streaming replication standbys which are no longer attached.

- &repmgrd;: on a cascaded standby, don't fail over if `failover=manual`. GitHub #531.

## Release 4.2

Wed October 24, 2018

&repmgr; 4.2 is a major release, with the main new feature being the ability to pause repmgrd, e.g. during planned maintenance operations. Various other usability enhancements and a couple of bug fixes are also included; see notes below for details.

A restart of the PostgreSQL server is required for this release. For detailed upgrade instructions, see Upgrading a major version release.

On Debian-based systems, including Ubuntu, if using &repmgrd; please ensure that the in the file `/etc/init.d/repmgrd`, the parameter `REPMGRD_OPTS` contains "`--daemonize=false`", e.g.:

    # additional options
    REPMGRD_OPTS="--daemonize=false"

For further details, see repmgrd daemon configuration on Debian/Ubuntu.

### Configuration file changes

- New parameter `shutdown_check_timeout` (default: 60 seconds) added; this provides an explicit timeout for `repmgr standby switchover` to check that the demotion candidate (current primary) has shut down. Previously, the parameters `reconnect_attempts` and `reconnect_interval` were used to calculate a timeout, but these are actually intended for primary failure detection. (GitHub #504).

- New parameter `repmgr_bindir` added, to facilitate remote invocation of repmgr when the repmgr binary is located somewhere other than the PostgreSQL binary directory, as it cannot be assumed all package maintainers will install &repmgr; there.

  This parameter is optional; if not set (the default), &repmgr; will fall back to `pg_bindir` (if set).

  (GitHub #246).

### repmgr enhancements

- `repmgr cluster cleanup` now accepts the `--node-id` option to delete records for only one node. (GitHub #493).

- When running `repmgr cluster matrix` and `repmgr cluster crosscheck`, &repmgr; will report nodes unreachable via SSH, and emit return code `ERR_BAD_SSH`. (GitHub #246).

  Users relying on `repmgr cluster crosscheck` to return a non-zero return code as a way of detecting connectivity errors should be aware that `ERR_BAD_SSH` will be returned if there is an SSH connection error from the node where the command is executed, even if the command is able to establish that PostgreSQL connectivity is fine. Therefore the exact return code should be checked to determine what kind of connectivity error has been detected.

### repmgrd enhancements

- &repmgrd; can now be "paused", i.e. instructed not to take any action such as a failover, even if the prerequisites for such an action are detected.

  This removes the need to stop &repmgrd; on all nodes when performing a planned operation such as a switchover.

  For further details, see Pausing repmgrd.

### Bug fixes

- &repmgr;: fix "Missing replication slots" label in `repmgr node check`. (GitHub #507)

- &repmgrd;: fix parsing of `-d/--daemonize` option.

## Release 4.1.1

Wed September 5, 2018

repmgr 4.1.1 contains a number of usability enhancements and bug fixes.

We recommend upgrading to this version as soon as possible. This release can be installed as a simple package upgrade from repmgr 4.0 ~ 4.1.0; &repmgrd; (if running) should be restarted. See upgrading-repmgr for more details.

### repmgr enhancements

- `repmgr standby switchover --dry-run` no longer copies external configuration files to test they can be copied; this avoids making any changes to the target system. (GitHub #491).

- `repmgr cluster cleanup`: add `cluster_cleanup` event. (GitHub #492).

- `repmgr standby switchover`: improve detection of free walsenders. (GitHub #495).

- Improve messages emitted during `repmgr standby promote`.

### repmgrd enhancements

- Always reopen the log file after receiving `SIGHUP`. Previously this only happened if a configuration file change was detected. (GitHub #485).

- Report version number after logger initialisation. (GitHub #487).

- Improve cascaded standby failover handling. (GitHub #480).

- Improve reconnection handling after brief network outages; if monitoring data being collected, this could lead to orphaned sessions on the primary. (GitHub #480).

- Check `promote_command` and `follow_command` are defined when reloading configuration. These were checked on startup but not reload by &repmgrd;, which made it possible to make &repmgrd; with invalid values. It's unlikely anyone would want to do this, but we should make it impossible anyway. (GitHub #486).

### Other

- Text of any failed queries will now be logged as `ERROR` to assist logfile analysis at log levels higher than `DEBUG`. (GitHub #498).

### Bug fixes

- `repmgr node rejoin`: remove new upstream's replication slot if it still exists on the rejoined standby. (GitHub #499).

- &repmgrd;: fix startup on witness node when local data is stale. (GitHub #488, #489).

- Truncate version string reported by PostgreSQL if necessary; some distributions insert additional detail after the actual version. (GitHub #490).

## Release 4.1.0

Tue July 31, 2018

&repmgr; 4.1.0 introduces some changes to &repmgrd; behaviour and some additional configuration parameters.

This release can be installed as a simple package upgrade from repmgr 4.0 ~ 4.0.6. The following post-upgrade steps must be carried out:

- Execute `ALTER EXTENSION repmgr UPDATE` on the primary server in the database where &repmgr; is installed.

- &repmgrd; must be restarted on all nodes where it is running.

A restart of the PostgreSQL server is not required for this release (unless upgrading from repmgr 3.x).

See upgrading-repmgr-extension for more details.

Configuration changes are backwards-compatible and no changes to `repmgr.conf` are required. However users should review the changes listed below.

Repository changes

Coinciding with this release, the 2ndQuadrant repository structure has changed. See section installation-packages for details, particularly if you are using a RPM-based system.

### Configuration file changes

- Default for repmgr-conf-log-level is now `INFO`. This produces additional informative log output, without creating excessive additional log file volume, and matches the setting assumed for examples in the documentation. (GitHub #470).

- `recovery_min_apply_delay` now accepts a minimum value of `zero` (GitHub #448).

### repmgr enhancements

- repmgr: always exit with an error if an unrecognised command line option is provided. This matches the behaviour of other PostgreSQL utilities such as psql. (GitHub #464).

- repmgr: add `-q/--quiet` option to suppress non-error output. (GitHub #468).

- `repmgr cluster show`, `repmgr node check` and `repmgr node status` return non-zero exit code if node status issues detected. (GitHub #456).

- Add `--csv` output option for `repmgr cluster event`. (GitHub #471).

- `repmgr witness unregister` can be run on any node, by providing the ID of the witness node with `--node-id`. (GitHub #472).

- `repmgr standby switchover` will refuse to run if an exclusive backup is taking place on the current primary. (GitHub #476).

### repmgrd enhancements

- &repmgrd;: create a PID file by default (GitHub #457). For details, see repmgrd-pid-file.

- &repmgrd;: daemonize process by default. In case, for whatever reason, the user does not wish to daemonize the process, provide `--daemonize=false`. (GitHub #458).

### Bug fixes

- `repmgr standby register --wait-sync`: fix behaviour when no timeout provided.

- `repmgr cluster cleanup`: add missing help options. (GitHub #461/#462).

- Ensure witness node follows new primary after switchover. (GitHub #453).

- `repmgr node check` and `repmgr node status`: fix witness node handling. (GitHub #451).

- When using `repmgr standby clone` with `--recovery-conf-only` and replication slots, ensure `primary_slot_name` is set correctly. (GitHub #474).

## Release 4.0.6

Thu June 14, 2018

&repmgr; 4.0.6 contains a number of bug fixes and usability enhancements.

We recommend upgrading to this version as soon as possible. This release can be installed as a simple package upgrade from repmgr 4.0 ~ 4.0.5; &repmgrd; (if running) should be restarted. See upgrading-repmgr for more details.

### Usability enhancements

- `repmgr cluster crosscheck` and `repmgr cluster matrix`: return non-zero exit code if node connection issues detected (GitHub #447)

- `repmgr standby clone`: Improve handling of external configuration file copying, including consideration in `--dry-run` check (GitHub #443)

- When using `--dry-run`, force log level to `INFO` to ensure output will always be displayed (GitHub #441)

- `repmgr standby clone`: Improve documentation of `--recovery-conf-only` mode (GitHub #438)

- `repmgr standby clone`: Don't require presence of `user` parameter in conninfo string (GitHub #437)

### Bug fixes

- `repmgr witness register`: prevent registration of a witness server with the same name as an existing node

- `repmgr standby follow`: check node has actually connected to new primary before reporting success (GitHub #444)

- `repmgr node rejoin`: Fix bug when parsing `--config-files` parameter (GitHub #442)

- &repmgrd;: ensure local node is counted as quorum member (GitHub #439)

## Release 4.0.5

Wed May 2, 2018

&repmgr; 4.0.5 contains a number of usability enhancements related to pg_rewind usage, `recovery.conf` generation and (in &repmgrd;) handling of various corner-case situations, as well as a number of bug fixes.

### Usability enhancements

- Various documentation improvements, with particular emphasis on the importance of setting appropriate service commands instead of relying on pg_ctl.

- Poll demoted primary after restart as a standby during a switchover operation (GitHub #408).

- Add configuration parameter `config_directory` (GitHub #424).

- Add sanity check if `--upstream-node-id` not supplied when executing repmgr-standby-register (GitHub #395).

- Enable pg_rewind to be used with PostgreSQL 9.3/9.4 (GitHub #413).

- When generating replication connection strings, set `dbname=replication` if appropriate (GitHub #421).

- Enable provision of `archive_cleanup_command` in `recovery.conf` (GitHub #416).

- Actively check for node to rejoin cluster (GitHub #415).

- &repmgrd;: set `connect_timeout=2` (if not explicitly set) when pinging a server.

### Bug fixes

- Fix display of conninfo parsing error messages.

- Fix minimum accepted value for `degraded_monitoring_timeout` (GitHub #411).

- Fix superuser password handling (GitHub #400)

- Fix parsing of `archive_ready_critical` configuration file parameter (GitHub #426).

- Fix `repmgr cluster crosscheck` output (GitHub #389)

- Fix memory leaks in witness code (GitHub #402).

- &repmgrd;: handle `pg_ctl promote` timeout (GitHub #425).

- &repmgrd;: handle failover situation with only two nodes in the primary location, and at least one node in another location (GitHub #407).

- &repmgrd;: prevent standby connection handle from going stale.

## Release 4.0.4

Fri Mar 9, 2018

&repmgr; 4.0.4 contains some bug fixes and and a number of usability enhancements related to logging/diagnostics, event notifications and pre-action checks.

This release can be installed as a simple package upgrade from repmgr 4.0 ~ 4.0.3; &repmgrd; (if running) should be restarted. See upgrading-repmgr for more details.

It is not possible to perform a switchover where the demotion candidate is running &repmgr; 4.0.2 or lower; all nodes should be upgraded to the latest version (4.0.4). This is due to additional checks introduced in 4.0.3 which require the presence of 4.0.3 or later versions on all nodes.

### Usability enhancements

- add `repmgr standby clone --recovery-conf-only` option to enable integration of a standby cloned from another source into a &repmgr; cluster (GitHub #382)

- remove restriction on using replication slots when cloning from a Barman server (GitHub #379)

- make `repmgr standby promote` timeout values configurable (GitHub #387)

- add missing options to main `--help` output (GitHub #391, #392)

### Bug fixes

- ensure `repmgr node rejoin` honours the `--dry-run` option (GitHub #383)

- improve replication slot warnings generated by `repmgr node status` (GitHub #385)

- fix --superuser handling when cloning a standby (GitHub #380)

- &repmgrd;: improve detection of status change from primary to standby

- &repmgrd;: improve reconnection to the local node after a failover (previously a connection error due to the node starting up was being interpreted as the node being unavailable)

- &repmgrd;: when running on a witness server, correctly connect to new primary after a failover

- &repmgrd;: add event notification `repmgrd_shutdown` (GitHub #393)

## Release 4.0.3

Thu Feb 15, 2018

&repmgr; 4.0.3 contains some bug fixes and and a number of usability enhancements related to logging/diagnostics, event notifications and pre-action checks.

This release can be installed as a simple package upgrade from repmgr 4.0 ~ 4.0.2; repmgrd (if running) should be restarted.

It is not possible to perform a switchover where the demotion candidate is running &repmgr; 4.0.2 or lower; all nodes should be upgraded to 4.0.3. This is due to additional checks introduced in 4.0.3 which require the presence of 4.0.3 or later versions on all nodes.

### Usability enhancements

- improve `repmgr standby switchover` behaviour when `pg_ctl` is used to control the server and logging output is not explicitly redirected

- improve `repmgr standby switchover` log messages and provide new exit code `ERR_SWITCHOVER_INCOMPLETE` when old primary could not be shut down cleanly

- add check to verify the demotion candidate can make a replication connection to the promotion candidate before executing a switchover (GitHub #370)

- add check for sufficient walsenders and replication slots on the promotion candidate before executing `repmgr standby switchover` (GitHub #371)

- add --dry-run mode to `repmgr standby follow` (GitHub #368)

- provide information about the primary node for `repmgr standby register` and `repmgr standby follow` event notifications (GitHub #375)

- add `standby_register_sync` event notification, which is fired when `repmgr standby register` is run with the `--wait-sync` option and the new or updated standby node record has synchronised to the standby (GitHub #374)

- when running `repmgr cluster show`, if any node is unreachable, output the error message encountered in the list of warnings (GitHub #369)

### Bug fixes

- ensure an inactive data directory can be overwritten when cloning a standby (GitHub #366)

- `repmgr node status` upstream node display fixed (GitHub #363)

- `repmgr primary unregister`: clarify usage and fix `--help` output (GitHub #373)

- parsing of `pg_basebackup_options` fixed (GitHub #376)

- ensure the `pg_subtrans` directory is created when cloning a standby in Barman mode

- `repmgr witness register`: fix primary node check (GitHub #377).

## Release 4.0.2

Thu Jan 18, 2018

&repmgr; 4.0.2 contains some bug fixes and small usability enhancements.

This release can be installed as a simple package upgrade from &repmgr; 4.0.1 or 4.0; &repmgrd; (if running) should be restarted.

### Usability enhancements

- Recognize the `-t`/`--terse` option for `repmgr cluster event` to hide the `Details` column (GitHub #360)

- Add "--wait-start" option for `repmgr standby register` (GitHub #356)

- Add `%p` event notification parameter for `repmgr standby switchover`

### Bug fixes

- Add missing -W option to `getopt_long()` invocation (GitHub #350)

- Automatically create slot name if missing (GitHub #343)

- Fixes to parsing output of remote repmgr invocations (GitHub #349)

- When registering BDR nodes, automatically create missing connection replication set (GitHub #347)

- Handle missing node record in `repmgr node rejoin` (GitHub #358)

### Documentation

- The documentation can now be built as a single HTML file (GitHub pull request #353)

## Release 4.0.1

Wed Dec 13, 2017

&repmgr; 4.0.1 is a bugfix release.

### Bug fixes

- ensure correct return codes are returned for `repmgr node check --action=` operations (GitHub #340)

- Fix repmgr-cluster-show when `repmgr` schema not set in search path (GitHub #341)

- When using `--force-rewind` with repmgr-node-rejoin delete any replication slots copied by pg_rewind (GitHub #334)

- Only perform sanity check on accessibility of configuration files outside the data directory when `--copy-external-config-files` provided (GitHub #342)

- Initialise "voting_term" table in application, not extension SQL (GitHub #344)

## Release 4.0.0

Tue Nov 21, 2017

repmgr 4.0 is an entirely new version of &repmgr;, implementing &repmgr; as a native PostgreSQL extension, adding new and improving existing features, and making &repmgr; more user-friendly and intuitive to use. The new code base will make it easier to add additional functionality for future releases.

With the new version, the opportunity has been taken to make some changes in the way &repmgr; is set up and configured. In particular changes have been made to some configuration file settings consistency for and clarity. Changes are covered in detail below

To standardise terminology, from this release `primary` is used to denote the read/write node in a streaming replication cluster. `master` is still accepted as an alias for &repmgr; commands (e.g. `repmgr master register`).

For detailed instructions on upgrading from repmgr 3.x, see upgrading-from-repmgr-3.

### Features and improvements

- improved switchover: the `switchover` process has been improved and streamlined, speeding up the switchover process and can also instruct other standbys to follow the new primary once the switchover has completed. See performing-switchover for more details.

- "--dry-run" option: many &repmgr; commands now provide a `--dry-run` option which will execute the command as far as possible without making any changes, which will enable possible issues to be identified before the intended operation is actually carried out.

- easier upgrades: &repmgr; is now implemented as a native PostgreSQL extension, which means future upgrades can be carried out by installing the upgraded package and issuing ALTER EXTENSION repmgr UPDATE.

- improved logging output: &repmgr; (and &repmgrd;) now provide more explicit logging output giving a better picture of what is going on. Where appropriate, `DETAIL` and `HINT` log lines provide additional detail and suggestions for resolving problems. Additionally, &repmgrd; now emits informational log lines at regular, configurable intervals to confirm that it's running correctly and which node(s) it's monitoring.

- automatic configuration file location in packages: Many operating system packages place the &repmgr; configuration files in a version-specific subdirectory, e.g. `/etc/repmgr/9.6/repmgr.conf`; &repmgr; now makes it easy for package maintainers to provide a patch with the actual file location, meaning `repmgr.conf` does not need to be provided explicitly. This is currently the case for 2ndQuadrant-provided `.deb` and `.rpm` packages.

- monitoring and status checks: New commands repmgr-node-check and repmgr-node-status providing information about a node's status and replication-related monitoring output.

- node rejoin: New commands repmgr-node-rejoin enables a failed primary to be rejoined to a replication cluster, optionally using pg_rewind to synchronise its data, (note that pg_rewind may not be useable in some circumstances).

- automatic failover: improved detection of node status; promotion decision based on a consensual model, with the promoted primary explicitly informing other standbys to follow it. The &repmgrd; daemon will continue functioning even if the monitored PostgreSQL instance is down, and resume monitoring if it reappears. Additionally, if the instance's role has changed (typically from a primary to a standby, e.g. following reintegration of a failed primary using repmgr-node-rejoin) &repmgrd; will automatically resume monitoring it as a standby.

- new documentation: the existing documentation spread over multiple text files has been consolidated into DocBook format (as used by the main PostgreSQL project) and is now available online in HTML format.

  The DocBook files can easily be used to create versions of the documentation in other formats such as PDF.

### New command line options

- `--dry-run`: &repmgr; will attempt to perform the action as far as possible without making any changes to the database

- `--upstream-node-id`: use to specify the upstream node the standby will connect later stream from, when cloning and registering a standby.

  This replaces the configuration file parameter `upstream_node`. as the upstream node is set when the standby is initially cloned, but can change over the lifetime of an installation (due to failovers, switchovers etc.) so it's pointless/confusing keeping the original value around in `repmgr.conf`.

### Changed command line options

repmgr

- `--replication-user` has been deprecated; it has been replaced by the configuration file option `replication_user`. The value (which defaults to the user provided in the `conninfo` string) will be stored in the &repmgr; metadata for use by repmgr-standby-clone and repmgr-standby-follow.

- `--recovery-min-apply-delay` is now a configuration file parameter `recovery_min_apply_delay`, to ensure the setting does not get lost when a standby follows a new upstream.

- `--no-conninfo-password` is deprecated; a password included in the environment variable `PGPASSWORD` will no longer be added to `primary_conninfo` by default; to force the inclusion of a password (not recommended), use the new configuration file parameter `use_primary_conninfo_password`. For details, ee section cloning-advanced-managing-passwords.

&repmgrd;

- `--monitoring-history` is deprecated and is replaced by the configuration file option `monitoring_history`. This enables the setting to be changed without having to modify system service files.

### Configuration file changes

Required settings

The following 4 parameters are mandatory in `repmgr.conf`:

- node_id

- node_name

- conninfo

- data_directory

Renamed settings

Some settings have been renamed for clarity and consistency:

- `node` is now `node_id`

- `name` is now `node_name`

- `barman_server` is now `barman_host`

- `master_reponse_timeout` is now `async_query_timeout` (to better indicate its purpose)

The following configuration file parameters have been renamed for consistency with other parameters (and conform to the pattern used by PostgreSQL itself, which uses the prefix `log_` for logging parameters):

- `loglevel` is now `log_level`

- `logfile` is now `log_file`

- `logfacility` is now `log_facility`

Removed settings

- `cluster` has been removed

- `upstream_node` - see note about `--upstream-node-id` above

- `retry_promote_interval_secs`this is now redundant due to changes in the failover/promotion mechanism; the new equivalent is `primary_notification_timeout`

Logging changes

- default value for `log_level` is `INFO` rather than `NOTICE`.

- new parameter `log_status_interval`, which causes &repmgrd; to emit a status log line at the specified interval

### repmgrd

The shared library has been renamed from `repmgr_funcs` to `repmgr`, meaning `shared_preload_libraries` in `postgresql.conf` needs to be updated to the new name:

            shared_preload_libraries = 'repmgr'