<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
  functionality will be included in a feature release (e.g. 4.0.x to 4.1.x).
 </para>

 <sect1 id="upgrading-repmgr-extension" xreflabel="Upgrading repmgr 4.x and later">
  <indexterm>
   <primary>upgrading</primary>
   <secondary>repmgr 4.x and later</secondary>
  </indexterm>
  <title>Upgrading repmgr 4.x and later</title>
  <para>
    &repmgr; 4.x is implemented as a PostgreSQL extension; normally the upgrade consists
    of the two following steps:
    <orderedlist>
      <listitem>
        <simpara>
          Install the updated package (or compile the updated source)
        </simpara>
      </listitem>
      <listitem>
        <simpara>
          In the database where the &repmgr; extension is installed, execute
          <command>ALTER EXTENSION repmgr UPDATE</command>.
        </simpara>
      </listitem>
    </orderedlist>
  </para>

  <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>

  <para>
    If the <application>repmgrd</application> daemon is in use, we recommend stopping it
    before upgrading &repmgr;.
  </para>
  <para>
    Note that it may be necessary to restart the PostgreSQL server if the upgrade contains
    changes to the shared object file used by <application>repmgrd</application>; check the
    release notes for details.
  </para>
 </sect1>

 <sect1 id="upgrading-and-pg-upgrade" xreflabel="pg_upgrade and repmgr">
  <indexterm>
   <primary>upgrading</primary>
   <secondary>pg_upgrade</secondary>
  </indexterm>
  <indexterm>
    <primary>pg_upgrade</primary>
  </indexterm>
  <title>pg_upgrade and repmgr</title>

  <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/static/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>
 </sect1>


 <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>
    <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
          <application>repmgrd</application> 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 <application>repmgrd</application> 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 <application>repmgrd</application> 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>
