mirror of
https://github.com/EnterpriseDB/repmgr.git
synced 2026-03-26 00:26:30 +00:00
doc: standardize doc formatting
Indent with two spaces instead of one.
This commit is contained in:
Ian Barwick
@@ -3,443 +3,442 @@
|
|||||||
<title>FAQ (Frequently Asked Questions)</title>
|
<title>FAQ (Frequently Asked Questions)</title>
|
||||||
|
|
||||||
<indexterm>
|
<indexterm>
|
||||||
<primary>FAQ (Frequently Asked Questions)</primary>
|
<primary>FAQ (Frequently Asked Questions)</primary>
|
||||||
</indexterm>
|
</indexterm>
|
||||||
|
|
||||||
<sect1 id="faq-general" xreflabel="General">
|
<sect1 id="faq-general" xreflabel="General">
|
||||||
<title>General</title>
|
<title>General</title>
|
||||||
|
|
||||||
<sect2 id="faq-xrepmgr-version-diff" xreflabel="Version differences">
|
<sect2 id="faq-xrepmgr-version-diff" xreflabel="Version differences">
|
||||||
<title>What's the difference between the repmgr versions?</title>
|
<title>What's the difference between the repmgr versions?</title>
|
||||||
<para>
|
|
||||||
&repmgr; 4 is a complete rewrite of the previous &repmgr; code base
|
|
||||||
and implements &repmgr; as a PostgreSQL extension. It
|
|
||||||
supports all PostgreSQL versions from 9.3 (although some &repmgr;
|
|
||||||
features are not available for PostgreSQL 9.3 and 9.4).
|
|
||||||
</para>
|
|
||||||
<note>
|
|
||||||
<para>
|
<para>
|
||||||
&repmgr; 5 is fundamentally the same code base as &repmgr; 4, but provides
|
&repmgr; 4 is a complete rewrite of the previous &repmgr; code base
|
||||||
support for the revised replication configuration mechanism in PostgreSQL 12.
|
and implements &repmgr; as a PostgreSQL extension. It
|
||||||
|
supports all PostgreSQL versions from 9.3 (although some &repmgr;
|
||||||
|
features are not available for PostgreSQL 9.3 and 9.4).
|
||||||
</para>
|
</para>
|
||||||
</note>
|
<note>
|
||||||
<para>
|
<para>
|
||||||
&repmgr; 3.x builds on the improved replication facilities added
|
&repmgr; 5 is fundamentally the same code base as &repmgr; 4, but provides
|
||||||
in PostgreSQL 9.3, as well as improved automated failover support
|
support for the revised replication configuration mechanism in PostgreSQL 12.
|
||||||
via &repmgrd;, and is not compatible with PostgreSQL 9.2
|
</para>
|
||||||
and earlier. We recommend upgrading to &repmgr; 4, as the &repmgr; 3.x
|
</note>
|
||||||
series is no longer maintained.
|
<para>
|
||||||
</para>
|
&repmgr; 3.x builds on the improved replication facilities added
|
||||||
<para>
|
in PostgreSQL 9.3, as well as improved automated failover support
|
||||||
&repmgr; 2.x supports PostgreSQL 9.0 ~ 9.3. While it is compatible
|
via &repmgrd;, and is not compatible with PostgreSQL 9.2
|
||||||
with PostgreSQL 9.3, we recommend using repmgr 4.x. &repmgr; 2.x is
|
and earlier. We recommend upgrading to &repmgr; 4, as the &repmgr; 3.x
|
||||||
no longer maintained.
|
series is no longer maintained.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
See also <link linkend="install-compatibility-matrix">&repmgr; compatibility matrix</link>
|
&repmgr; 2.x supports PostgreSQL 9.0 ~ 9.3. While it is compatible
|
||||||
and <link linkend="faq-upgrade-repmgr">Should I upgrade &repmgr;?</link>.
|
with PostgreSQL 9.3, we recommend using repmgr 4.x. &repmgr; 2.x is
|
||||||
</para>
|
no longer maintained.
|
||||||
</sect2>
|
</para>
|
||||||
|
<para>
|
||||||
|
See also <link linkend="install-compatibility-matrix">&repmgr; compatibility matrix</link>
|
||||||
|
and <link linkend="faq-upgrade-repmgr">Should I upgrade &repmgr;?</link>.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-replication-slots-advantage" xreflabel="Advantages of replication slots">
|
<sect2 id="faq-replication-slots-advantage" xreflabel="Advantages of replication slots">
|
||||||
<title>What's the advantage of using replication slots?</title>
|
<title>What's the advantage of using replication slots?</title>
|
||||||
<para>
|
<para>
|
||||||
Replication slots, introduced in PostgreSQL 9.4, ensure that the
|
Replication slots, introduced in PostgreSQL 9.4, ensure that the
|
||||||
primary server will retain WAL files until they have been consumed
|
primary server will retain WAL files until they have been consumed
|
||||||
by all standby servers. This means standby servers should never
|
by all standby servers. This means standby servers should never
|
||||||
fail due to not being able to retrieve required WAL files from the
|
fail due to not being able to retrieve required WAL files from the
|
||||||
primary.
|
primary.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
However this does mean that if a standby is no longer connected to the
|
However this does mean that if a standby is no longer connected to the
|
||||||
primary, the presence of the replication slot will cause WAL files
|
primary, the presence of the replication slot will cause WAL files
|
||||||
to be retained indefinitely, and eventually lead to disk space
|
to be retained indefinitely, and eventually lead to disk space
|
||||||
exhaustion.
|
exhaustion.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<tip>
|
<tip>
|
||||||
<para>
|
<para>
|
||||||
2ndQuadrant's recommended configuration is to configure
|
2ndQuadrant's recommended configuration is to configure
|
||||||
<ulink url="https://www.pgbarman.org/">Barman</ulink> as a fallback
|
<ulink url="https://www.pgbarman.org/">Barman</ulink> as a fallback
|
||||||
source of WAL files, rather than maintain replication slots for
|
source of WAL files, rather than maintain replication slots for
|
||||||
each standby. See also: <link linkend="cloning-from-barman-restore-command">Using Barman as a WAL file source</link>.
|
each standby. See also: <link linkend="cloning-from-barman-restore-command">Using Barman as a WAL file source</link>.
|
||||||
</para>
|
</para>
|
||||||
</tip>
|
</tip>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-replication-slots-number" xreflabel="Number of replication slots">
|
<sect2 id="faq-replication-slots-number" xreflabel="Number of replication slots">
|
||||||
<title>How many replication slots should I define in <varname>max_replication_slots</varname>?</title>
|
<title>How many replication slots should I define in <varname>max_replication_slots</varname>?</title>
|
||||||
<para>
|
<para>
|
||||||
Normally at least same number as the number of standbys which will connect
|
Normally at least same number as the number of standbys which will connect
|
||||||
to the node. Note that changes to <varname>max_replication_slots</varname> require a server
|
to the node. Note that changes to <varname>max_replication_slots</varname> require a server
|
||||||
restart to take effect, and as there is no particular penalty for unused
|
restart to take effect, and as there is no particular penalty for unused
|
||||||
replication slots, setting a higher figure will make adding new nodes
|
replication slots, setting a higher figure will make adding new nodes
|
||||||
easier.
|
easier.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-hash-index" xreflabel="Hash indexes">
|
<sect2 id="faq-hash-index" xreflabel="Hash indexes">
|
||||||
<title>Does &repmgr; support hash indexes?</title>
|
<title>Does &repmgr; support hash indexes?</title>
|
||||||
<para>
|
<para>
|
||||||
Before PostgreSQL 10, hash indexes were not WAL logged and are therefore not suitable
|
Before PostgreSQL 10, hash indexes were not WAL logged and are therefore not suitable
|
||||||
for use in streaming replication in PostgreSQL 9.6 and earlier. See the
|
for use in streaming replication in PostgreSQL 9.6 and earlier. See the
|
||||||
<ulink url="https://www.postgresql.org/docs/9.6/sql-createindex.html#AEN80279">PostgreSQL documentation</ulink>
|
<ulink url="https://www.postgresql.org/docs/9.6/sql-createindex.html#AEN80279">PostgreSQL documentation</ulink>
|
||||||
for details.
|
for details.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
From PostgreSQL 10, this restriction has been lifted and hash indexes can be used
|
From PostgreSQL 10, this restriction has been lifted and hash indexes can be used
|
||||||
in a streaming replication cluster.
|
in a streaming replication cluster.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-upgrades" xreflabel="Upgrading PostgreSQL with repmgr">
|
<sect2 id="faq-upgrades" xreflabel="Upgrading PostgreSQL with repmgr">
|
||||||
<title>Can &repmgr; assist with upgrading a PostgreSQL cluster?</title>
|
<title>Can &repmgr; assist with upgrading a PostgreSQL cluster?</title>
|
||||||
<para>
|
<para>
|
||||||
For <emphasis>minor</emphasis> version upgrades, e.g. from 9.6.7 to 9.6.8, a common
|
For <emphasis>minor</emphasis> version upgrades, e.g. from 9.6.7 to 9.6.8, a common
|
||||||
approach is to upgrade a standby to the latest version, perform a
|
approach is to upgrade a standby to the latest version, perform a
|
||||||
<link linkend="performing-switchover">switchover</link> promoting it to a primary,
|
<link linkend="performing-switchover">switchover</link> promoting it to a primary,
|
||||||
then upgrade the former primary.
|
then upgrade the former primary.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
For <emphasis>major</emphasis> version upgrades (e.g. from PostgreSQL 9.6 to PostgreSQL 10),
|
For <emphasis>major</emphasis> version upgrades (e.g. from PostgreSQL 9.6 to PostgreSQL 10),
|
||||||
the traditional approach is to "reseed" a cluster by upgrading a single
|
the traditional approach is to "reseed" a cluster by upgrading a single
|
||||||
node with <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html">pg_upgrade</ulink>
|
node with <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html">pg_upgrade</ulink>
|
||||||
and recloning standbys from this.
|
and recloning standbys from this.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
To minimize downtime during major upgrades from PostgreSQL 9.4 and later,
|
To minimize downtime during major upgrades from PostgreSQL 9.4 and later,
|
||||||
<ulink url="https://www.2ndquadrant.com/en/resources/pglogical/">pglogical</ulink>
|
<ulink url="https://www.2ndquadrant.com/en/resources/pglogical/">pglogical</ulink>
|
||||||
can be used to set up a parallel cluster using the newer PostgreSQL version,
|
can be used to set up a parallel cluster using the newer PostgreSQL version,
|
||||||
which can be kept in sync with the existing production cluster until the
|
which can be kept in sync with the existing production cluster until the
|
||||||
new cluster is ready to be put into production.
|
new cluster is ready to be put into production.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-libdir-repmgr-error">
|
<sect2 id="faq-libdir-repmgr-error">
|
||||||
<title>What does this error mean: <literal>ERROR: could not access file "$libdir/repmgr"</literal>?</title>
|
<title>What does this error mean: <literal>ERROR: could not access file "$libdir/repmgr"</literal>?</title>
|
||||||
<para>
|
<para>
|
||||||
It means the &repmgr; extension code is not installed in the
|
It means the &repmgr; extension code is not installed in the
|
||||||
PostgreSQL application directory. This typically happens when using PostgreSQL
|
PostgreSQL application directory. This typically happens when using PostgreSQL
|
||||||
packages provided by a third-party vendor, which often have different
|
packages provided by a third-party vendor, which often have different
|
||||||
filesystem layouts.
|
filesystem layouts.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Either use PostgreSQL packages provided by the community or 2ndQuadrant; if this
|
Either use PostgreSQL packages provided by the community or 2ndQuadrant; if this
|
||||||
is not possible, contact your vendor for assistance.
|
is not possible, contact your vendor for assistance.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-old-packages">
|
<sect2 id="faq-old-packages">
|
||||||
<title>How can I obtain old versions of &repmgr; packages?</title>
|
<title>How can I obtain old versions of &repmgr; packages?</title>
|
||||||
<para>
|
<para>
|
||||||
See appendix <xref linkend="packages-old-versions"/> for details.
|
See appendix <xref linkend="packages-old-versions"/> for details.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-required-for-replication">
|
<sect2 id="faq-repmgr-required-for-replication">
|
||||||
<title>Is &repmgr; required for streaming replication?</title>
|
<title>Is &repmgr; required for streaming replication?</title>
|
||||||
<para>
|
<para>
|
||||||
No.
|
No.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
&repmgr; (together with &repmgrd;) assists with
|
&repmgr; (together with &repmgrd;) assists with
|
||||||
<emphasis>managing</emphasis> replication. It does not actually perform replication, which
|
<emphasis>managing</emphasis> replication. It does not actually perform replication, which
|
||||||
is part of the core PostgreSQL functionality.
|
is part of the core PostgreSQL functionality.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-what-if-repmgr-uninstalled">
|
<sect2 id="faq-what-if-repmgr-uninstalled">
|
||||||
<title>Will replication stop working if &repmgr; is uninstalled?</title>
|
<title>Will replication stop working if &repmgr; is uninstalled?</title>
|
||||||
<para>
|
<para>
|
||||||
No. See preceding question.
|
No. See preceding question.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-version-mix">
|
<sect2 id="faq-version-mix">
|
||||||
<title>Does it matter if different &repmgr; versions are present in the replication cluster?</title>
|
<title>Does it matter if different &repmgr; versions are present in the replication cluster?</title>
|
||||||
<para>
|
<para>
|
||||||
Yes. If different "major" &repmgr; versions (e.g. 3.3.x and 4.1.x) are present,
|
Yes. If different "major" &repmgr; versions (e.g. 3.3.x and 4.1.x) are present,
|
||||||
&repmgr; (in particular &repmgrd;)
|
&repmgr; (in particular &repmgrd;)
|
||||||
may not run, or run properly, or in the worst case (if different &repmgrd;
|
may not run, or run properly, or in the worst case (if different &repmgrd;
|
||||||
versions are running and there are differences in the failover implementation) break
|
versions are running and there are differences in the failover implementation) break
|
||||||
your replication cluster.
|
your replication cluster.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
If different "minor" &repmgr; versions (e.g. 4.1.1 and 4.1.6) are installed,
|
If different "minor" &repmgr; versions (e.g. 4.1.1 and 4.1.6) are installed,
|
||||||
&repmgr; will function, but we strongly recommend always running the same version
|
&repmgr; will function, but we strongly recommend always running the same version
|
||||||
to ensure there are no unexpected suprises, e.g. a newer version behaving slightly
|
to ensure there are no unexpected suprises, e.g. a newer version behaving slightly
|
||||||
differently to the older version.
|
differently to the older version.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
See also <link linkend="faq-upgrade-repmgr">Should I upgrade &repmgr;?</link>.
|
See also <link linkend="faq-upgrade-repmgr">Should I upgrade &repmgr;?</link>.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-upgrade-repmgr">
|
<sect2 id="faq-upgrade-repmgr">
|
||||||
<title>Should I upgrade &repmgr;?</title>
|
<title>Should I upgrade &repmgr;?</title>
|
||||||
<para>
|
<para>
|
||||||
Yes.
|
Yes.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
We don't release new versions for fun, you know. Upgrading may require a little effort,
|
We don't release new versions for fun, you know. Upgrading may require a little effort,
|
||||||
but running an older &repmgr; version with bugs which have since been fixed may end up
|
but running an older &repmgr; version with bugs which have since been fixed may end up
|
||||||
costing you more effort. The same applies to PostgreSQL itself.
|
costing you more effort. The same applies to PostgreSQL itself.
|
||||||
</para>
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
</sect2>
|
<sect2 id="faq-repmgr-conf-data-directory">
|
||||||
|
<title>Why do I need to specify the data directory location in repmgr.conf?</title>
|
||||||
|
<para>
|
||||||
|
In some circumstances &repmgr; may need to access a PostgreSQL data
|
||||||
|
directory while the PostgreSQL server is not running, e.g. to confirm
|
||||||
|
it shut down cleanly during a <link linkend="performing-switchover">switchover</link>.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Additionally, this provides support when using &repmgr; on PostgreSQL 9.6 and
|
||||||
|
earlier, where the <literal>repmgr</literal> user is not a superuser; in that
|
||||||
|
case the <literal>repmgr</literal> user will not be able to access the
|
||||||
|
<literal>data_directory</literal> configuration setting, access to which is restricted
|
||||||
|
to superusers. (In PostgreSQL 10 and later, non-superusers can be added to the
|
||||||
|
group <option>pg_read_all_settings</option> which will enable them to read this setting).
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-conf-data-directory">
|
<sect1 id="faq-repmgr" xreflabel="repmgr">
|
||||||
<title>Why do I need to specify the data directory location in repmgr.conf?</title>
|
<title><command>repmgr</command></title>
|
||||||
<para>
|
|
||||||
In some circumstances &repmgr; may need to access a PostgreSQL data
|
|
||||||
directory while the PostgreSQL server is not running, e.g. to confirm
|
|
||||||
it shut down cleanly during a <link linkend="performing-switchover">switchover</link>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Additionally, this provides support when using &repmgr; on PostgreSQL 9.6 and
|
|
||||||
earlier, where the <literal>repmgr</literal> user is not a superuser; in that
|
|
||||||
case the <literal>repmgr</literal> user will not be able to access the
|
|
||||||
<literal>data_directory</literal> configuration setting, access to which is restricted
|
|
||||||
to superusers. (In PostgreSQL 10 and later, non-superusers can be added to the
|
|
||||||
group <option>pg_read_all_settings</option> which will enable them to read this setting).
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="faq-repmgr" xreflabel="repmgr">
|
<sect2 id="faq-register-existing-node" xreflabel="registering an existing node">
|
||||||
<title><command>repmgr</command></title>
|
<title>Can I register an existing PostgreSQL server with repmgr?</title>
|
||||||
|
<para>
|
||||||
|
Yes, any existing PostgreSQL server which is part of the same replication
|
||||||
|
cluster can be registered with &repmgr;. There's no requirement for a
|
||||||
|
standby to have been cloned using &repmgr;.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-register-existing-node" xreflabel="registering an existing node">
|
<sect2 id="faq-repmgr-clone-other-source" >
|
||||||
<title>Can I register an existing PostgreSQL server with repmgr?</title>
|
<title>Can I use a standby not cloned by &repmgr; as a &repmgr; node?</title>
|
||||||
<para>
|
|
||||||
Yes, any existing PostgreSQL server which is part of the same replication
|
|
||||||
cluster can be registered with &repmgr;. There's no requirement for a
|
|
||||||
standby to have been cloned using &repmgr;.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-clone-other-source" >
|
<para>
|
||||||
<title>Can I use a standby not cloned by &repmgr; as a &repmgr; node?</title>
|
For a standby which has been manually cloned or recovered from an external
|
||||||
|
backup manager such as Barman, the command
|
||||||
|
<command><link linkend="repmgr-standby-clone">repmgr standby clone --recovery-conf-only</link></command>
|
||||||
|
can be used to create the correct <filename>recovery.conf</filename> file for
|
||||||
|
use with &repmgr; (and will create a replication slot if required). Once this has been done,
|
||||||
|
<link linkend="repmgr-standby-register">register the node</link> as usual.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<para>
|
<sect2 id="faq-repmgr-recovery-conf" >
|
||||||
For a standby which has been manually cloned or recovered from an external
|
<title>What does &repmgr; write in <filename>recovery.conf</filename>, and what options can be set there?</title>
|
||||||
backup manager such as Barman, the command
|
<para>
|
||||||
<command><link linkend="repmgr-standby-clone">repmgr standby clone --recovery-conf-only</link></command>
|
See section <link linkend="repmgr-standby-clone-recovery-conf">Customising recovery.conf</link>.
|
||||||
can be used to create the correct <filename>recovery.conf</filename> file for
|
</para>
|
||||||
use with &repmgr; (and will create a replication slot if required). Once this has been done,
|
</sect2>
|
||||||
<link linkend="repmgr-standby-register">register the node</link> as usual.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-recovery-conf" >
|
<sect2 id="faq-repmgr-failed-primary-standby" xreflabel="Reintegrate a failed primary as a standby">
|
||||||
<title>What does &repmgr; write in <filename>recovery.conf</filename>, and what options can be set there?</title>
|
<title>How can a failed primary be re-added as a standby?</title>
|
||||||
<para>
|
<para>
|
||||||
See section <link linkend="repmgr-standby-clone-recovery-conf">Customising recovery.conf</link>.
|
This is a two-stage process. First, the failed primary's data directory
|
||||||
</para>
|
must be re-synced with the current primary; secondly the failed primary
|
||||||
</sect2>
|
needs to be re-registered as a standby.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
It's possible to use <command>pg_rewind</command> to re-synchronise the existing data
|
||||||
|
directory, which will usually be much
|
||||||
|
faster than re-cloning the server. However <command>pg_rewind</command> can only
|
||||||
|
be used if PostgreSQL either has <varname>wal_log_hints</varname> enabled, or
|
||||||
|
data checksums were enabled when the cluster was initialized.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note that <command>pg_rewind</command> is available as part of the core PostgreSQL
|
||||||
|
distribution from PostgreSQL 9.5, and as a third-party utility for PostgreSQL 9.3 and 9.4.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
&repmgr; provides the command <command>repmgr node rejoin</command> which can
|
||||||
|
optionally execute <command>pg_rewind</command>; see the <xref linkend="repmgr-node-rejoin"/>
|
||||||
|
documentation for details, in particular the section <xref linkend="repmgr-node-rejoin-pg-rewind"/>.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If <command>pg_rewind</command> cannot be used, then the data directory will need
|
||||||
|
to be re-cloned from scratch.
|
||||||
|
</para>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-failed-primary-standby" xreflabel="Reintegrate a failed primary as a standby">
|
</sect2>
|
||||||
<title>How can a failed primary be re-added as a standby?</title>
|
|
||||||
<para>
|
|
||||||
This is a two-stage process. First, the failed primary's data directory
|
|
||||||
must be re-synced with the current primary; secondly the failed primary
|
|
||||||
needs to be re-registered as a standby.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
It's possible to use <command>pg_rewind</command> to re-synchronise the existing data
|
|
||||||
directory, which will usually be much
|
|
||||||
faster than re-cloning the server. However <command>pg_rewind</command> can only
|
|
||||||
be used if PostgreSQL either has <varname>wal_log_hints</varname> enabled, or
|
|
||||||
data checksums were enabled when the cluster was initialized.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Note that <command>pg_rewind</command> is available as part of the core PostgreSQL
|
|
||||||
distribution from PostgreSQL 9.5, and as a third-party utility for PostgreSQL 9.3 and 9.4.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
&repmgr; provides the command <command>repmgr node rejoin</command> which can
|
|
||||||
optionally execute <command>pg_rewind</command>; see the <xref linkend="repmgr-node-rejoin"/>
|
|
||||||
documentation for details, in particular the section <xref linkend="repmgr-node-rejoin-pg-rewind"/>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If <command>pg_rewind</command> cannot be used, then the data directory will need
|
|
||||||
to be re-cloned from scratch.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</sect2>
|
<sect2 id="faq-repmgr-check-configuration" xreflabel="Check PostgreSQL configuration">
|
||||||
|
<title>Is there an easy way to check my primary server is correctly configured for use with &repmgr;?</title>
|
||||||
|
<para>
|
||||||
|
Execute <command><link linkend="repmgr-standby-clone">repmgr standby clone</link></command>
|
||||||
|
with the <literal>--dry-run</literal> option; this will report any configuration problems
|
||||||
|
which need to be rectified.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-check-configuration" xreflabel="Check PostgreSQL configuration">
|
<sect2 id="faq-repmgr-clone-skip-config-files" xreflabel="">
|
||||||
<title>Is there an easy way to check my primary server is correctly configured for use with &repmgr;?</title>
|
<title>When cloning a standby, how can I get &repmgr; to copy
|
||||||
<para>
|
<filename>postgresql.conf</filename> and <filename>pg_hba.conf</filename> from the PostgreSQL configuration
|
||||||
Execute <command><link linkend="repmgr-standby-clone">repmgr standby clone</link></command>
|
directory in <filename>/etc</filename>?</title>
|
||||||
with the <literal>--dry-run</literal> option; this will report any configuration problems
|
<para>
|
||||||
which need to be rectified.
|
Use the command line option <literal>--copy-external-config-files</literal>. For more details
|
||||||
</para>
|
see <xref linkend="repmgr-standby-clone-config-file-copying"/>.
|
||||||
</sect2>
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-clone-skip-config-files" xreflabel="">
|
<sect2 id="faq-repmgr-shared-preload-libaries-no-repmgrd" xreflabel="shared_preload_libraries without repmgrd">
|
||||||
<title>When cloning a standby, how can I get &repmgr; to copy
|
<title>Do I need to include <literal>shared_preload_libraries = 'repmgr'</literal>
|
||||||
<filename>postgresql.conf</filename> and <filename>pg_hba.conf</filename> from the PostgreSQL configuration
|
in <filename>postgresql.conf</filename> if I'm not using &repmgrd;?</title>
|
||||||
directory in <filename>/etc</filename>?</title>
|
<para>
|
||||||
<para>
|
No, the <literal>repmgr</literal> shared library is only needed when running &repmgrd;.
|
||||||
Use the command line option <literal>--copy-external-config-files</literal>. For more details
|
If you later decide to run &repmgrd;, you just need to add
|
||||||
see <xref linkend="repmgr-standby-clone-config-file-copying"/>.
|
<literal>shared_preload_libraries = 'repmgr'</literal> and restart PostgreSQL.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-shared-preload-libaries-no-repmgrd" xreflabel="shared_preload_libraries without repmgrd">
|
<sect2 id="faq-repmgr-permissions" xreflabel="Replication permission problems">
|
||||||
<title>Do I need to include <literal>shared_preload_libraries = 'repmgr'</literal>
|
<title>I've provided replication permission for the <literal>repmgr</literal> user in <filename>pg_hba.conf</filename>
|
||||||
in <filename>postgresql.conf</filename> if I'm not using &repmgrd;?</title>
|
but <command>repmgr</command>/&repmgrd; complains it can't connect to the server... Why?</title>
|
||||||
<para>
|
<para>
|
||||||
No, the <literal>repmgr</literal> shared library is only needed when running &repmgrd;.
|
<command>repmgr</command> and &repmgrd; need to be able to connect to the repmgr database
|
||||||
If you later decide to run &repmgrd;, you just need to add
|
with a normal connection to query metadata. The <literal>replication</literal> connection
|
||||||
<literal>shared_preload_libraries = 'repmgr'</literal> and restart PostgreSQL.
|
permission is for PostgreSQL's streaming replication (and doesn't necessarily need to be the <literal>repmgr</literal> user).
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-permissions" xreflabel="Replication permission problems">
|
<sect2 id="faq-repmgr-clone-provide-primary-conninfo" xreflabel="Providing primary connection parameters">
|
||||||
<title>I've provided replication permission for the <literal>repmgr</literal> user in <filename>pg_hba.conf</filename>
|
<title>When cloning a standby, why do I need to provide the connection parameters
|
||||||
but <command>repmgr</command>/&repmgrd; complains it can't connect to the server... Why?</title>
|
for the primary server on the command line, not in the configuration file?</title>
|
||||||
<para>
|
<para>
|
||||||
<command>repmgr</command> and &repmgrd; need to be able to connect to the repmgr database
|
Cloning a standby is a one-time action; the role of the server being cloned
|
||||||
with a normal connection to query metadata. The <literal>replication</literal> connection
|
from could change, so fixing it in the configuration file would create
|
||||||
permission is for PostgreSQL's streaming replication (and doesn't necessarily need to be the <literal>repmgr</literal> user).
|
confusion. If &repmgr; needs to establish a connection to the primary
|
||||||
</para>
|
server, it can retrieve this from the <literal>repmgr.nodes</literal> table on the local
|
||||||
</sect2>
|
node, and if necessary scan the replication cluster until it locates the active primary.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-clone-provide-primary-conninfo" xreflabel="Providing primary connection parameters">
|
<sect2 id="faq-repmgr-clone-waldir-xlogdir" xreflabel="Providing a custom WAL directory">
|
||||||
<title>When cloning a standby, why do I need to provide the connection parameters
|
<title>When cloning a standby, how do I ensure the WAL files are placed in a custom directory?</title>
|
||||||
for the primary server on the command line, not in the configuration file?</title>
|
<para>
|
||||||
<para>
|
Provide the option <literal>--waldir</literal> (<literal>--xlogdir</literal> in PostgreSQL 9.6
|
||||||
Cloning a standby is a one-time action; the role of the server being cloned
|
and earlier) with the absolute path to the WAL directory in <varname>pg_basebackup_options</varname>.
|
||||||
from could change, so fixing it in the configuration file would create
|
For more details see <xref linkend="cloning-advanced-pg-basebackup-options"/>.
|
||||||
confusion. If &repmgr; needs to establish a connection to the primary
|
</para>
|
||||||
server, it can retrieve this from the <literal>repmgr.nodes</literal> table on the local
|
</sect2>
|
||||||
node, and if necessary scan the replication cluster until it locates the active primary.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-clone-waldir-xlogdir" xreflabel="Providing a custom WAL directory">
|
<sect2 id="faq-repmgr-events-no-fkey" xreflabel="No foreign key on node_id in repmgr.events">
|
||||||
<title>When cloning a standby, how do I ensure the WAL files are placed in a custom directory?</title>
|
<title>Why is there no foreign key on the <literal>node_id</literal> column in the <literal>repmgr.events</literal>
|
||||||
<para>
|
table?</title>
|
||||||
Provide the option <literal>--waldir</literal> (<literal>--xlogdir</literal> in PostgreSQL 9.6
|
<para>
|
||||||
and earlier) with the absolute path to the WAL directory in <varname>pg_basebackup_options</varname>.
|
Under some circumstances event notifications can be generated for servers
|
||||||
For more details see <xref linkend="cloning-advanced-pg-basebackup-options"/>.
|
which have not yet been registered; it's also useful to retain a record
|
||||||
</para>
|
of events which includes servers removed from the replication cluster
|
||||||
</sect2>
|
which no longer have an entry in the <literal>repmgr.nodes</literal> table.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgr-events-no-fkey" xreflabel="No foreign key on node_id in repmgr.events">
|
<sect2 id="faq-repmgr-recovery-conf-quoted-values" xreflabel="Quoted values in recovery.conf">
|
||||||
<title>Why is there no foreign key on the <literal>node_id</literal> column in the <literal>repmgr.events</literal>
|
<title>Why are some values in <filename>recovery.conf</filename> surrounded by pairs of single quotes?</title>
|
||||||
table?</title>
|
<para>
|
||||||
<para>
|
This is to ensure that user-supplied values which are written as parameter values in <filename>recovery.conf</filename>
|
||||||
Under some circumstances event notifications can be generated for servers
|
are escaped correctly and do not cause errors when <filename>recovery.conf</filename> is parsed.
|
||||||
which have not yet been registered; it's also useful to retain a record
|
</para>
|
||||||
of events which includes servers removed from the replication cluster
|
<para>
|
||||||
which no longer have an entry in the <literal>repmgr.nodes</literal> table.
|
The escaping is performed by an internal PostgreSQL routine, which leaves strings consisting
|
||||||
</para>
|
of digits and alphabetical characters only as-is, but wraps everything else in pairs of single quotes,
|
||||||
</sect2>
|
even if the string does not contain any characters which need escaping.
|
||||||
|
</para>
|
||||||
<sect2 id="faq-repmgr-recovery-conf-quoted-values" xreflabel="Quoted values in recovery.conf">
|
</sect2>
|
||||||
<title>Why are some values in <filename>recovery.conf</filename> surrounded by pairs of single quotes?</title>
|
|
||||||
<para>
|
|
||||||
This is to ensure that user-supplied values which are written as parameter values in <filename>recovery.conf</filename>
|
|
||||||
are escaped correctly and do not cause errors when <filename>recovery.conf</filename> is parsed.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The escaping is performed by an internal PostgreSQL routine, which leaves strings consisting
|
|
||||||
of digits and alphabetical characters only as-is, but wraps everything else in pairs of single quotes,
|
|
||||||
even if the string does not contain any characters which need escaping.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="faq-repmgrd" xreflabel="repmgrd">
|
<sect1 id="faq-repmgrd" xreflabel="repmgrd">
|
||||||
<title>&repmgrd;</title>
|
<title>&repmgrd;</title>
|
||||||
|
|
||||||
|
|
||||||
<sect2 id="faq-repmgrd-prevent-promotion" xreflabel="Prevent standby from being promoted to primary">
|
<sect2 id="faq-repmgrd-prevent-promotion" xreflabel="Prevent standby from being promoted to primary">
|
||||||
<title>How can I prevent a node from ever being promoted to primary?</title>
|
<title>How can I prevent a node from ever being promoted to primary?</title>
|
||||||
<para>
|
<para>
|
||||||
In <filename>repmgr.conf</filename>, set its priority to a value of <literal>0</literal>; apply the changed setting with
|
In <filename>repmgr.conf</filename>, set its priority to a value of <literal>0</literal>; apply the changed setting with
|
||||||
<command><link linkend="repmgr-standby-register">repmgr standby register --force</link></command>.
|
<command><link linkend="repmgr-standby-register">repmgr standby register --force</link></command>.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Additionally, if <varname>failover</varname> is set to <literal>manual</literal>, the node will never
|
Additionally, if <varname>failover</varname> is set to <literal>manual</literal>, the node will never
|
||||||
be considered as a promotion candidate.
|
be considered as a promotion candidate.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgrd-delayed-standby" xreflabel="Delayed standby support">
|
<sect2 id="faq-repmgrd-delayed-standby" xreflabel="Delayed standby support">
|
||||||
<title>Does &repmgrd; support delayed standbys?</title>
|
<title>Does &repmgrd; support delayed standbys?</title>
|
||||||
<para>
|
<para>
|
||||||
&repmgrd; can monitor delayed standbys - those set up with
|
&repmgrd; can monitor delayed standbys - those set up with
|
||||||
<varname>recovery_min_apply_delay</varname> set to a non-zero value
|
<varname>recovery_min_apply_delay</varname> set to a non-zero value
|
||||||
in <filename>recovery.conf</filename> - but as it's not currently possible
|
in <filename>recovery.conf</filename> - but as it's not currently possible
|
||||||
to directly examine the value applied to the standby, &repmgrd;
|
to directly examine the value applied to the standby, &repmgrd;
|
||||||
may not be able to properly evaluate the node as a promotion candidate.
|
may not be able to properly evaluate the node as a promotion candidate.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
We recommend that delayed standbys are explicitly excluded from promotion
|
We recommend that delayed standbys are explicitly excluded from promotion
|
||||||
by setting <varname>priority</varname> to <literal>0</literal> in
|
by setting <varname>priority</varname> to <literal>0</literal> in
|
||||||
<filename>repmgr.conf</filename>.
|
<filename>repmgr.conf</filename>.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Note that after registering a delayed standby, &repmgrd; will only start
|
Note that after registering a delayed standby, &repmgrd; will only start
|
||||||
once the metadata added in the primary node has been replicated.
|
once the metadata added in the primary node has been replicated.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgrd-logfile-rotate" xreflabel="repmgrd logfile rotation">
|
<sect2 id="faq-repmgrd-logfile-rotate" xreflabel="repmgrd logfile rotation">
|
||||||
<title>How can I get &repmgrd; to rotate its logfile?</title>
|
<title>How can I get &repmgrd; to rotate its logfile?</title>
|
||||||
<para>
|
<para>
|
||||||
Configure your system's <literal>logrotate</literal> service to do this; see <xref linkend="repmgrd-log-rotation"/>.
|
Configure your system's <literal>logrotate</literal> service to do this; see <xref linkend="repmgrd-log-rotation"/>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgrd-recloned-no-start" xreflabel="repmgrd not restarting after node cloned">
|
<sect2 id="faq-repmgrd-recloned-no-start" xreflabel="repmgrd not restarting after node cloned">
|
||||||
<title>I've recloned a failed primary as a standby, but &repmgrd; refuses to start?</title>
|
<title>I've recloned a failed primary as a standby, but &repmgrd; refuses to start?</title>
|
||||||
<para>
|
<para>
|
||||||
Check you registered the standby after recloning. If unregistered, the standby
|
Check you registered the standby after recloning. If unregistered, the standby
|
||||||
cannot be considered as a promotion candidate even if <varname>failover</varname> is set to
|
cannot be considered as a promotion candidate even if <varname>failover</varname> is set to
|
||||||
<literal>automatic</literal>, which is probably not what you want. &repmgrd; will start if
|
<literal>automatic</literal>, which is probably not what you want. &repmgrd; will start if
|
||||||
<varname>failover</varname> is set to <literal>manual</literal> so the node's replication status can still
|
<varname>failover</varname> is set to <literal>manual</literal> so the node's replication status can still
|
||||||
be monitored, if desired.
|
be monitored, if desired.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgrd-pg-bindir" xreflabel="repmgrd does not apply pg_bindir to promote_command or follow_command">
|
<sect2 id="faq-repmgrd-pg-bindir" xreflabel="repmgrd does not apply pg_bindir to promote_command or follow_command">
|
||||||
<title>
|
<title>
|
||||||
&repmgrd; ignores pg_bindir when executing <varname>promote_command</varname> or <varname>follow_command</varname>
|
&repmgrd; ignores pg_bindir when executing <varname>promote_command</varname> or <varname>follow_command</varname>
|
||||||
</title>
|
</title>
|
||||||
<para>
|
<para>
|
||||||
<varname>promote_command</varname> or <varname>follow_command</varname> can be user-defined scripts,
|
<varname>promote_command</varname> or <varname>follow_command</varname> can be user-defined scripts,
|
||||||
so &repmgr; will not apply <option>pg_bindir</option> even if excuting &repmgr;. Always provide the full
|
so &repmgr; will not apply <option>pg_bindir</option> even if excuting &repmgr;. Always provide the full
|
||||||
path; see <xref linkend="repmgrd-automatic-failover-configuration"/> for more details.
|
path; see <xref linkend="repmgrd-automatic-failover-configuration"/> for more details.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="faq-repmgrd-startup-no-upstream" xreflabel="repmgrd does not start if upstream node is not running">
|
<sect2 id="faq-repmgrd-startup-no-upstream" xreflabel="repmgrd does not start if upstream node is not running">
|
||||||
<title>
|
<title>
|
||||||
&repmgrd; aborts startup with the error "<literal>upstream node must be running before repmgrd can start</literal>"
|
&repmgrd; aborts startup with the error "<literal>upstream node must be running before repmgrd can start</literal>"
|
||||||
</title>
|
</title>
|
||||||
<para>
|
<para>
|
||||||
&repmgrd; does this to avoid starting up on a replication cluster
|
&repmgrd; does this to avoid starting up on a replication cluster
|
||||||
which is not in a healthy state. If the upstream is unavailable, &repmgrd;
|
which is not in a healthy state. If the upstream is unavailable, &repmgrd;
|
||||||
may initiate a failover immediately after starting up, which could have unintended side-effects,
|
may initiate a failover immediately after starting up, which could have unintended side-effects,
|
||||||
particularly if &repmgrd; is not running on other nodes.
|
particularly if &repmgrd; is not running on other nodes.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
In particular, it's possible that the node's local copy of the <literal>repmgr.nodes</literal> copy
|
In particular, it's possible that the node's local copy of the <literal>repmgr.nodes</literal> copy
|
||||||
is out-of-date, which may lead to incorrect failover behaviour.
|
is out-of-date, which may lead to incorrect failover behaviour.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The onus is therefore on the adminstrator to manually set the cluster to a stable, healthy state before
|
The onus is therefore on the adminstrator to manually set the cluster to a stable, healthy state before
|
||||||
starting &repmgrd;.
|
starting &repmgrd;.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
</appendix>
|
</appendix>
|
||||||
|
|||||||
Reference in New Issue
Block a user