Promotion, timelines, and what a timeline switch means

Promotion is the moment a standby stops replaying someone else’s history and starts writing its own.

Doing it

Three ways, all equivalent in effect:

SELECT pg_promote(wait => true, wait_seconds => 60);

pg_ctl promote -D $PGDATA
touch $PGDATA/promote.signal        # what pg_ctl promote does

pg_promote() with wait => true is the one to prefer in a script, because it returns only once the promotion has completed and tells you whether it did.

$ SELECT pg_promote(wait => true, wait_seconds => 60); SELECT pg_is_in_recovery();

 pg_promote
------------
t

pg_is_in_recovery
-------------------
f

$ tail /tmp/sb.log

22:53:36.888 UTC [210] LOG:  received promote request
22:53:36.889 UTC [210] LOG:  redo done at 0/43CCB2A8 system usage: CPU: user: 0.35 s, system: 0.16 s, elapsed: 2330.84 s
22:53:36.894 UTC [210] LOG:  selected new timeline ID: 2
22:53:36.977 UTC [204] LOG:  database system is ready to accept connections

89 milliseconds from received promote request to ready to accept connections. The 2,330 seconds in the redo done line is the lifetime of the startup process, not the promotion time — a number that is easy to misread as a duration.

That speed is the whole point of a hot standby: it has already replayed everything, so promotion is a decision rather than a build.

The timeline

$ cat $PGDATA/pg_wal/00000002.history

1	0/43CCB2E0	no recovery target specified

Three fields: diverged from timeline 1, at LSN 0/43CCB2E0, and why.

Compare with the history file from the point-in-time recovery in lesson XIII-06:

1	0/4034B48	before 2026-08-27 21:22:51.345091+00

The third field is the distinguishing one. no recovery target specified means a promotion — the standby was replaying and was told to stop and take over. A reason naming a target means a PITR.

Reading that field is how you tell, months later, what a timeline in your archive actually was.

Verifying a promotion

In order, and all four:

-- 1. it is no longer in recovery
SELECT pg_is_in_recovery();                       -- expect f

-- 2. it is on a new timeline (from the log, or the history file)
--    LOG:  selected new timeline ID: 2

-- 3. it accepts writes
CREATE TABLE promotion_check(t timestamptz default now());
INSERT INTO promotion_check DEFAULT VALUES;

-- 4. the data you expected is there
SELECT count(*) FROM your_busiest_table;

Step 4 is the one that matters and the one that gets skipped. A promotion always succeeds mechanically. Whether it succeeded usefully depends on how caught up the standby was, and that is a question about pg_last_wal_replay_lsn() before the promotion, not about the promotion itself.

What to take from this

• pg_promote(wait => true) is the scriptable form; it reports success.
• Measured: 89 ms from promote request to accepting connections.
• pg_controldata reports the last checkpoint’s timeline. Right after a promotion it still says the old one. Use pg_is_in_recovery().
• The history file’s third field distinguishes a promotion (no recovery target specified) from a PITR.
• Other standbys need repointing and access to the new history file.
• Promotion is irreversible. Fence first, then promote.

Cross-course references

• Linux for Production Sysadmins — Part LIII (Quorum and split brain) covers why a promotion decision needs more than one node’s opinion of the network.
• Observability for Production Sysadmins — Part CIX (Incident investigation workflows) covers recording the promotion time and the timeline it produced, which is what makes the next rejoin possible.

Quiz