1<chapter id="promoting-standby" xreflabel="Promoting a standby">
2 <title>Promoting a standby server with repmgr</title>
3 <indexterm>
4   <primary>promoting a standby</primary>
5   <seealso>repmgr standby promote</seealso>
6 </indexterm>
7 <para>
8   If a primary server fails or needs to be removed from the replication cluster,
9   a new primary server must be designated, to ensure the cluster continues
10   to function correctly. This can be done with <xref linkend="repmgr-standby-promote"/>,
11   which promotes the standby on the current server to primary.
12 </para>
13
14 <para>
15  To demonstrate this, set up a replication cluster with a primary and two attached
16  standby servers so that the cluster looks like this:
17  <programlisting>
18     $ repmgr -f /etc/repmgr.conf cluster show
19     ID | Name  | Role    | Status    | Upstream | Location | Connection string
20    ----+-------+---------+-----------+----------+----------+--------------------------------------
21     1  | node1 | primary | * running |          | default  | host=node1 dbname=repmgr user=repmgr
22     2  | node2 | standby |   running | node1    | default  | host=node2 dbname=repmgr user=repmgr
23     3  | node3 | standby |   running | node1    | default  | host=node3 dbname=repmgr user=repmgr</programlisting>
24 </para>
25 <para>
26  Stop the current primary with e.g.:
27  <programlisting>
28   $ pg_ctl -D /var/lib/postgresql/data -m fast stop</programlisting>
29 </para>
30 <para>
31  At this point the replication cluster will be in a partially disabled state, with
32  both standbys accepting read-only connections while attempting to connect to the
33  stopped primary. Note that the &repmgr; metadata table will not yet have been updated;
34  executing <xref linkend="repmgr-cluster-show"/> will note the discrepancy:
35  <programlisting>
36    $ repmgr -f /etc/repmgr.conf cluster show
37     ID | Name  | Role    | Status        | Upstream | Location | Connection string
38    ----+-------+---------+---------------+----------+----------+--------------------------------------
39     1  | node1 | primary | ? unreachable |          | default  | host=node1 dbname=repmgr user=repmgr
40     2  | node2 | standby |   running     | node1    | default  | host=node2 dbname=repmgr user=repmgr
41     3  | node3 | standby |   running     | node1    | default  | host=node3 dbname=repmgr user=repmgr
42
43    WARNING: following issues were detected
44    node "node1" (ID: 1) is registered as an active primary but is unreachable</programlisting>
45 </para>
46 <para>
47  Now promote the first standby with:
48  <programlisting>
49   $ repmgr -f /etc/repmgr.conf standby promote</programlisting>
50 </para>
51 <para>
52  This will produce output similar to the following:
53  <programlisting>
54    INFO: connecting to standby database
55    NOTICE: promoting standby
56    DETAIL: promoting server using "pg_ctl -l /var/log/postgresql/startup.log -w -D '/var/lib/postgresql/data' promote"
57    server promoting
58    INFO: reconnecting to promoted server
59    NOTICE: STANDBY PROMOTE successful
60    DETAIL: node 2 was successfully promoted to primary</programlisting>
61 </para>
62 <para>
63  Executing <xref linkend="repmgr-cluster-show"/> will show the current state; as there is now an
64  active primary, the previous warning will not be displayed:
65  <programlisting>
66    $ repmgr -f /etc/repmgr.conf cluster show
67     ID | Name  | Role    | Status    | Upstream | Location | Connection string
68    ----+-------+---------+-----------+----------+----------+--------------------------------------
69     1  | node1 | primary | - failed  |          | default  | host=node1 dbname=repmgr user=repmgr
70     2  | node2 | primary | * running |          | default  | host=node2 dbname=repmgr user=repmgr
71     3  | node3 | standby |   running | node1    | default  | host=node3 dbname=repmgr user=repmgr</programlisting>
72 </para>
73 <para>
74  However the sole remaining standby (<literal>node3</literal>) is still trying to replicate from the failed
75  primary; <xref linkend="repmgr-standby-follow"/> must now be executed to rectify this situation
76  (see <xref linkend="follow-new-primary"/> for example).
77 </para>
78</chapter>
79
80