repmgr - Replication Manager for PostgreSQL

repmgr 3.2 released

What is repmgr?

repmgr is an open source package which greatly simplifies the process of setting up and managing replication using streaming replication within a cluster of PostgreSQL servers. Taking advantage of features introduced since PostgreSQL 9.3, repmgr builds on PostgreSQL's core functionality to provide a smooth, user-friendly way of working with the complexities of replication and failover management in high-availability environments.

repmgr consists of two core tools - the repmgr command line interface, which provides functionality for adminstering replication such as cloning standby servers, and repmgrd, a background daemon which monitors nodes in a replication cluster and provides automatic failover support.

The latest repmgr major version, 3.2, provides support for 2ndQuadrant’s Barman archive management server, additional cluster monitoring functionality and several improvements to the standby cloning process.

Note that repmgr 3.2 supports PostgreSQL 9.3 and later only.

2ndQuadrant provides professional support services for repmgr - see our website for details.

New features in repmgr 3.2

Barman support

repmgr 3.2 provides enhanced integration with 2ndQuadrant's Barman backup and recovery manager. In particular it is now possible to clone a standby from a Barman archive, rather than directly from a running database server. This means the server is not subjected to the I/O load caused by a backup, and there's no need to manage WAL retention on the database server. The standby can also use the Barman archive as a fallback source of WAL in case streaming replication is interrupted.

Replication cluster monitoring

Particularly with more complex replication clusters spread over multiple locations, gaining an overview of connection status between nodes can be a tedious and time-consuming process. repmgr 3.2 provides two new commands which help with this, expanding the existing repmgr cluster show:

• repmgr cluster matrix which runs cluster show on each node and arranges the results in a matrix, recording success or failure, showing the state of the cluster as seen from the executing node.
• repmgr cluster crosscheck which runs cluster matrix on each node and combines the results in a single matrix, providing a full overview of connections between all databases in the cluster.

See the README file for a more in-depth explanation with examples.

Standby cloning improvements

In addition to the ability to clone directly from a Barman archive, various other improvements have been made to the standby cloning process. In particular, by default password-less SSH connection between servers is now optional and only needs to be provided for specific features.

• By default cloning will be carried out with pg_basebackup's --xlog-method set to stream - this ensures that WAL files are copied while the backup is being taken, rather than fetched afterwards (when required files may already have been removed). This option can be overridden by adding --xlog-method=fetch to pg_basebackup_options in repmgr.conf.
• Before starting the cloning process using the default pg_basebackup method, repmgr will check that the required number of free walsenders are available (normally two unless --xlog-method=fetch was explicitly specified).
• wal_keep_segments no longer needs to be set on the server being cloned, except in the following circumstances:
  • pg_basebackup_options in repmgr.conf includes the setting --xlog-method=fetch and has not been set restore_command in repmgr.conf.
  • the standby is being cloned with rsync
• It's now possible to clone from a different server to the one defined in as the node's upstream in repmgr.conf, as long as the upstream node is already registered.
• Copying of configuration files outside the data directory now only takes place if the option --copy-external-config-files is provided - this required password-less SSH connections between servers and in contrast to previous repmgr is therefore now optional. If used, by default all configuration files detected will be copied to the same path on the standby server as on the original server; specify --copy-external-config-files=pgdata to copy them into the data directory.

Better integration of OS level server commands

By default, repmgr.conf will use PostgreSQL's standard pg_ctl utility to control a running PostgreSQL server. However it may be better to use the operating system's service management system, e.g. systemd. To specify which service control commands are used, the following repmgr.conf configuration settings are available:

• service_start_command
• service_stop_command
• service_restart_command
• service_reload_command
• service_promote_command

Other new commands and options

The option --wait-sync can be provided to standby register, which causes repmgr to wait for the node record of the standby just registered node to synchronise to the standby. This is necessary for e.g. repmgrd to start, but can take some time if the master node is busy,

Better control over witness server management is provided with the new commands witness register and witness unregister. witness register can be used to set up an existing database instance as a witness server (as before, witness creare will both create and register the witness server).

standby unregister and witness unregister can be executed for a node which is not running by providing the --node parameter with the id of the node to be unregistered.

Other improvements

repmgrd will no longer start on a server which is marked as inactive, if repmgrd's failover mode is set to automatic. This prevents situations where a failed node has been re-cloned but not re-registered, if repmgrd is running it would not treat the node as a promotion candidate during automatic failover.

Upgrading from older repmgr versions

Upgrading from repmgr 3.1.2 ~ 3.1.5

repmgr 3.2 can simply be installed in place of the existing repmgr 3.1.2, repmgr 3.1.3, repmgr 3.1.4 or repmgr 3.1.5 version.

If repmgrd is running, stop and restart the service to ensure it is running with the current repmgr version.

Upgrading from repmgr 3.1.1 or 3.1

To upgrade from repmgr 3.1.1 or repmgr 3.1 version, install repmgr 3.1.5 from your operating system's packaging system or from source, then perform following tasks:

• Run the provided repmgr database upgrade script, repmgr3.1.1_repmgr3.1.2.sql. This makes a small modification to the repl_nodes table's foreign key definition.
• If repmgrd is running, stop and restart the service to ensure it is running with the current repmgr version.

Upgrading from repmgr 3.0

repmgr 3.2 is a drop-in replacement for an existing repmgr 3.0 installation. It should be installed first, either from your operating system's packaging system or from source, then following tasks performed:

• Run the provided repmgr database upgrade script, sql/repmgr3.0_repmgr3.1.sql. This introduces one new convenience view, repl_show_nodes, but otherwise no changes have been made to repmgr's metadata schema.
• Run the provided repmgr database upgrade script, repmgr3.1.1_repmgr3.1.2.sql. This makes a small modification to the repl_nodes table's foreign key definition.
• If repmgrd is running, stop and restart the service to ensure it is running with the current repmgr version.

Upgrading from repmgr 2.0

repmgr 3.2 can replace an existing repmgr 2.0 installation. It should be installed first, either from your operating system's packaging system or from source, then following tasks performed:

• If repmgrd is running, stop the service.
• Run the provided repmgr database upgrade script, sql/repmgr2_repmgr3.sql, which is required to expand the repl_nodes table.
• Run the provided repmgr database upgrade script, sql/repmgr3.0_repmgr3.1.sql. This introduces one new convenience view, repl_show_nodes.
• Run the provided repmgr database upgrade script, repmgr3.1.1_repmgr3.1.2.sql. This makes a small modification to the repl_nodes table's foreign key definition.
• Restart repmgrd if previously stopped.

Community and development

repmgr is free and open source software and is licensed under the GPLv3.

Contributions to repmgr are welcome. See CONTRIBUTING.md for information about how to contribute.

All repmgr code and documentation is Copyright © 2011-2020, 2ndQuadrant Limited. See the files COPYRIGHT and LICENSE for details.