Contents

promote_trigger_file

A system parameter specifying a file to trigger promotion of a standby
This entry relates to a PostgreSQL feature which is deprecated and may be desupported in future releases.

promote_trigger_file is a configuration parameter specifying the path of a file, which if present, will cause a standby to be promoted to primary.

promote_trigger_file was added in PostgreSQL 12, replacing the recovery.conf parameter trigger_file, and removed in PostgreSQL 16.

Default value

The default value for promote_trigger_file is: '' (empty string).

Usage

If promote_trigger_file is set, and a matching file is placed in the specified location, the standby will promote itself.

The file can be empty. It must be readable by the system user under which PostgreSQL runs, otherwise the PostgreSQL instance will refuse to start, or will terminate if running.

On a primary, promote_trigger_file will be ignored, even if the specified location is not accessible. The presence of a file will be have no effect.

In PostgreSQL 9.0, when streaming replication was introduced, promote_trigger_file was the only way to promote a running standby to primary. In general, pg_ctl promote (available from PostgreSQL 9.1) and the pg_promote() function (available from PostgreSQL 12) provide a more convenient method for achieving this.

Change history

Examples

If promote_trigger_file is set to "/tmp/standby.trg" and a corresponding file is found, the PostgreSQL log will contain entries like this:

[2022-11-27 09:47:41 UTC]    LOG:  00000: promote trigger file found: /tmp/standby.trg
[2022-11-27 09:47:41 UTC]    FATAL:  57P01: terminating walreceiver process due to administrator command
[2022-11-27 09:47:41 UTC]    LOG:  00000: invalid record length at 0/3000208: wanted 24, got 0
[2022-11-27 09:47:41 UTC]    LOG:  00000: redo done at 0/30001D0 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 83.20 s
[2022-11-27 09:47:41 UTC]    LOG:  00000: selected new timeline ID: 2
[2022-11-27 09:47:41 UTC]    LOG:  00000: archive recovery complete
[2022-11-27 09:47:41 UTC]    LOG:  00000: checkpoint starting: force
[2022-11-27 09:47:41 UTC]    LOG:  00000: database system is ready to accept connections

Attempting to set promote_trigger_file to a location not accessible to PostgreSQL:

[2022-11-27 09:51:18 UTC]    LOG:  00000: received SIGHUP, reloading configuration files
[2022-11-27 09:51:18 UTC]    LOG:  00000: parameter "promote_trigger_file" changed to "/root/standby.trg"
[2022-11-27 09:51:18 UTC]    FATAL:  42501: could not stat promote trigger file "/root/standby.trg": Permission denied
[2022-11-27 09:51:18 UTC]    LOG:  00000: startup process (PID 2210329) exited with exit code 1
[2022-11-27 09:51:18 UTC]    LOG:  00000: terminating any other active server processes
[2022-11-27 09:51:18 UTC]    LOG:  00000: shutting down due to startup process failure
[2022-11-27 09:51:18 UTC]    LOG:  00000: database system is shut down

Categories

Deprecated, GUC configuration item, Replication

See also

pg_ctl, pg_promote()