mirror of
https://github.com/EnterpriseDB/repmgr.git
synced 2026-03-22 22:56:29 +00:00
598 lines
21 KiB
XML
598 lines
21 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>
|
|
A minor release upgrade involves updating &repmgr; from one minor release to another
|
|
minor release within the same major release (e.g. <literal>5.3.1</literal> to <literal>5.3.2</literal>).
|
|
An upgrade between minor releases of differing major releases (e.g. <literal>5.2.1</literal> to <literal>5.3.2</literal>)
|
|
is a <link linkend="upgrading-major-version">major upgrade</link>.
|
|
</para>
|
|
<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 usually <emphasis>not</emphasis> required for minor version upgrades
|
|
within the same major version (e.g. <literal>5.3.1</literal> to <literal>5.3.2</literal>).
|
|
Be sure to check the <link linkend="appendix-release-notes">release notes</link>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
The same &repmgr; "major version" (e.g. <literal>5.3</literal>) must be
|
|
installed on all nodes in the replication cluster. While it's possible to have differing
|
|
&repmgr; "minor versions" (e.g. <literal>5.3.1</literal> and <literal>5.3.2</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.
|
|
</para>
|
|
<para>
|
|
New PostgreSQL minor versions are usually released every couple of months;
|
|
see the <ulink url="https://www.postgresql.org/developer/roadmap/">Roadmap</ulink>
|
|
for the current schedule.
|
|
</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>
|
|
|
|
<sect2 id="upgrading-pg-upgrade-standby" xreflabel="pg_upgrade and upgrading standbys">
|
|
<title>Upgrading standbys with pg_upgrade and rsync</title>
|
|
<para>
|
|
If you are intending to upgrade a standby using the <command>rsync</command> method described
|
|
in the <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html#PGUPGRADE-STEP-REPLICAS">pg_upgrade documentation</ulink>,
|
|
you <emphasis>must</emphasis> ensure the standby's replication configuration is present and correct
|
|
before starting the standby.
|
|
</para>
|
|
<para>
|
|
Use <link linkend="repmgr-standby-clone">repmgr standby clone --replication-conf-only</link> to generate
|
|
the correct replication configuration.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
If upgrading from PostgreSQL 11 or earlier, be sure to delete <filename>recovery.conf</filename>, if present,
|
|
otherwise PostgreSQL will refuse to start.
|
|
</para>
|
|
</tip>
|
|
|
|
</sect2>
|
|
|
|
|
|
</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 <filename>repmgr.conf</filename> configuration files
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
upgrading the repmgr schema using <command>CREATE EXTENSION</command> (PostgreSQL 12 and earlier)
|
|
</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 from &repmgr; 4. This must be manually modified to contain
|
|
the correct data directory.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Upgrading the repmgr schema (PostgreSQL 12 and earlier)</title>
|
|
<para>
|
|
Ensure &repmgrd; is not running, or any cron jobs which execute the
|
|
<command>repmgr</command> binary.
|
|
</para>
|
|
<para>
|
|
Install the latest &repmgr; package; 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>
|
|
<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 following steps can be skipped; proceed to <xref linkend="upgrade-reregister-nodes"/>.
|
|
</simpara>
|
|
</tip>
|
|
|
|
<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/EnterpriseDB/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/EnterpriseDB/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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Upgrading the repmgr schema (PostgreSQL 13 and later)</title>
|
|
<para>
|
|
Beginning with PostgreSQL 13, the <command>CREATE EXTENSION ... FROM unpackaged</command>
|
|
syntax is no longer available. In the unlikely event you have ended up with an
|
|
installation running PostgreSQL 13 or later and containing the legacy &repmgr;
|
|
schema, there is no convenient way of upgrading this; instead you'll just need
|
|
to re-register the nodes as detailed in <link linkend="upgrade-reregister-nodes">the following section</link>,
|
|
which will create the &repmgr; extension automatically.
|
|
</para>
|
|
<para>
|
|
Any historical data you wish to retain (e.g. the contents of the <structname>events</structname>
|
|
and <structname>monitoring</structname> tables) will need to be exported manually.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="upgrade-reregister-nodes">
|
|
<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>
|
|
If not already present (e.g. after executing <command>CREATE EXTENSION repmgr FROM unpackaged</command>),
|
|
the &repmgr; extension will be automatically created by <command>repmgr primary register</command>.
|
|
</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>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="upgrade-drop-repmgr-cluster-schema">
|
|
<title>Drop the legacy repmgr schema</title>
|
|
<para>
|
|
Once the cluster has been registered with the current &repmgr; version, the legacy
|
|
<literal>repmgr_$cluster</literal> schema can be dropped at any time with:
|
|
<programlisting>
|
|
DROP SCHEMA repmgr_$cluster CASCADE</programlisting>
|
|
(substitute <literal>$cluster</literal> with the value of the <varname>clustername</varname>
|
|
variable used in &repmgr; 3.x).
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</chapter>
|