repmgr/doc/repmgr-standby-follow.sgml

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

  <refmeta>
    <refentrytitle>repmgr standby follow</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>repmgr standby follow</refname>
    <refpurpose>attach a running standby to a new upstream node</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>

    <para>
      Attaches the standby to a new upstream node. This command requires a valid
      <filename>repmgr.conf</filename> file for the standby, either specified
      explicitly with <literal>-f/--config-file</literal> or located in a
      default location; no additional arguments are required.
    </para>

	<para>
	  By default &repmgr; will attempt to attach the standby to the current primary.
	  If <option>--upstream-node-id</option> is provided, &repmgr; will attempt
	  to attach the standby to the specified node, which can be another standby.
	</para>

    <para>
      This command will force a restart of the standby server, which must be
      running.
    </para>

	<tip>
      <para>
		To re-add an inactive node to the replication cluster, use
		<xref linkend="repmgr-node-rejoin">.
      </para>
	</tip>

	<para>
	  <command>repmgr standby follow</command> will wait up to
	  <varname>standby_follow_timeout</varname> seconds (default: <literal>30</literal>)
	  to verify the standby has actually connected to the new upstream node.
	</para>

	<note>
	  <para>
		If <option>recovery_min_apply_delay</option> is set for the standby, it
		will not attach to the new upstream node until it has replayed available
		WAL.
	  </para>
	  <para>
		Conversely, if the standby is attached follows another standby
		with <option>recovery_min_apply_delay</option> set, that standby's replay
		state may actually be behind that of its new downstream node.
	  </para>
	</note>

  </refsect1>

  <refsect1>
    <title>Example</title>
    <para>
      <programlisting>
      $ repmgr -f /etc/repmgr.conf standby follow
      INFO: setting node 3's primary to node 2
      NOTICE: restarting server using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' restart"
      waiting for server to shut down........ done
      server stopped
      waiting for server to start.... done
      server started
      NOTICE: STANDBY FOLLOW successful
      DETAIL: node 3 is now attached to node 2</programlisting>
    </para>
  </refsect1>

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

      <varlistentry>
        <term><option>--dry-run</option></term>
        <listitem>
          <para>
            Check prerequisites but don't actually follow a new standby.
          </para>
          <important>
            <para>
              This does not guarantee the standby can follow the primary; in
              particular, whether the primary and standby timelines have diverged,
              can currently only be determined by actually attempting to
              attach the standby to the primary.
            </para>
          </important>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--upstream-node-id</option></term>
        <listitem>
          <para>
            Node ID of the new primary.
          </para>
          <para>
            This option is intended for use by <application>repmgrd</application>, when
			instructing standbys to follow the new primary. For more details
			see <link linkend="repmgrd-automatic-failover-configuration">Automatic failover configuration</link>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-w</option></term>
        <term><option>--wait</option></term>
        <listitem>
          <para>
            Wait for a primary to appear. &repmgr; will wait for up to
            <varname>primary_follow_timeout</varname> seconds
            (default: 60 seconds) to verify that the standby is following the new primary.
            This value can be defined in <filename>repmgr.conf</filename>.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

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

      <varlistentry>
        <term><option>SUCCESS (0)</option></term>
        <listitem>
          <para>
            No issues were detected.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ERR_DB_CONN (6)</option></term>
        <listitem>
          <para>
            &repmgr; was unable to establish a database connection to one of the nodes.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ERR_FOLLOW_FAIL (23)</option></term>
        <listitem>
          <para>
            &repmgr; was unable to complete the follow command.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="repmgr-standby-follow-events">
    <title>Event notifications</title>
    <para>
      A <literal>standby_follow</literal> <link linkend="event-notifications">event notification</link> will be generated.
    </para>
    <para>
      If provided, &repmgr; will substitute the placeholders <literal>%p</literal> with the node ID of the primary
      being followed, <literal>%c</literal> with its <literal>conninfo</literal> string, and
      <literal>%a</literal> with its node name.
    </para>
  </refsect1>

  <refsect1>
    <title>See also</title>
    <para>
     <xref linkend="repmgr-node-rejoin">
    </para>
  </refsect1>
</refentry>