repmgr: Overview

Summary: This chapter provides a high-level overview of repmgr’s components and functionality.

Concepts

This guide assumes that you are familiar with PostgreSQL administration and streaming replication concepts. For further details on streaming replication, see the PostgreSQL documentation section on streaming replication.

The following terms are used throughout the repmgr documentation.

• replication cluster

  In the repmgr documentation, “replication cluster” refers to the network of PostgreSQL servers connected by streaming replication.

• node

  A node is a single PostgreSQL server within a replication cluster.

• upstream node

  The node a standby server connects to, in order to receive streaming replication. This is either the primary server, or in the case of cascading replication, another standby.

• failover

  This is the action which occurs if a primary server fails and a suitable standby is promoted as the new primary. The repmgrd daemon supports automatic failover to minimise downtime.

• switchover

  In certain circumstances, such as hardware or operating system maintenance, it’s necessary to take a primary server offline; in this case a controlled switchover is necessary, whereby a suitable standby is promoted and the existing primary removed from the replication cluster in a controlled manner. The repmgr command line client provides this functionality.

• fencing

  In a failover situation, following the promotion of a new standby, it’s essential that the previous primary does not unexpectedly come back on line, which would result in a split-brain situation. To prevent this, the failed primary should be isolated from applications, i.e. “fenced off”.

• witness server

  repmgr provides functionality to set up a so-called “witness server” to assist in determining a new primary server in a failover situation with more than one standby. The witness server itself is not part of the replication cluster, although it does contain a copy of the repmgr metadata schema.

  The purpose of a witness server is to provide a “casting vote” where servers in the replication cluster are split over more than one location. In the event of a loss of connectivity between locations, the presence or absence of the witness server will decide whether a server at that location is promoted to primary; this is to prevent a “split-brain” situation where an isolated location interprets a network outage as a failure of the (remote) primary and promotes a (local) standby.

  A witness server only needs to be created if repmgrd is in use.

Components

repmgr is a suite of open-source tools to manage replication and failover within a cluster of PostgreSQL servers. It supports and enhances PostgreSQL’s built-in streaming replication, which provides a single read/write primary server and one or more read-only standbys containing near-real time copies of the primary server’s database. It provides two main tools:

repmgr

A command-line tool used to perform administrative tasks such as:

• setting up standby servers
• promoting a standby server to primary
• switching over primary and standby servers
• displaying the status of servers in the replication cluster

repmgrd

A daemon which actively monitors servers in a replication cluster and performs the following tasks:

• monitoring and recording replication performance
• performing failover by detecting failure of the primary and promoting the most suitable standby server
• provide notifications about events in the cluster to a user-defined script which can perform tasks such as sending alerts by email

Repmgr user and metadata

In order to effectively manage a replication cluster, repmgr needs to store information about the servers in the cluster in a dedicated database schema. This schema is automatically created by the repmgr extension, which is installed during the first step in initializing a repmgr-administered cluster (repmgr primary register) and contains the following objects:

Tables

• repmgr.events: records events of interest
• repmgr.nodes: connection and status information for each server in the replication cluster
• repmgr.monitoring_history: historical standby monitoring information written by repmgrd

Views

• repmgr.show_nodes: based on the table repmgr.nodes, additionally showing the name of the server’s upstream node
• repmgr.replication_status: when repmgrd’s monitoring is enabled, shows current monitoring status for each standby.

The repmgr metadata schema can be stored in an existing database or in its own dedicated database. Note that the repmgr metadata schema cannot reside on a database server which is not part of the replication cluster managed by repmgr.

A database user must be available for repmgr to access this database and perform necessary changes. This user does not need to be a superuser, however some operations such as initial installation of the repmgr extension will require a superuser connection (this can be specified where required with the command line option --superuser).