github/repmgr
1
0
Fork 0
mirror of https://github.com/EnterpriseDB/repmgr.git synced 2026-03-23 15:16:29 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Various documentation fixes

Browse Source
This commit is contained in:
Ian Barwick
2017-10-17 11:00:37 +09:00
parent 95ec8d8b21
commit f6c253f8a6
15 changed files with 160 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/cloning-standbys.sgml
View File

@@ -5,8 +5,8 @@
<sect1 id="cloning-from-barman" xreflabel="Cloning from Barman">
<indexterm>
<primary>cloning</primary>
<secondary>from Barman</secondary>
<primary>cloning</primary>
<secondary>from Barman</secondary>
</indexterm>
<title>Cloning a standby from Barman</title>
<para>
@@ -192,7 +192,7 @@
</programlisting>
</para>
<para>
Replication slots must be enabled in <filename>postgresql.conf</filename>` by
Replication slots must be enabled in <filename>postgresql.conf</filename> by
setting the parameter <varname>max_replication_slots</varname> to at least the
number of expected standbys (changes to this parameter require a server restart).
</para>

5
doc/configuration-file-settings.sgml
View File

@@ -1,4 +1,9 @@
<sect1 id="configuration-file-settings" xreflabel="configuration file settings">
<indexterm>
<primary>repmgr.conf</primary>
<secondary>settings</secondary>
</indexterm>
<title>Configuration file settings</title>
<para>
Each <filename>repmgr.conf</filename> file must contain the following parameters:

15
doc/configuration-file.sgml
View File

@@ -1,4 +1,9 @@
<sect1 id="configuration-file" xreflabel="configuration file location">
<indexterm>
<primary>repmgr.conf</primary>
<secondary>location</secondary>
</indexterm>
<title>Configuration file location</title>
<para>
<application>repmgr</application> and <application>repmgrd</application>
@@ -7,7 +12,7 @@
<filename>repmgr.conf</filename> must contain a number of required parameters, including
the database connection string for the local node and the location
of its data directory; other values will be inferred from defaults if
not explicitly supplied. See section `configuration file parameters`
not explicitly supplied. See section <xref linkend="configuration-file-settings">
for more details.
</para>
@@ -15,7 +20,7 @@
The configuration file will be searched for in the following locations:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>a configuration file specified by the `-f/--config-file` command line option</para>
<para>a configuration file specified by the <literal>-f/--config-file</literal> command line option</para>
</listitem>
<listitem>
<para>
@@ -37,10 +42,10 @@
</para>
<para>
Note that if a file is explicitly specified with <application>-f/--config-file</application>,
an error will be raised if it is not found or not readable and no attempt will be made to
Note that if a file is explicitly specified with <literal>-f/--config-file</literal>,
an error will be raised if it is not found or not readable, and no attempt will be made to
check default locations; this is to prevent <application>repmgr</application> unexpectedly
reading the wrong file.
reading the wrong configuraton file.
</para>
</sect1>

10
doc/event-notifications.sgml
View File

@@ -1,12 +1,12 @@
<chapter id="event-notifications" xreflabel="event notifications">
<title>Event Notifications</title>
<para>
Each time `repmgr` or `repmgrd` perform a significant event, a record
of that event is written into the `repmgr.events` table together with
Each time &repmgr; or <command>repmgrd</command> perform a significant event, a record
of that event is written into the <literal>repmgr.events</literal> table together with
a timestamp, an indication of failure or success, and further details
if appropriate. This is useful for gaining an overview of events
affecting the replication cluster. However note that this table has
advisory character and should be used in combination with the `repmgr`
advisory character and should be used in combination with the &repmgr;
and PostgreSQL logs to obtain details of any events.
</para>
<para>
@@ -28,8 +28,8 @@
<para>
Additionally, event notifications can be passed to a user-defined program
or script which can take further action, e.g. send email notifications.
This is done by setting the `event_notification_command` parameter in
`repmgr.conf`.
This is done by setting the <literal>event_notification_command</literal> parameter in
<filename>repmgr.conf</filename>.
</para>
<para>
This parameter accepts the following format placeholders:

8
doc/follow-new-primary.sgml
View File

@@ -1,4 +1,9 @@
<chapter id="follow-new-primary" xreflabel="Following a new primary">
<indexterm>
<primary>Following a new primary</primary>
<seealso>repmgr standby follow</seealso>
</indexterm>
<title>Following a new primary</title>
<para>
Following the failure or removal of the replication cluster's existing primary
@@ -22,7 +27,8 @@
</programlisting>
</para>
<para>
The standby is now replicating from the new primary and `repmgr cluster show`
The standby is now replicating from the new primary and
<command><link linkend="repmgr-cluster-show">repmgr cluster show</link></command>
output reflects this:
<programlisting>
$ repmgr -f /etc/repmgr.conf cluster show

61
doc/install-packages.sgml
View File

@@ -1,32 +1,47 @@
<sect1 id="installation-packages" xreflabel="Installing from packages">
<title>Installing &repmgr; from packages</title>
<para>
We recommend installing `repmgr` using the available packages for your
system.
We recommend installing &repmgr; using the available packages for your
system.
</para>
<sect2 id="installation-packages-redhat" xreflabel="Installing from packages on RHEL, Fedora and CentOS">
<title>RedHat/Fedora/CentOS</title>
<para>
RPM packages for `repmgr` are available via Yum through
the PostgreSQL Global Development Group RPM repository
( <ulink url="https://yum.postgresql.org/">http://yum.postgresql.org/</>).
Follow the instructions for your distribution (RedHat, CentOS,
Fedora, etc.) and architecture as detailed at yum.postgresql.org.
</para>
<para>
2ndQuadrant also provides its own RPM packages which are made available
at the same time as each `repmgr` release, as it can take some days for
them to become available via the main PGDG repository. See here for details:
<ulink url="http://repmgr.org/yum-repository.html">http://repmgr.org/yum-repository.html</>
</para>
</sect2>
<sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
<title>Debian/Ubuntu</title>
<para>.deb packages for `repmgr` are available from the
PostgreSQL Community APT repository (<ulink url="http://apt.postgresql.org/">http://apt.postgresql.org/</> ).
Instructions can be found in the APT section of the PostgreSQL Wiki
(<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</> ).
<indexterm>
<primary>installation</primary>
<secondary>on Redhat/CentOS/Fedora etc.</secondary>
</indexterm>
<title>RedHat/Fedora/CentOS</title>
<para>
RPM packages for &repmgr; are available via Yum through
the PostgreSQL Global Development Group RPM repository
(<ulink url="https://yum.postgresql.org/">http://yum.postgresql.org/</>).
Follow the instructions for your distribution (RedHat, CentOS,
Fedora, etc.) and architecture as detailed there.
</para>
<para>
<ulink url="https://2ndquadrant.com">2ndQuadrant</ulink> also provides its
own RPM packages which are made available
at the same time as each &repmgr; release, as it can take some days for
them to become available via the main PGDG repository. See here for details:
<ulink url="http://repmgr.org/yum-repository.html">http://repmgr.org/yum-repository.html</>
</para>
</sect2>
<sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
<indexterm>
<primary>installation</primary>
<secondary>on Debian/Ubuntu etc.</secondary>
</indexterm>
<title>Debian/Ubuntu</title>
<para>.deb packages for &repmgr; are available from the
PostgreSQL Community APT repository (<ulink url="http://apt.postgresql.org/">http://apt.postgresql.org/</>).
Instructions can be found in the APT section of the PostgreSQL Wiki
(<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</>).
</para>
</sect2>
</sect1>

43
doc/install-requirements.sgml
View File

@@ -7,17 +7,14 @@
</para>
<para>
From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.4, including PostgreSQL 10.
</para>
<para>
PostgreSQL 9.3 is supported by repmgr 3.3.
From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.3, including PostgreSQL 10.
Note that some &repmgr; functionality is not available in PostgreSQL 9.3 and PostgreSQL 9.4.
</para>
<note>
<simpara>
If upgrading from `repmgr 3`, please see the separate upgrade guide
`doc/upgrading-from-repmgr3.md`.
</simpara>
<simpara>
If upgrading from &repmgr; 3.x, please see the section <xref linkend="upgrading-from-repmgr-3">.
</simpara>
</note>
<para>
@@ -26,42 +23,44 @@ If upgrading from `repmgr 3`, please see the separate upgrade guide
</para>
<para>
`repmgr` must be installed on each server in the replication cluster.
&repmgr; must be installed on each server in the replication cluster.
If installing repmgr from packages, the package version must match the PostgreSQL
version. If installing from source, repmgr must be compiled against the same
major version.
</para>
<para>
A dedicated system user for `repmgr` is *not* required; as many `repmgr` and
`repmgrd` actions require direct access to the PostgreSQL data directory,
these commands should be executed by the `postgres` user.
A dedicated system user for &repmgr; is *not* required; as many &repmgr; and
<command>repmgrd</command> actions require direct access to the PostgreSQL data directory,
these commands should be executed by the <literal>postgres</literal> user.
</para>
<para>
Passwordless `ssh` connectivity between all servers in the replication cluster
Passwordless <command>ssh</command> connectivity between all servers in the replication cluster
is not required, but is necessary in the following cases:
<itemizedlist>
<listitem>
<simpara>if you need `repmgr` to copy configuration files from outside the PostgreSQL
data directory (in which case `rsync` is also required)</simpara>
<simpara>if you need &repmgr; to copy configuration files from outside the PostgreSQL
data directory (in which case <command>rsync</command> is also required)</simpara>
</listitem>
<listitem>
<simpara>to perform switchover operations</simpara>
<simpara>to perform <link linkend="performing-switchover">switchover operations</link></simpara>
</listitem>
<listitem>
<simpara>when executing `repmgr cluster matrix` and `repmgr cluster crosscheck`</simpara>
<simpara>
when executing <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command>
and <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>
</simpara>
</listitem>
</itemizedlist>
</para>
<tip>
<simpara>
We recommend using a session multiplexer utility such as `screen` or
`tmux` when performing long-running actions (such as cloning a database)
on a remote server - this will ensure the `repmgr` action won't be prematurely
terminated if your `ssh` session to the server is interrupted or closed.
We recommend using a session multiplexer utility such as <command>screen</command> or
<command>tmux</command> when performing long-running actions (such as cloning a database)
on a remote server - this will ensure the &repmgr; action won't be prematurely
terminated if your <command>ssh</command> session to the server is interrupted or closed.
</simpara>
</tip>
</sect1>

8
doc/install-source.sgml
View File

@@ -1,4 +1,9 @@
<sect1 id="installation-source" xreflabel="Installing from source code">
<indexterm>
<primary>installation</primary>
<secondary>from source</secondary>
</indexterm>
<title>Installing &repmgr; from source</title>
<sect2 id="installation-source-prereqs">
@@ -132,7 +137,8 @@
./configure && make install
</programlisting>
Ensure `pg_config` for the target PostgreSQL version is in `$PATH`.
Ensure <command>pg_config</command> for the target PostgreSQL version is in
<varname>$PATH</varname>.
</para>
</sect2>

4
doc/install.sgml
View File

@@ -1,4 +1,8 @@
<chapter id="installation" xreflabel="Installation">
<indexterm>
<primary>installation</primary>
</indexterm>
<title>Installation</title>
<para>

55
doc/overview.sgml
View File

@@ -5,6 +5,11 @@
This chapter provides a high-level overview of repmgr's components and functionality.
</para>
<sect1 id="repmgr-concepts" xreflabel="Concepts">
<indexterm>
<primary>concepts</primary>
</indexterm>
<title>Concepts</title>
<para>
@@ -15,13 +20,13 @@
streaming replication</>.
</para>
<para>
The following terms are used throughout the `repmgr` documentation.
The following terms are used throughout the &repmgr; documentation.
<variablelist>
<varlistentry>
<term>replication cluster</term>
<listitem>
<simpara>
In the `repmgr` documentation, "replication cluster" refers to the network
In the &repmgr; documentation, "replication cluster" refers to the network
of PostgreSQL servers connected by streaming replication.
</simpara>
</listitem>
@@ -31,7 +36,7 @@
<term>node</term>
<listitem>
<simpara>
A node is a server within a replication cluster.
A node is a single PostgreSQL server within a replication cluster.
</simpara>
</listitem>
</varlistentry>
@@ -41,7 +46,7 @@
<listitem>
<simpara>
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
This is either the primary server, or in the case of cascading replication, another
standby.
</simpara>
</listitem>
@@ -52,7 +57,7 @@
<listitem>
<simpara>
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
is promoted as the new primary. The <command>repmgrd</command> daemon supports automatic failover
to minimise downtime.
</simpara>
</listitem>
@@ -66,7 +71,7 @@
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.
The &repmgr; command line client provides this functionality.
</simpara>
</listitem>
</varlistentry>
@@ -88,7 +93,7 @@
<sect1 id="repmgr-components" xreflabel="Components">
<title>Components</title>
<para>
`repmgr` is a suite of open-source tools to manage replication and failover
&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
@@ -147,11 +152,12 @@
<sect1 id="repmgr-user-metadata" xreflabel="Repmgr user and metadata">
<title>Repmgr user and metadata</title>
<para>
In order to effectively manage a replication cluster, `repmgr` needs to store
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:
This schema is automatically by the &repmgr; extension, which is installed
during the first step in initialising a &repmgr;-administered cluster
(<command><link linkend="repmgr-primary-register">repmgr primary register</link></command>)
and contains the following objects:
<variablelist>
<varlistentry>
<term>Tables</term>
@@ -159,14 +165,15 @@
<para>
<itemizedlist>
<listitem>
<simpara>repmgr.events: records events of interest</simpara>
<simpara><literal>repmgr.events</literal>: records events of interest</simpara>
</listitem>
<listitem>
<simpara>repmgr.nodes: connection and status information for each server in the
<simpara><literal>repmgr.nodes</literal>: connection and status information for each server in the
replication cluster</simpara>
</listitem>
<listitem>
<simpara>repmgr.monitoring_history: historical standby monitoring information written by `repmgrd`</simpara>
<simpara><literal>repmgr.monitoring_history</literal>: historical standby monitoring information
written by <command>repmgrd</command></simpara>
</listitem>
</itemizedlist>
</para>
@@ -178,12 +185,12 @@
<para>
<itemizedlist>
<listitem>
<simpara>repmgr.show_nodes: based on the table `repl_nodes`, additionally showing the
name of the server's upstream node</simpara>
<simpara>repmgr.show_nodes: based on the table <literal>repmgr.nodes</literal>, additionally showing the
name of the server's upstream node</simpara>
</listitem>
<listitem>
<simpara>repmgr.replication_status: when `repmgrd`'s monitoring is enabled, shows current monitoring
status for each standby.</simpara>
<simpara>repmgr.replication_status: when <command>repmgrd</command>'s monitoring is enabled, shows
current monitoring status for each standby.</simpara>
</listitem>
</itemizedlist>
</para>
@@ -193,16 +200,16 @@
</para>
<para>
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`.
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;.
</para>
<para>
A database user must be available for `repmgr` to access this database and perform
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
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`).
<literal>--superuser</literal>).
</para>
</sect1>

4
doc/repmgr-cluster-matrix.sgml
View File

@@ -9,7 +9,7 @@
</para>
<para>
<command>repmgr cluster matrix</command> requires a valid <filename>repmgr.conf</filename>
file on each node. Additionally passwordless `ssh` connections are required between
file on each node. Additionally passwordless <command>ssh</command> connections are required between
all nodes.
</para>
<para>
@@ -46,7 +46,7 @@
<para>
The other two nodes are up; the corresponding rows have <literal>x</literal> in the
column corresponding to <literal>node3</literal>, meaning that inbound connections to
that node have failed, and `*` in the columns corresponding to
that node have failed, and <literal>*</literal> in the columns corresponding to
<literal>node1</literal> and <literal>node2</literal>, meaning that inbound connections
to these nodes have succeeded.
</para>

2
doc/repmgr-cluster-show.sgml
View File

@@ -32,7 +32,7 @@
<literal>--verbose</literal> mode.
</para>
<para>
The `cluster show` command accepts an optional parameter <literal>--csv</literal>, which
<command>cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
outputs the replication cluster's status in a simple CSV format, suitable for
parsing by scripts:
<programlisting>

2
doc/repmgr-standby-clone.sgml
View File

@@ -58,7 +58,7 @@
<para>
When initially cloning a standby, you will need to ensure
that all required WAL files remain available while the cloning is taking
place. To ensure this happens when using the default `pg_basebackup` method,
place. To ensure this happens when using the default <command>pg_basebackup</command> method,
&repmgr; will set <command>pg_basebackup</command>'s <literal>--xlog-method</literal>
parameter to <literal>stream</literal>,
which will ensure all WAL files generated during the cloning process are

11
doc/switchover.sgml
View File

@@ -1,4 +1,9 @@
<chapter id="performing-switchover" xreflabel="Performing a switchover with repmgr">
<indexterm>
<primary>switchover</primary>
</indexterm>
<title>Performing a switchover with repmgr</title>
<para>
A typical use-case for replication is a combination of primary and standby
@@ -39,7 +44,7 @@
</simpara>
<simpara>
Please also read carefully the sections <xref linkend="preparing-for-switchover"> and
`Caveats` below.
<xref linkend="switchover-caveats"> below.
</simpara>
</note>
@@ -81,7 +86,7 @@
If WAL file archiving is set up, check that there is no backlog of files waiting
to be archived, as PostgreSQL will not finally shut down until all these have been
archived. If there is a backlog exceeding <varname>archive_ready_warning</varname> WAL files,
`repmgr` will emit a warning before attempting to perform a switchover; you can also check
&repmgr; will emit a warning before attempting to perform a switchover; you can also check
manually with <command>repmgr node check --archive-ready</command>.
</para>
<para>
@@ -198,7 +203,7 @@
</itemizedlist>
</para>
<para>
We hope to remove some of these restrictions in future versions of `repmgr`.
We hope to remove some of these restrictions in future versions of &repmgr;.
</para>
</sect1>
</chapter>

22
doc/upgrading-repmgr.sgml
View File

@@ -1,5 +1,11 @@
<chapter id="upgrading-repmgr" xreflabel="Upgrading repmgr">
<indexterm>
<primary>upgrading</primary>
</indexterm>
<title>Upgrading repmgr</title>
<para>
&repmgr; is updated regularly with point releases (e.g. 4.0.1 to 4.0.2)
containing bugfixes and other minor improvements. Any substantial new
@@ -17,8 +23,13 @@
file used by <command>repmgrd</command>; check the release notes for details.
</para>
<sect1 id="upgrading-from-repmgr-3">
<title>Upgrading from repmgr 3</title>
<sect1 id="upgrading-from-repmgr-3" xreflabel="Upgrading from repmgr 3.x">
<indexterm>
<primary>upgrading</primary>
<secondary>from repmgr 3.x</secondary>
</indexterm>
<title>Upgrading from repmgr 3.x</title>
<para>
The upgrade process consists of two steps:
<orderedlist>
@@ -162,8 +173,8 @@
<command>repmgr</command> binary.
</para>
<para>
Install <literal>repmgr4</literal>; any <literal>repmgr3</literal> packages should be uninstalled
(if not automatically uninstalled already).
Install <literal>repmgr 4</literal> packages; any <literal>repmgr 3.x</literal> packages
should be uninstalled (if not automatically uninstalled already by your packaging system).
</para>
<sect3>
<title>Upgrading from repmgr 3.1.1 or earlier</title>
@@ -203,7 +214,8 @@
</para>
<note>
<simpara>there must be only one schema matching <literal>repmgr_%</literal> in the
database, otherwise this step may not work.</simpara>
database, otherwise this step may not work.
</simpara>
</note>
</sect3>
<sect3>