mirror of
https://github.com/EnterpriseDB/repmgr.git
synced 2026-03-23 15:16:29 +00:00
931da14df1
"repmgr daemon" can be interpreted to mean the commands affect the local daemon process only. Rename the commands which affect the entire cluster to "repmgr service ...". The "repmgr daemon ..." form of the affected commands is retained for backwards compatibility.
531 lines
18 KiB
XML
531 lines
18 KiB
XML
<chapter id="upgrading-repmgr" xreflabel="Upgrading repmgr">
|
|
<title>Upgrading repmgr</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
</indexterm>
|
|
|
|
|
|
<para>
|
|
&repmgr; is updated regularly with minor releases (e.g. 4.0.1 to 4.0.2)
|
|
containing bugfixes and other minor improvements. Any substantial new
|
|
functionality will be included in a major release (e.g. 4.0 to 4.1).
|
|
</para>
|
|
|
|
<sect1 id="upgrading-repmgr-extension" xreflabel="Upgrading repmgr 4.x and later">
|
|
<title>Upgrading repmgr 4.x and later</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
<secondary>repmgr 4.x and later</secondary>
|
|
</indexterm>
|
|
<para>
|
|
From version 4, &repmgr; consists of three elements:
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
|
|
<listitem>
|
|
<simpara>
|
|
the <application>repmgr</application> and &repmgrd; executables
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
the objects for the &repmgr; PostgreSQL extension (SQL files for creating/updating
|
|
repmgr metadata, and the extension control file)
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
the shared library module used by &repmgrd; which
|
|
is resident in the PostgreSQL backend
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
With <emphasis>minor releases</emphasis>, usually changes are only made to the <application>repmgr</application>
|
|
and &repmgrd; executables. In this case, the upgrade is quite straightforward,
|
|
and is simply a case of installing the new version, and restarting &repmgrd;
|
|
(if running).
|
|
</para>
|
|
|
|
<para>
|
|
For <emphasis>major releases</emphasis>, the &repmgr; PostgreSQL extension will need to be updated
|
|
to the latest version. Additionally, if the shared library module has been updated (this is sometimes,
|
|
but not always the case), PostgreSQL itself will need to be restarted on each node.
|
|
</para>
|
|
<important>
|
|
<para>
|
|
Always check the <link linkend="appendix-release-notes">release notes</link> for every
|
|
release as they may contain upgrade instructions particular to individual versions.
|
|
</para>
|
|
</important>
|
|
|
|
<sect2 id="upgrading-minor-version" xreflabel="Upgrading a minor version release">
|
|
<title>Upgrading a minor version release</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
<secondary>minor release</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The process for installing minor version upgrades is quite straightforward:
|
|
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
|
|
<listitem>
|
|
<simpara>
|
|
install the new &repmgr; version
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
restart &repmgrd; on all nodes where it is running
|
|
</simpara>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Some packaging systems (e.g. <link linkend="packages-debian-ubuntu">Debian/Ubuntu</link>
|
|
may restart &repmgrd; as part of the package upgrade process.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Minor version upgrades can be performed in any order on the nodes in the replication
|
|
cluster.
|
|
</para>
|
|
|
|
<para>
|
|
A PostgreSQL restart is <emphasis>not</emphasis> required for minor version upgrades.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
The same &repmgr; "major version" (e.g. <literal>4.2</literal>) must be
|
|
installed on all nodes in the replication cluster. While it's possible to have differing
|
|
&repmgr; "minor versions" (e.g. <literal>4.2.1</literal>) on different nodes,
|
|
we strongly recommend updating all nodes to the latest minor version.
|
|
</para>
|
|
</note>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="upgrading-major-version" xreflabel="Upgrading a major version release">
|
|
<title>Upgrading a major version release</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
<secondary>major release</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
"major version" upgrades need to be planned more carefully, as they may include
|
|
changes to the &repmgr; metadata (which need to be propagated from the primary to all
|
|
standbys) and/or changes to the shared object file used by &repmgrd;
|
|
(which require a PostgreSQL restart).
|
|
</para>
|
|
<para>
|
|
With this in mind,
|
|
</para>
|
|
|
|
<para>
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Stop &repmgrd; (if in use) on all nodes where it is running.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Disable the &repmgrd; service on all nodes where it is in use;
|
|
this is to prevent packages from prematurely restarting &repmgrd;.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Install the updated package (or compile the updated source) on all nodes.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If running a <literal>systemd</literal>-based Linux distribution, execute (as <literal>root</literal>,
|
|
or with appropriate <literal>sudo</literal> permissions):
|
|
<programlisting>
|
|
systemctl daemon-reload</programlisting>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
If the &repmgr; shared library module has been updated (check the <link linkend="appendix-release-notes">release notes</link>!),
|
|
restart PostgreSQL, then &repmgrd; (if in use) on each node,
|
|
The order in which this is applied to individual nodes is not critical,
|
|
and it's also fine to restart PostgreSQL on all nodes first before starting &repmgrd;.
|
|
</simpara>
|
|
<simpara>
|
|
Note that if the upgrade requires a PostgreSQL restart, &repmgrd;
|
|
will only function correctly once all nodes have been restarted.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
On the primary node, execute
|
|
<programlisting>
|
|
ALTER EXTENSION repmgr UPDATE</programlisting>
|
|
in the database where &repmgr; is installed.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Reenable the &repmgrd; service on all nodes where it is in use, and
|
|
ensure it is running.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
</para>
|
|
<tip>
|
|
<para>
|
|
If the &repmgr; upgrade requires a PostgreSQL restart, combine the &repmgr; upgrade
|
|
with a PostgreSQL minor version upgrade, which will require a restart in any case.
|
|
New PostgreSQL minor version are usually released every couple of months.
|
|
</para>
|
|
</tip>
|
|
</sect2>
|
|
|
|
<sect2 id="upgrading-check-repmgrd" xreflabel="Checking repmgrd status after an upgrade">
|
|
<title>Checking repmgrd status after an upgrade</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
<secondary>checking repmgrd status</secondary>
|
|
</indexterm>
|
|
<para>
|
|
From <link linkend="release-4.2">repmgr 4.2</link>, once the upgrade is complete, execute the
|
|
<command><link linkend="repmgr-service-status">repmgr service status</link></command>
|
|
(&repmgr; 4.2 - 4.4: <command><link linkend="repmgr-service-status">repmgr daemon status</link></command>)
|
|
command (on any node) to show an overview of the status of &repmgrd; on all nodes.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="upgrading-and-pg-upgrade" xreflabel="pg_upgrade and repmgr">
|
|
<title>pg_upgrade and repmgr</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
<secondary>pg_upgrade</secondary>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>pg_upgrade</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> requires that if any functions are
|
|
dependent on a shared library, this library must be present in both
|
|
the old and new installations before <application>pg_upgrade</application>
|
|
can be executed.
|
|
</para>
|
|
<para>
|
|
To minimize the risk of any upgrade issues (particularly if an upgrade to
|
|
a new major &repmgr; version is involved), we recommend upgrading
|
|
&repmgr; on the old server <emphasis>before</emphasis> running
|
|
<application>pg_upgrade</application> to ensure that old and new
|
|
versions are the same.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
This issue applies to any PostgreSQL extension which has
|
|
dependencies on a shared library.
|
|
</simpara>
|
|
</note>
|
|
<para>
|
|
For further details please see the <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html">pg_upgrade documentation</ulink>.
|
|
</para>
|
|
<para>
|
|
If replication slots are in use, bear in mind these will <emphasis>not</emphasis>
|
|
be recreated by <application>pg_upgrade</application>. These will need to
|
|
be recreated manually.
|
|
</para>
|
|
<tip>
|
|
<para>
|
|
Use <command><link linkend="repmgr-node-check">repmgr node check</link></command>
|
|
to determine which replication slots need to be recreated.
|
|
</para>
|
|
</tip>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="upgrading-from-repmgr-3" xreflabel="Upgrading from repmgr 3.x">
|
|
<title>Upgrading from repmgr 3.x</title>
|
|
|
|
<indexterm>
|
|
<primary>upgrading</primary>
|
|
<secondary>from repmgr 3.x</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The upgrade process consists of two steps:
|
|
<orderedlist>
|
|
<listitem>
|
|
<simpara>
|
|
converting the repmgr.conf configuration files
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
upgrading the repmgr schema using <command>CREATE EXTENSION</command>
|
|
</simpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>
|
|
A script is provided to assist with converting <filename>repmgr.conf</filename>.
|
|
</para>
|
|
<para>
|
|
The schema upgrade (which converts the &repmgr; metadata into
|
|
a packaged PostgreSQL extension) is normally carried out
|
|
automatically when the &repmgr; extension is created.
|
|
</para>
|
|
<para>
|
|
The shared library has been renamed from <literal>repmgr_funcs</literal> to
|
|
<literal>repmgr</literal> - if it's set in <varname>shared_preload_libraries</varname>
|
|
in <filename>postgresql.conf</filename> it will need to be updated to the new name:
|
|
<programlisting>
|
|
shared_preload_libraries = 'repmgr'</programlisting>
|
|
</para>
|
|
|
|
<sect2 id="converting-repmgr-conf">
|
|
<title>Converting repmgr.conf configuration files</title>
|
|
<para>
|
|
With a completely new repmgr version, we've taken the opportunity
|
|
to rename some configuration items for
|
|
clarity and consistency, both between the configuration file and
|
|
the column names in <structname>repmgr.nodes</structname>
|
|
(e.g. <varname>node</varname> to <varname>node_id</varname>), and
|
|
also for consistency with PostgreSQL naming conventions
|
|
(e.g. <varname>loglevel</varname> to <varname>log_level</varname>).
|
|
</para>
|
|
<para>
|
|
Other configuration items have been changed to command line options,
|
|
and vice-versa, e.g. to avoid hard-coding items such as a a node's
|
|
upstream ID, which might change over time.
|
|
</para>
|
|
<para>
|
|
&repmgr; will issue a warning about deprecated/altered options.
|
|
</para>
|
|
<sect3>
|
|
<title>Changed parameters in "repmgr.conf"</title>
|
|
<para>
|
|
Following parameters have been added:
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
<listitem>
|
|
<simpara><varname>data_directory</varname>: this is mandatory and must
|
|
contain the path to the node's data directory</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><varname>monitoring_history</varname>: this replaces the
|
|
&repmgrd; command line option
|
|
<literal>--monitoring-history</literal></simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Following parameters have been renamed:
|
|
</para>
|
|
<table tocentry="1" id="repmgr3-repmgr4-renamed-parameters">
|
|
<title>Parameters renamed in repmgr4</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>repmgr3</entry>
|
|
<entry>repmgr4</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><varname>node</varname></entry>
|
|
<entry><varname>node_id</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>loglevel</varname></entry>
|
|
<entry><varname>log_level</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>logfacility</varname></entry>
|
|
<entry><varname>log_facility</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>logfile</varname></entry>
|
|
<entry><varname>log_file</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>barman_server</varname></entry>
|
|
<entry><varname>barman_host</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>master_reponse_timeout</varname></entry>
|
|
<entry><varname>async_query_timeout</varname></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<note>
|
|
<para>
|
|
From &repmgr; 4, <literal>barman_server</literal> refers
|
|
to the server configured in Barman (in &repmgr; 3, the deprecated
|
|
<literal>cluster</literal> parameter was used for this);
|
|
the physical Barman hostname is configured with
|
|
<literal>barman_host</literal> (see <xref linkend="cloning-from-barman-prerequisites"/>
|
|
for details).
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Following parameters have been removed:
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
<listitem>
|
|
<simpara><varname>cluster</varname>: is no longer required and will
|
|
be ignored.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><varname>upstream_node</varname>: is replaced by the
|
|
command-line parameter <literal>--upstream-node-id</literal></simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Conversion script</title>
|
|
<para>
|
|
To assist with conversion of <filename>repmgr.conf</filename> files, a Perl script
|
|
is provided in <filename>contrib/convert-config.pl</filename>.
|
|
Use like this:
|
|
<programlisting>
|
|
$ ./convert-config.pl /etc/repmgr.conf
|
|
node_id=2
|
|
node_name=node2
|
|
conninfo=host=node2 dbname=repmgr user=repmgr connect_timeout=2
|
|
pg_ctl_options='-l /var/log/postgres/startup.log'
|
|
rsync_options=--exclude=postgresql.local.conf --archive
|
|
log_level=INFO
|
|
pg_basebackup_options=--no-slot
|
|
data_directory=</programlisting>
|
|
</para>
|
|
<para>
|
|
The converted file is printed to <literal>STDOUT</literal> and the original file is not
|
|
changed.
|
|
</para>
|
|
<para>
|
|
Please note that the the conversion script will add an empty
|
|
placeholder parameter for <varname>data_directory</varname>, which
|
|
is a required parameter in repmgr4 and which <emphasis>must</emphasis>
|
|
be provided.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Upgrading the repmgr schema</title>
|
|
<para>
|
|
Ensure &repmgrd; is not running, or any cron jobs which execute the
|
|
<command>repmgr</command> binary.
|
|
</para>
|
|
<para>
|
|
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>
|
|
<para>
|
|
If your repmgr version is 3.1.1 or earlier, you will need to update
|
|
the schema to the latest version in the 3.x series (3.3.2) before
|
|
converting the installation to repmgr 4.
|
|
</para>
|
|
<para>
|
|
To do this, apply the following upgrade scripts as appropriate for
|
|
your current version:
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
<listitem>
|
|
<simpara>
|
|
<ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/REL3_3_STABLE/sql/repmgr3.0_repmgr3.1.sql">repmgr3.0_repmgr3.1.sql</ulink></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/REL3_3_STABLE/sql/repmgr3.1.1_repmgr3.1.2.sql">repmgr3.1.1_repmgr3.1.2.sql</ulink></simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
For more details see the
|
|
<ulink url="https://repmgr.org/release-notes-3.3.2.html#upgrading">repmgr 3 upgrade notes</ulink>.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Manually create the repmgr extension</title>
|
|
<para>
|
|
In the database used by the existing &repmgr; installation, execute:
|
|
<programlisting>
|
|
CREATE EXTENSION repmgr FROM unpackaged;</programlisting>
|
|
</para>
|
|
<para>
|
|
This will move and convert all objects from the existing schema
|
|
into the new, standard <literal>repmgr</literal> schema.
|
|
</para>
|
|
<note>
|
|
<simpara>there must be only one schema matching <literal>repmgr_%</literal> in the
|
|
database, otherwise this step may not work.
|
|
</simpara>
|
|
</note>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Re-register each node</title>
|
|
<para>
|
|
This is necessary to update the <literal>repmgr</literal> metadata with some additional items.
|
|
</para>
|
|
<para>
|
|
On the primary node, execute e.g.
|
|
<programlisting>
|
|
repmgr primary register -f /etc/repmgr.conf --force</programlisting>
|
|
</para>
|
|
<para>
|
|
On each standby node, execute e.g.
|
|
<programlisting>
|
|
repmgr standby register -f /etc/repmgr.conf --force</programlisting>
|
|
</para>
|
|
<para>
|
|
Check the data is updated as expected by examining the <structname>repmgr.nodes</structname>
|
|
table; restart &repmgrd; if required.
|
|
</para>
|
|
<para>
|
|
The original <literal>repmgr_$cluster</literal> schema can be dropped at any time.
|
|
</para>
|
|
<tip>
|
|
<simpara>
|
|
If you don't care about any data from the existing &repmgr; installation,
|
|
(e.g. the contents of the <structname>events</structname> and <structname>monitoring</structname>
|
|
tables), the manual <command>CREATE EXTENSION</command> step can be skipped; just re-register
|
|
each node, starting with the primary node, and the <literal>repmgr</literal> extension will be
|
|
automatically created.
|
|
</simpara>
|
|
</tip>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|