repmgr cluster show

repmgr cluster show

display information about each registered node in the replication cluster

## Description

Displays information about each registered node in the replication cluster. This command polls each registered server and shows its role (`primary` / `standby`) and status. It polls each server directly and can be run on any node in the cluster; this is also useful when analyzing connectivity from a particular node.

For PostgreSQL 9.6 and later, the output will also contain the node's current timeline ID.

Node availability is tested by connecting from the node where `repmgr cluster show` is executed, and does not necessarily imply the node is down. See repmgr-cluster-matrix and repmgr-cluster-crosscheck to get better overviews of connections between nodes.

## Execution

This command requires either a valid `repmgr.conf` file or a database connection string to one of the registered nodes; no additional arguments are needed.

To show database connection errors when polling nodes, run the command in `--verbose` mode.

## Example

        $ repmgr -f /etc/repmgr.conf cluster show
         ID | Name  | Role    | Status    | Upstream | Location | Priority | Timeline | Connection string
        ----+-------+---------+-----------+----------+----------+----------+----------+-----------------------------------------
         1  | node1 | primary | * running |          | default  | 100      | 1        | host=db_node1 dbname=repmgr user=repmgr
         2  | node2 | standby |   running | node1    | default  | 100      | 1        | host=db_node2 dbname=repmgr user=repmgr
         3  | node3 | standby |   running | node1    | default  | 100      | 1        | host=db_node3 dbname=repmgr user=repmgr
         4  | node4 | standby |   running | node1    | default  | 100      | 1        | host=db_node4 dbname=repmgr user=repmgr
         5  | node5 | witness | * running | node1    | default  | 0        | n/a      | host=db_node5 dbname=repmgr user=repmgr

## Notes

The column `Role` shows the expected server role according to the &repmgr; metadata.

`Status` shows whether the server is running or unreachable. If the node has an unexpected role not reflected in the &repmgr; metadata, e.g. a node was manually promoted to primary, this will be highlighted with an exclamation mark. If a connection to the node cannot be made, this will be highlighted with a question mark. Note that the node will only be shown as `? unreachable` if a connection is not possible at network level; if the PostgreSQL instance on the node is pingable but not accepting connections, it will be shown as `? running`.

In the following example, executed on `node3`, `node1` is not reachable at network level and assumed to be down; `node2` has been promoted to primary (but `node3` is not attached to it, and its metadata has not yet been updated); `node4` is running but rejecting connections (from `node3` at least).

         ID | Name  | Role    | Status               | Upstream | Location | Priority | Timeline | Connection string
        ----+-------+---------+----------------------+----------+----------+----------+----------+----------------------------------------------------
         1  | node1 | primary | ? unreachable        |          | default  | 100      |          | host=db_node1 dbname=repmgr user=repmgr
         2  | node2 | standby | ! running as primary | ? node1  | default  | 100      | 2        | host=db_node2 dbname=repmgr user=repmgr
         3  | node3 | standby |   running            | ? node1  | default  | 100      | 1        | host=db_node3 dbname=repmgr user=repmgr
         4  | node4 | standby | ? running            | ? node1  | default  | 100      |          | host=db_node4 dbname=repmgr user=repmgr

        WARNING: following issues were detected
          - unable to connect to node "node1" (ID: 1)
          - node "node1" (ID: 1) is registered as an active primary but is unreachable
          - node "node2" (ID: 2) is registered as standby but running as primary
          - unable to connect to node "node2" (ID: 2)'s upstream node "node1" (ID: 1)
          - unable to determine if node "node2" (ID: 2) is attached to its upstream node "node1" (ID: 1)
          - unable to connect to node "node3" (ID: 3)'s upstream node "node1" (ID: 1)
          - unable to determine if node "node3" (ID: 3) is attached to its upstream node "node1" (ID: 1)
          - unable to connect to node "node4" (ID: 4)
        HINT: execute with --verbose option to see connection error messages

To diagnose connection issues, execute `repmgr cluster show` with the `--verbose` option; this will display the error message for each failed connection attempt.

Use repmgr-cluster-matrix and repmgr-cluster-crosscheck to diagnose connection issues across the whole replication cluster.

## Options

`--csv`

- `repmgr cluster show` accepts an optional parameter `--csv`, which outputs the replication cluster's status in a simple CSV format, suitable for parsing by scripts, e.g.:

          $ repmgr -f /etc/repmgr.conf cluster show --csv
          1,-1,-1
          2,0,0
          3,0,1

  The columns have following meanings:

  - node ID

  - availability (0 = available, -1 = unavailable)

  - recovery state (0 = not in recovery, 1 = in recovery, -1 = unknown)

`--compact`

- Suppress display of the `conninfo` column.

`--terse`

- Suppress warnings about connection issues.

`--verbose`

- Display the full text of any database connection error messages

## Exit codes

One of the following exit codes will be emitted by `repmgr cluster show`:

`SUCCESS (0)`

- No issues were detected.

`ERR_BAD_CONFIG (1)`

- An issue was encountered while attempting to retrieve &repmgr; metadata.

`ERR_DB_CONN (6)`

- &repmgr; was unable to connect to the local PostgreSQL instance.

`ERR_NODE_STATUS (25)`

- One or more issues were detected with the replication configuration, e.g. a node was not in its expected state.

## See also

repmgr-node-status, repmgr-node-check, repmgr-service-status