Master PostgreSQL Replication with repmgr: A Complete Guide

REPMGR Overview

repmgr is an open‑source tool for managing replication and failover in PostgreSQL clusters. It enhances built‑in streaming replication by providing a single read/write primary and one or more read‑only standby servers.

Each node holds a repmgr.conf file that records its ID, name, connection info, and PGDATA path. After configuring, the repmgr command can deploy the cluster with a “one‑click” approach.

After deployment, each node runs the repmgrd daemon to monitor database status, while metadata tables store information about all nodes.

Election Principle

During an auto‑failover, a standby that cannot connect to the primary after several attempts (configurable in repmgr.conf) triggers repmgrd to elect a candidate standby to become the new primary. The election order is LSN → Priority → Node_ID.

Node with the highest LSN is preferred.

If LSNs are equal, the node with higher Priority wins (Priority 0 disables promotion).

If both LSN and Priority are equal, the node with the smaller Node ID is chosen.

Two Main Tools

repmgr provides two executables: repmgr – command‑line utility for cluster management (register, promote, switchover, status, etc.). repmgrd – daemon that monitors the cluster, records events, detects failures, performs failover, and can invoke custom notification scripts.

User and Metadata

repmgr stores node information in dedicated tables created by the repmgr extension during the initial repmgr primary register step.

Tables: repmgr.events, repmgr.nodes, repmgr.monitoring_history Views: repmgr.show_nodes, repmgr.replication_status Note: The metadata database must belong to the same replication cluster managed by repmgr. The managing user does not need to be a superuser, except for operations like initial extension installation.

Installation

All nodes must run the same repmgr version (e.g., 5.2.x). Example for version 5.2.x:

$ git clone https://github.com/EnterpriseDB/repmgr
$ git checkout REL5_2_STABLE
$ cd repmgr/
./configure
$ make install

After make install, the binaries repmgr and repmgrd appear in pg_bin_path.

Basic Command Syntax

repmgr [OPTIONS] primary {register|unregister}
repmgr [OPTIONS] standby {register|unregister|clone|promote|follow|switchover}
repmgr [OPTIONS] node {status|check|rejoin|service}
repmgr [OPTIONS] cluster {show|event|matrix|crosscheck|cleanup}
repmgr [OPTIONS] witness {register|unregister}
repmgr [OPTIONS] service {status|pause|unpause}
repmgr [OPTIONS] daemon {start|stop}

Common options include: -b, --pg_bindir=PATH – path to PostgreSQL binaries. -f, --config-file=PATH – path to repmgr.conf. -F, --force – force potentially dangerous actions. -d, --dbname=DBNAME – database to connect (default “postgres”). -h, --host=HOSTNAME, -p, --port=PORT, -U, --username=USERNAME – connection parameters. -D, --pgdata=DIR – data directory of the node. --node-id, --node-name – identify the node for specific operations. --dry-run, -L, --log-level, --log-to-file, -q, --quiet, -t, --terse, -v, --verbose – logging and execution controls.

Common Operations

Register/unregister primary or standby nodes.

Clone a standby from the primary.

Promote a standby to primary or follow a new primary.

Show cluster status, events, and replication matrix.