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