1<refentry id="repmgr-cluster-show">
2  <indexterm>
3    <primary>repmgr cluster show</primary>
4  </indexterm>
5
6  <refmeta>
7    <refentrytitle>repmgr cluster show</refentrytitle>
8  </refmeta>
9
10  <refnamediv>
11    <refname>repmgr cluster show</refname>
12    <refpurpose>display information about each registered node in the replication cluster</refpurpose>
13  </refnamediv>
14
15
16  <refsect1>
17    <title>Description</title>
18    <para>
19      Displays information about each registered node in the replication cluster. This
20      command polls each registered server and shows its role (<literal>primary</literal> /
21      <literal>standby</literal>) and status. It polls each server
22      directly and can be run on any node in the cluster; this is also useful when analyzing
23      connectivity from a particular node.
24    </para>
25	<para>
26	  For PostgreSQL 9.6 and later, the output will also contain the node's current timeline ID.
27	</para>
28    <para>
29      Node availability is tested by connecting from the node where
30      <command>repmgr cluster show</command> is executed, and does not necessarily imply the node
31      is down. See <xref linkend="repmgr-cluster-matrix"/> and <xref linkend="repmgr-cluster-crosscheck"/> to get
32      better overviews of connections between nodes.
33    </para>
34
35  </refsect1>
36
37  <refsect1>
38    <title>Execution</title>
39    <para>
40      This command requires either a valid <filename>repmgr.conf</filename> file or a database
41      connection string to one of the registered nodes; no additional arguments are needed.
42    </para>
43
44    <para>
45      To show database connection errors when polling nodes, run the command in
46      <literal>--verbose</literal> mode.
47    </para>
48
49  </refsect1>
50
51  <refsect1>
52    <title>Example</title>
53    <para>
54    <programlisting>
55    $ repmgr -f /etc/repmgr.conf cluster show
56     ID | Name  | Role    | Status    | Upstream | Location | Priority | Timeline | Connection string
57    ----+-------+---------+-----------+----------+----------+----------+----------+-----------------------------------------
58     1  | node1 | primary | * running |          | default  | 100      | 1        | host=db_node1 dbname=repmgr user=repmgr
59     2  | node2 | standby |   running | node1    | default  | 100      | 1        | host=db_node2 dbname=repmgr user=repmgr
60     3  | node3 | standby |   running | node1    | default  | 100      | 1        | host=db_node3 dbname=repmgr user=repmgr
61     4  | node4 | standby |   running | node1    | default  | 100      | 1        | host=db_node4 dbname=repmgr user=repmgr
62     5  | node5 | witness | * running | node1    | default  | 0        | n/a      | host=db_node5 dbname=repmgr user=repmgr</programlisting>
63  </para>
64  </refsect1>
65  <refsect1>
66    <title>Notes</title>
67    <para>
68      The column <literal>Role</literal> shows the expected server role according to the
69      &repmgr; metadata.
70	</para>
71	<para>
72	  <literal>Status</literal> shows whether the server is running or unreachable.
73      If the node has an unexpected role not reflected in the &repmgr; metadata, e.g. a node was manually
74      promoted to primary, this will be highlighted with an exclamation mark.
75	  If a connection to the node cannot be made, this will be highlighted with a question mark.
76	  Note that the node will only be shown as <literal>? unreachable</literal>
77	  if a connection is not possible at network level; if the PostgreSQL instance on the
78	  node is pingable but not accepting connections, it will be shown as <literal>? running</literal>.
79	</para>
80	<para>
81	  In the following example, executed on <literal>node3</literal>, <literal>node1</literal> is not reachable
82	  at network level and assumed to be down; <literal>node2</literal> has been promoted to primary
83	  (but <literal>node3</literal> is not attached to it, and its metadata has not yet been updated);
84	  <literal>node4</literal> is running but rejecting connections (from <literal>node3</literal> at least).
85      <programlisting>
86     ID | Name  | Role    | Status               | Upstream | Location | Priority | Timeline | Connection string
87    ----+-------+---------+----------------------+----------+----------+----------+----------+----------------------------------------------------
88     1  | node1 | primary | ? unreachable        |          | default  | 100      |          | host=db_node1 dbname=repmgr user=repmgr
89     2  | node2 | standby | ! running as primary | ? node1  | default  | 100      | 2        | host=db_node2 dbname=repmgr user=repmgr
90     3  | node3 | standby |   running            | ? node1  | default  | 100      | 1        | host=db_node3 dbname=repmgr user=repmgr
91     4  | node4 | standby | ? running            | ? node1  | default  | 100      |          | host=db_node4 dbname=repmgr user=repmgr
92
93    WARNING: following issues were detected
94      - unable to connect to node "node1" (ID: 1)
95      - node "node1" (ID: 1) is registered as an active primary but is unreachable
96      - node "node2" (ID: 2) is registered as standby but running as primary
97      - unable to connect to node "node2" (ID: 2)'s upstream node "node1" (ID: 1)
98      - unable to determine if node "node2" (ID: 2) is attached to its upstream node "node1" (ID: 1)
99      - unable to connect to node "node3" (ID: 3)'s upstream node "node1" (ID: 1)
100      - unable to determine if node "node3" (ID: 3) is attached to its upstream node "node1" (ID: 1)
101      - unable to connect to node "node4" (ID: 4)
102    HINT: execute with --verbose option to see connection error messages</programlisting>
103    </para>
104	<para>
105	  To diagnose connection issues, execute <command>repmgr cluster show</command>
106	  with the <option>--verbose</option> option; this will display the error message
107	  for each failed connection attempt.
108	</para>
109	<tip>
110	  <para>
111		Use <xref linkend="repmgr-cluster-matrix"/> and <xref linkend="repmgr-cluster-crosscheck"/>
112		to diagnose connection issues across the whole replication cluster.
113	  </para>
114	</tip>
115  </refsect1>
116
117  <refsect1>
118    <title>Options</title>
119
120    <variablelist>
121
122      <varlistentry>
123        <term><option>--csv</option></term>
124        <listitem>
125	  <para>
126	    <command>repmgr cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
127	    outputs the replication cluster's status in a simple CSV format, suitable for
128	    parsing by scripts, e.g.:
129	    <programlisting>
130    $ repmgr -f /etc/repmgr.conf cluster show --csv
131    1,-1,-1
132    2,0,0
133    3,0,1</programlisting>
134	  </para>
135	  <para>
136	    The columns have following meanings:
137	    <itemizedlist spacing="compact" mark="bullet">
138	      <listitem>
139		<simpara>
140		  node ID
141		</simpara>
142	      </listitem>
143	      <listitem>
144		<simpara>
145            availability (0 = available, -1 = unavailable)
146		</simpara>
147	      </listitem>
148	      <listitem>
149		<simpara>
150            recovery state (0 = not in recovery, 1 = in recovery, -1 = unknown)
151		</simpara>
152	      </listitem>
153	    </itemizedlist>
154	  </para>
155	</listitem>
156      </varlistentry>
157
158      <varlistentry>
159        <term><option>--compact</option></term>
160        <listitem>
161          <para>
162			Suppress display of the <literal>conninfo</literal> column.
163          </para>
164        </listitem>
165      </varlistentry>
166
167      <varlistentry>
168        <term><option>--terse</option></term>
169        <listitem>
170          <para>
171			Suppress warnings about connection issues.
172          </para>
173        </listitem>
174      </varlistentry>
175
176      <varlistentry>
177        <term><option>--verbose</option></term>
178        <listitem>
179          <para>
180			Display the full text of any database connection error messages
181          </para>
182        </listitem>
183      </varlistentry>
184
185	</variablelist>
186
187  </refsect1>
188
189
190  <refsect1>
191    <title>Exit codes</title>
192    <para>
193      One of the following exit codes will be emitted by <command>repmgr cluster show</command>:
194    </para>
195    <variablelist>
196
197      <varlistentry>
198        <term><option>SUCCESS (0)</option></term>
199        <listitem>
200          <para>
201            No issues were detected.
202          </para>
203        </listitem>
204      </varlistentry>
205
206      <varlistentry>
207        <term><option>ERR_BAD_CONFIG (1)</option></term>
208        <listitem>
209          <para>
210            An issue was encountered while attempting to retrieve
211            &repmgr; metadata.
212          </para>
213        </listitem>
214      </varlistentry>
215
216      <varlistentry>
217        <term><option>ERR_DB_CONN (6)</option></term>
218        <listitem>
219          <para>
220            &repmgr; was unable to connect to the local PostgreSQL instance.
221          </para>
222        </listitem>
223      </varlistentry>
224
225      <varlistentry>
226        <term><option>ERR_NODE_STATUS (25)</option></term>
227        <listitem>
228          <para>
229            One or more issues were detected with the replication configuration,
230            e.g. a node was not in its expected state.
231          </para>
232        </listitem>
233      </varlistentry>
234
235   </variablelist>
236  </refsect1>
237
238  <refsect1>
239    <title>See also</title>
240    <para>
241     <xref linkend="repmgr-node-status"/>, <xref linkend="repmgr-node-check"/>, <xref linkend="repmgr-service-status"/>
242    </para>
243  </refsect1>
244
245</refentry>
246