repmgr/doc/repmgr-standby-switchover.sgml

<refentry id="repmgr-standby-switchover">
  <indexterm>
    <primary>repmgr standby switchover</primary>
  </indexterm>

  <refmeta>
    <refentrytitle>repmgr standby switchover</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>repmgr standby switchover</refname>
    <refpurpose>promote a standby to primary and demote the existing primary to a standby</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>

    <para>
      Promotes a standby to primary and demotes the existing primary to a standby.
      This command must be run on the standby to be promoted, and requires a
      passwordless SSH connection to the current primary.
    </para>
    <para>
      If other standbys are connected to the demotion candidate, &repmgr; can instruct
      these to follow the new primary if the option <literal>--siblings-follow</literal>
      is specified. This requires a passwordless SSH connection between the promotion
      candidate (new primary) and the standbys attached to the demotion candidate
      (existing primary).
    </para>
    <note>
      <para>
        Performing a switchover is a non-trivial operation. In particular it
        relies on the current primary being able to shut down cleanly and quickly.
        &repmgr; will attempt to check for potential issues but cannot guarantee
        a successful switchover.
      </para>
    </note>
  </refsect1>

  <refsect1>
    <title>Options</title>
    <variablelist>

      <varlistentry>
        <term><option>--always-promote</option></term>
        <listitem>
          <para>
            Promote standby to primary, even if it is behind original primary
            (original primary will be shut down in any case).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--dry-run</option></term>
        <listitem>
          <para>
            Check prerequisites but don't actually execute a switchover.
          </para>
          <important>
            <para>
              Success of <option>--dry-run</option> does not imply the switchover will
              complete successfully, only that
              the prerequisites for performing the operation are met.
            </para>
          </important>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-F</option></term>
        <term><option>--force</option></term>
        <listitem>
          <para>
            Ignore warnings and continue anyway.
          </para>
          <para>
            Specifically, if a problem is encountered when shutting down the current primary,
            using <option>-F/--force</option> will cause &repmgr; to continue by promoting
            the standby to be the new primary, and if <option>--siblings-follow</option> is
            specified, attach any other standbys to the new primary.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--force-rewind</option></term>
        <listitem>
          <para>
            Use <application>pg_rewind</application> to reintegrate the old primary if necessary
            (PostgreSQL 9.5 and later).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-R</option></term>
        <term><option>--remote-user</option></term>
        <listitem>
          <para>
            System username for remote SSH operations (defaults to local system user).
          </para>
        </listitem>
      </varlistentry>

     <varlistentry>
        <term><option>--siblings-follow</option></term>
        <listitem>
          <para>
            Have standbys attached to the old primary follow the new primary.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Execution</title>

    <para>
      Execute with the <literal>--dry-run</literal> option to test the switchover as far as
      possible without actually changing the status of either node.
    </para>
    <para>
      <application>repmgrd</application> should not be active on any nodes while a switchover is being
      executed. This restriction may be lifted in a later version.
    </para>
    <para>
      External database connections, e.g. from an application, should not be permitted while
      the switchover is taking place. In particular, active transactions on the primary
      can potentially disrupt the shutdown process.
    </para>
  </refsect1>

  <refsect1>
    <title>Event notifications</title>
    <para>
      <literal>standby_switchover</literal> and <literal>standby_promote</literal>
      <link linkend="event-notifications">event notifications</link> will be generated for the new primary,
      and a <literal>node_rejoin</literal> event notification for the former primary (new standby).
    </para>
    <para>
      If using an event notification script, <literal>standby_switchover</literal>
      will populate the placeholder parameter <literal>%p</literal> with the node ID of
      the former primary.
    </para>
  </refsect1>

  <refsect1>
    <title>Exit codes</title>
    <para>
      Following exit codes can be emitted by <literal>repmgr standby switchover</literal>:
    </para>
    <variablelist>

      <varlistentry>
        <term><option>SUCCESS (0)</option></term>
        <listitem>
          <para>
            The switchover completed successfully.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ERR_SWITCHOVER_FAIL (18)</option></term>
        <listitem>
          <para>
            The switchover could not be executed.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ERR_SWITCHOVER_INCOMPLETE (22)</option></term>
        <listitem>
          <para>
            The switchover was executed but a problem was encountered.
            Typically this means the former primary could not be reattached
            as a standby.
          </para>
        </listitem>
      </varlistentry>

   </variablelist>
  </refsect1>

  <refsect1>
    <title>See also</title>
    <para>
      For more details see the section <xref linkend="performing-switchover">.
    </para>
  </refsect1>

</refentry>