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.
    </para>
  </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>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-F</option></term>
        <term><option>--force</option></term>
        <listitem>
          <para>
            Ignore warnings and continue anyway.
          </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>
  </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 standby.
    </para>
  </refsect1>


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

</refentry>