From b049d7f0ec31c1c0c9ceb485cffe987289d57b67 Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Tue, 12 Sep 2017 23:04:16 +0900 Subject: [PATCH] Add "Overview" section --- doc/overview.sgml | 204 +++++++++++++++++++++++++++++++++++++++++++++- doc/repmgr.sgml | 4 + doc/version.sgml | 2 +- 3 files changed, 208 insertions(+), 2 deletions(-) diff --git a/doc/overview.sgml b/doc/overview.sgml index a6a7cc6f..a0f511a5 100644 --- a/doc/overview.sgml +++ b/doc/overview.sgml @@ -2,6 +2,208 @@ repmgr overview - repmgr is repmgr. + 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 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". + + + + + + + + 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 by the `repmgr` extension, which is installed + during the first step in initialising 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 `repl_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`). + + + diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml index 9c49e8d8..75e05c4a 100644 --- a/doc/repmgr.sgml +++ b/doc/repmgr.sgml @@ -52,6 +52,10 @@ repmgr + PostgreSQL + replication + asynchronous + high-availability diff --git a/doc/version.sgml b/doc/version.sgml index b3efd425..f26be77a 100644 --- a/doc/version.sgml +++ b/doc/version.sgml @@ -1 +1 @@ - +