repmgr standby promote

repmgr standby promote

promote a standby to a primary

## Description

Promotes a standby to a primary if the current primary has failed. This command requires a valid `repmgr.conf` file for the standby, either specified explicitly with `-f/--config-file` or located in a default location; no additional arguments are required.

If &repmgrd; is active, you must execute `repmgr service pause` (&repmgr; 4.2 - 4.4: `repmgr service pause`) to temporarily disable &repmgrd; while making any changes to the replication cluster.

If the standby promotion succeeds, the server will not need to be restarted. However any other standbys will need to follow the new primary, and will need to be restarted to do this.

Beginning with repmgr 4.4, the option `--siblings-follow` can be used to have all other standbys (and a witness server, if in use) follow the new primary.

If using &repmgrd;, when invoking `repmgr standby promote` (either directly via the `promote_command`, or in a script called via `promote_command`), `--siblings-follow` must not be included as a command line option for `repmgr standby promote`.

In repmgr 4.3 and earlier, `repmgr standby follow` must be executed on each standby individually.

&repmgr; will wait for up to `promote_check_timeout` seconds (default: `60`) to verify that the standby has been promoted, and will check the promotion every `promote_check_interval` seconds (default: 1 second). Both values can be defined in `repmgr.conf`.

In PostgreSQL 12 and earlier, if WAL replay is paused on the standby, and not all WAL files on the standby have been replayed, &repmgr; will not attempt to promote it.

This is because if WAL replay is paused, PostgreSQL itself will not react to a promote command until WAL replay is resumed and all pending WAL has been replayed. This means attempting to promote PostgreSQL in this state will leave PostgreSQL in a condition where the promotion may occur at a unpredictable point in the future.

Note that if the standby is in archive recovery, &repmgr; will not be able to determine if more WAL is pending replay, and will abort the promotion attempt if WAL replay is paused.

This restriction does not apply to PostgreSQL 13 and later.

## Example

          $ repmgr -f /etc/repmgr.conf standby promote
          NOTICE: promoting standby to primary
          DETAIL: promoting server "node2" (ID: 2) using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' promote"
          server promoting
          NOTICE: STANDBY PROMOTE successful
          DETAIL: server "node2" (ID: 2) was successfully promoted to primary

## User permission requirements

pg_promote() (PostgreSQL 12 and later)

From PostgreSQL 12, &repmgr; will attempt to use the built-in `pg_promote()` function to promote a standby to primary.

By default, execution of `pg_promote()` is restricted to superusers. If the `repmgr` user does not have permission to execute `pg_promote()`, &repmgr; will fall back to using "`pg_ctl promote`".

Execute `repmgr standby promote` with the `--dry-run` to check whether the &repmgr; user has permission to execute `pg_promote()`.

If the `repmgr` user is not a superuser, execution permission for this function can be granted with e.g.:

        GRANT EXECUTE ON FUNCTION pg_catalog.pg_promote TO repmgr

Note that permissions are only effective for the database they are granted in, so this must be executed in the &repmgr; database to be effective.

For more details on `pg_promote()`, see the PostgreSQL documentation.

## Options

`--dry-run`

- Check if this node can be promoted, but don't carry out the promotion.

`--siblings-follow`

- Have all sibling nodes (nodes formerly attached to the same upstream node as the promotion candidate) follow this node after it has been promoted.

  Note that a witness server, if in use, is also counted as a "sibling node" as it needs to be instructed to synchronise its metadata with the new primary.

  Do not provide this option when configuring &repmgrd;'s `promote_command`.

`-F`

`--force`

- Ignore warnings and continue anyway.

  This option is relevant in the following situations if `--siblings-follow` was specified:

  - If one or more sibling nodes was not reachable via SSH, the standby will be promoted anyway.

  - If the promotion candidate has insufficient free walsenders to accommodate the standbys which will be attached to it, the standby will be promoted anyway.

  - If replication slots are in use but the promotion candidate has insufficient free replication slots to accommodate the standbys which will be attached to it, the standby will be promoted anyway.

  Note that if the `-F`/`--force` option is used when any of the above situations is encountered, the onus is on the user to manually resolve any resulting issues.

## Configuration file settings

The following parameters in `repmgr.conf` are relevant to the promote operation:

- `promote_check_interval`: interval (in seconds, default: 1 second) to wait between each check to determine whether the standby has been promoted.

- `promote_check_timeout`: time (in seconds, default: 60 seconds) to wait to verify that the standby has been promoted before exiting with `ERR_PROMOTION_FAIL`.

- `service_promote_command`: a command which will be executed instead of `pg_ctl promote` or (in PostgreSQL 12 and later) `pg_promote()`.

  This is intended for systems which provide a package-level promote command, such as Debian's pg_ctlcluster, to promote the PostgreSQL from standby to primary.

## Exit codes

Following exit codes can be emitted by `repmgr standby promote`:

`SUCCESS (0)`

- The standby was successfully promoted to primary.

`ERR_DB_CONN (6)`

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

  PostgreSQL must be running before the node can be promoted.

`ERR_PROMOTION_FAIL (8)`

- The node could not be promoted to primary for one of the following reasons:

  - there is an existing primary node in the replication cluster

  - the node is not a standby

  - WAL replay is paused on the node

  - execution of the PostgreSQL promote command failed

## Event notifications

A `standby_promote` event notification will be generated.