repmgr node rejoin

repmgr node rejoin

rejoin a dormant (stopped) node to the replication cluster

## Description

Enables a dormant (stopped) node to be rejoined to the replication cluster.

This can optionally use pg_rewind to re-integrate a node which has diverged from the rest of the cluster, typically a failed primary.

If the node is running and needs to be attached to the current primary, use repmgr-standby-follow.

Note repmgr-standby-follow can only be used for standbys which have not diverged from the rest of the cluster.

## Usage

          repmgr node rejoin -d '$conninfo'

where `$conninfo` is the conninfo string of any reachable node in the cluster. `repmgr.conf` for the stopped node *must* be supplied explicitly if not otherwise available.

## Options

`--dry-run`

- Check prerequisites but don't actually execute the rejoin.

`--force-rewind[=/path/to/pg_rewind]`

- Execute pg_rewind.

  It is only necessary to provide the pg_rewind path if using PostgreSQL 9.3 or 9.4, and pg_rewind is not installed in the PostgreSQL `bin` directory.

`--config-files`

- comma-separated list of configuration files to retain after executing pg_rewind.

  Currently pg_rewind will overwrite the local node's configuration files with the files from the source node, so it's advisable to use this option to ensure they are kept.

`--config-archive-dir`

- Directory to temporarily store configuration files specified with `--config-files`; default: `/tmp`.

`-W/--no-wait`

- Don't wait for the node to rejoin cluster.

  If this option is supplied, &repmgr; will restart the node but not wait for it to connect to the primary.

## Configuration file settings

- `node_rejoin_timeout`: the maximum length of time (in seconds) to wait for the node to reconnect to the replication cluster (defaults to the value set in `standby_reconnect_timeout`, 60 seconds).

## Event notifications

A `node_rejoin` event notification will be generated.

## Notes

Currently `repmgr node rejoin` can only be used to attach a standby to the current primary, not another standby.

The node must have been shut down cleanly; if this was not the case, it will need to be manually started (remove any existing `recovery.conf` file first) until it has reached a consistent recovery point, then shut down cleanly.

If PostgreSQL is started in single-user mode and input is directed from `/dev/null/`, it will perform recovery then immediately quit, and will then be in a state suitable for use by pg_rewind.

              rm -f /var/lib/pgsql/data/recovery.conf
              postgres --single -D /var/lib/pgsql/data/ < /dev/null

## Using `pg_rewind`

`repmgr node rejoin` can optionally use `pg_rewind` to re-integrate a node which has diverged from the rest of the cluster, typically a failed primary. `pg_rewind` is available in PostgreSQL 9.5 and later as part of the core distribution, and can be installed from external sources for PostgreSQL 9.3 and 9.4.

`pg_rewind` requires that either `wal_log_hints` is enabled, or that data checksums were enabled when the cluster was initialized. See the `pg_rewind` documentation for details.

To have `repmgr node rejoin` use `pg_rewind`, pass the command line option `--force-rewind`, which will tell &repmgr; to execute `pg_rewind` to ensure the node can be rejoined successfully.

Be aware that if `pg_rewind` is executed and actually performs a rewind operation, any configuration files in the PostgreSQL data directory will be overwritten with those from the source server.

To prevent this happening, provide a comma-separated list of files to retain using the `--config-file` command line option; the specified files will be archived in a temporary directory (whose parent directory can be specified with `--config-archive-dir`) and restored once the rewind operation is complete.

Example, first using `--dry-run`, then actually executing the `node rejoin command`.

        $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node1 dbname=repmgr user=repmgr' \
             --force-rewind --config-files=postgresql.local.conf,postgresql.conf --verbose --dry-run
        NOTICE: using provided configuration file "/etc/repmgr.conf"
        INFO: prerequisites for using pg_rewind are met
        INFO: file "postgresql.local.conf" would be copied to "/tmp/repmgr-config-archive-node1/postgresql.local.conf"
        INFO: file "postgresql.conf" would be copied to "/tmp/repmgr-config-archive-node1/postgresql.local.conf"
        INFO: 2 files would have been copied to "/tmp/repmgr-config-archive-node1"
        INFO: directory "/tmp/repmgr-config-archive-node1" deleted
        INFO: pg_rewind would now be executed
        DETAIL: pg_rewind command is:
          pg_rewind -D '/var/lib/postgresql/data' --source-server='host=node1 dbname=repmgr user=repmgr'

If `--force-rewind` is used with the `--dry-run` option, this checks the prerequisites for using pg_rewind, but cannot predict the outcome of actually executing pg_rewind.

        $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node1 dbname=repmgr user=repmgr' \
             --force-rewind --config-files=postgresql.local.conf,postgresql.conf --verbose
        NOTICE: using provided configuration file "/etc/repmgr.conf"
        INFO: prerequisites for using pg_rewind are met
        INFO: 2 files copied to "/tmp/repmgr-config-archive-node1"
        NOTICE: executing pg_rewind
        NOTICE: 2 files copied to /var/lib/pgsql/data
        INFO: directory "/tmp/repmgr-config-archive-node1" deleted
        INFO: deleting "recovery.done"
        INFO: setting node 1's primary to node 2
        NOTICE: starting server using "pg_ctl-l /var/log/postgres/startup.log -w -D '/var/lib/pgsql/data' start"
        waiting for server to start.... done
        server started
        NOTICE: NODE REJOIN successful
        DETAIL: node 1 is now attached to node 2

## See also

repmgr-standby-follow