Physical Streaming Replication

[!WARNING] PG12 watershed recovery.conf removed in PG12. Server refuses to start if file exists. Standby identity now via standby.signal (presence file in $PGDATA) + standby GUCs in postgresql.conf. Configurations carried forward from PG≤11 fail at startup. Verbatim PG12 release-note: "recovery.conf is no longer used, and the server will not start if that file exists. recovery.signal and standby.signal files are now used to switch into non-primary mode. The trigger_file setting has been renamed to promote_trigger_file. The standby_mode setting has been removed."¹

[!WARNING] PG16 watershed promote_trigger_file GUC removed. Use pg_ctl promote or pg_promote() instead.²

Table of Contents

• When to Use This Reference
• Mental Model — Five Rules
• Decision Matrix
• Mechanics
  • Setup Topology
  • Standby Identity Files (PG12+)
  • primary_conninfo and primary_slot_name
  • wal_level Required Settings
  • hot_standby (Read Queries on Standby)
  • hot_standby_feedback (Block Primary Vacuum)
  • synchronous_commit Durability Dial
  • synchronous_standby_names (Quorum vs Priority)
  • max_standby_archive_delay / max_standby_streaming_delay
  • [Recovery Target GUCs](#recovery-target-guc s)
  • Cascading Replication
  • Promotion (pg_promote())
  • pg_stat_replication View
  • Per-Version Timeline
• Examples / Recipes
• Gotchas / Anti-patterns
• See Also
• Sources

When to Use This Reference

Pick this file for: setting up physical streaming replication primary+standby, choosing synchronous_commit level, picking synchronous_standby_names quorum vs priority mode, deciding hot_standby_feedback on/off, sizing max_standby_*_delay, planning controlled switchover, recovering from query-cancel cascades on standby, monitoring lag via pg_stat_replication.

NOT this file for: logical replication (→ 74-logical-replication.md), replication slot mechanics deep dive (→ 75-replication-slots.md), failover orchestration via Patroni/repmgr (→ 77-standby-failover.md, 78-ha-architectures.md, 79-patroni.md), pg_rewind for diverged former primaries (→ 89-pg-rewind.md), backup/PITR (→ 84-backup-physical-pitr.md).

Mental Model — Five Rules

1. Physical streaming = byte-for-byte WAL ship. Standby applies primary's WAL records. Same binary. Standby identical to primary at byte level. Cannot replicate selectively (no per-table, no row filter — that's logical replication).

2. Standby identity = standby.signal file + primary_conninfo GUC since PG12. Before PG12: recovery.conf. After PG12: empty standby.signal file in $PGDATA + postgresql.conf (or postgresql.auto.conf) with primary_conninfo='host=primary port=5432 user=replicator ...'. Server refuses startup if recovery.conf exists.¹

3. synchronous_commit is per-transaction durability dial. Five levels: off / local / remote_write / on (default) / remote_apply. Orthogonal to synchronous_standby_names — names list says which standbys count; level says how far WAL must travel before COMMIT returns.

4. synchronous_standby_names has three syntaxes. Simple list (priority, first N), FIRST N (s1,s2,s3) (priority — first N must ack), ANY N (s1,s2,s3) (quorum — any N must ack). Empty string = async.

5. hot_standby_feedback = on is bidirectional trade-off. Standby tells primary its xmin horizon. Primary delays vacuum to keep tuples visible to standby. Long-running standby query → primary table bloat. Off → standby query cancelled when primary vacuums tuples it still needs.

Decision Matrix

Three smell signals:

• pg_stat_replication.replay_lag always NULL → standby idle, nothing to compare. Send dummy WAL via heartbeat-insert on primary. Not a bug.
• pg_stat_replication.state = 'catchup' for hours → standby behind. Slot retention working but standby can't keep up. Check standby disk I/O, max_wal_senders, network.
• Standby queries silently cancelled with ERROR: canceling statement due to conflict with recovery → max_standby_*_delay too low for workload, hot_standby_feedback = off. Pick one mitigation.

Mechanics

Setup Topology

Physical streaming replication = one primary + N standbys. Standby connects to primary as replication user, walreceiver process consumes WAL, startup process applies. Primary may also archive WAL (decoupled from streaming). Standbys may cascade.

┌──────────────────┐
                   │   Primary (rw)   │
                   │                  │
                   │ walsender ──────►│ standby1 (read-only)
                   │ walsender ──────►│ standby2 (read-only)
                   │                  │   │
                   │ archiver ──► WAL │   ▼
                   │   archive  store │ walsender ──► standby3 (cascading)
                   └──────────────────┘

Primary needs:

• wal_level = replica (or logical)
• max_wal_senders >= N + slack
• max_replication_slots >= N
• replication-user role (CREATE ROLE rep REPLICATION LOGIN PASSWORD 'x')
• pg_hba.conf rule allowing replication connections

Standby needs:

• base backup from primary (pg_basebackup -R writes both standby.signal and primary_conninfo)
• standby.signal file in $PGDATA
• primary_conninfo GUC pointing at primary
• optional: primary_slot_name for bounded WAL retention

Standby Identity Files (PG12+)

Two presence files (empty content; their existence triggers behavior):

Verbatim from recovery-config.html: "In releases prior to PostgreSQL 12, recovery configuration was specified in a separate recovery.conf file."³

Both files: empty content. PostgreSQL checks for existence at startup. Removing standby.signal mid-life requires restart (file is read at startup, not periodically).

pg_basebackup -R writes standby.signal automatically, plus appends primary_conninfo to postgresql.auto.conf.

primary_conninfo and primary_slot_name

primary_conninfo (sighup-context, since PG12 was here) = libpq conninfo string. Standby's walreceiver uses it to connect.

# postgresql.auto.conf (or postgresql.conf)
primary_conninfo = 'host=primary.example.com port=5432 user=replicator
                    sslmode=verify-full sslrootcert=/etc/postgres/ca.crt
                    application_name=standby1 channel_binding=require
                    options=''-c statement_timeout=0'''
primary_slot_name = 'standby1_slot'

Three operational rules:

1. application_name in primary_conninfo is what shows up in pg_stat_replication.application_name AND what synchronous_standby_names matches against. Pick stable names.

2. Use libpq service file (~/.pg_service.conf) or PGSERVICE to avoid embedding password literally. Cross-reference 48-authentication-pg-hba.md.

3. primary_slot_name ties standby to a named replication slot on primary. Without it, primary may recycle WAL standby still needs (controlled by wal_keep_size on primary). With it, slot retains WAL until standby acknowledges — but unbounded retention if standby stalls. Cap with max_slot_wal_keep_size. Cross-reference 75-replication-slots.md.

wal_level Required Settings

wal_level (postmaster-context — restart required) controls WAL detail:

Pick replica for physical streaming. Pick logical if planning to also run logical replication / CDC. Logical implies replica.

hot_standby (Read Queries on Standby)

hot_standby = on (default since PG10) on standby = allow read-only queries during recovery. off = standby is replay-only, no client queries.

Standby restrictions (verbatim from hot-standby.html):

• No INSERT/UPDATE/DELETE/MERGE
• No DDL
• No SERIALIZABLE isolation (verbatim "Serializable transactions are not allowed on hot standby servers")⁴
• pg_replication_origin_* functions disabled
• LISTEN/NOTIFY disabled
• Temp tables: only via pg_temp namespace allowed since PG14

hot_standby_feedback (Block Primary Vacuum)

hot_standby_feedback = on (sighup-context) makes standby's walreceiver send its xmin horizon back to primary. Primary delays autovacuum from removing tuples standby still references.

Trade-off:

Recommendation: on for reporting/analytics standbys (queries are long-running, bloat acceptable). off for HA-only standbys (short queries, prefer cancellation over primary bloat).

synchronous_commit Durability Dial

synchronous_commit (user-context — set per session, transaction, or cluster) controls how far WAL must travel before COMMIT returns success.

Per-transaction override:

BEGIN;
SET LOCAL synchronous_commit = off;
INSERT INTO event_log (payload) SELECT payload FROM staging;
COMMIT;

Cluster-wide via ALTER SYSTEM or postgresql.conf. Per-role via ALTER ROLE webapp SET synchronous_commit = on;. Cross-reference 46-roles-privileges.md.

local is useful when you have synchronous standbys configured but a specific batch transaction can tolerate primary-only durability — bypasses sync wait without compromising primary fsync.

synchronous_standby_names (Quorum vs Priority)

synchronous_standby_names (sighup-context) = list of standbys that must ack before sync synchronous_commit levels return.

Three syntaxes:

# Empty string (default) — async, no standby is sync
synchronous_standby_names = ''

# Simple list = priority mode, FIRST 1 implicit
synchronous_standby_names = 'standby1, standby2, standby3'

# Priority mode explicit — first N from list must ack
synchronous_standby_names = 'FIRST 2 (standby1, standby2, standby3)'

# Quorum mode — ANY N of the listed must ack
synchronous_standby_names = 'ANY 2 (standby1, standby2, standby3)'

# Wildcard — any standby with matching application_name
synchronous_standby_names = 'ANY 1 (*)'

Names matched against pg_stat_replication.application_name. application_name set via primary_conninfo's application_name=... parameter.

Operational rules:

• Sync standby that disconnects → COMMIT blocks until either (a) standby reconnects, (b) timeout via wal_sender_timeout, (c) operator removes it from list and reloads. No automatic fallback to async — explicit policy.
• pg_stat_replication.sync_state shows current status: async / potential (in list but not currently sync) / sync (currently sync) / quorum (member of quorum group).

max_standby_archive_delay / max_standby_streaming_delay

When standby's WAL apply needs to remove tuples a running standby query references, conflict resolution:

Three behaviors:

• -1 = wait forever. Standby query never cancelled. WAL apply blocks indefinitely. Lag accumulates.
• 0 = no delay. Cancel queries immediately on conflict. Maximum apply throughput.
• positive value = wait this long, then cancel.

Combine with hot_standby_feedback: feedback prevents the conflict from arising; max_standby_*_delay controls behavior when conflict already arose.

Recovery Target GUCs

When recovery.signal present (point-in-time recovery, NOT regular standby), recovery target controls when to stop replay and promote.

Verbatim PG12: "Cause recovery to advance to the latest timeline by default ... recovery_target_timeline now defaults to latest. Previously, it defaulted to current."⁵

Verbatim PG12: "Do not allow multiple conflicting recovery_target* specifications ... only allow one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid."⁶

Cross-reference 84-backup-physical-pitr.md for full PITR walkthrough.

Cascading Replication

Standby may serve as upstream for downstream standby. Reduces load on primary, useful for geographic distribution.

Setup:

• Cascading source standby needs max_wal_senders > 0 (already required for any standby that receives traffic).
• Downstream standby's primary_conninfo points at cascading-source standby instead of original primary.
• Downstream sees same WAL stream eventually. Promotion of cascading source promotes downstream's source — but downstream itself needs its own promotion to become a primary.

Constraints:

• Cascading source must have wal_level >= replica.
• Synchronous replication only via direct standby of primary — cascaded standbys are always async with respect to primary's COMMIT.

Promotion (pg_promote())

pg_promote(wait boolean DEFAULT true, wait_seconds integer DEFAULT 60) (PG12+) ends recovery, promotes to primary.⁷

SELECT pg_promote(true, 60);  -- wait up to 60s for promotion to complete

Returns true if promoted, false if timeout. Standby becomes primary, can accept writes. New timeline ID created.

Pre-PG12 alternatives (still work):

• pg_ctl promote -D $PGDATA
• Touch promote_trigger_file (REMOVED in PG16)²

Recovery-pause alternative:

SELECT pg_wal_replay_pause();    -- pause apply (does not promote)
SELECT pg_get_wal_replay_pause_state();  -- 'not paused' / 'pause requested' / 'paused' (PG14+)
SELECT pg_wal_replay_resume();   -- resume apply

Verbatim PG14: "Add function pg_get_wal_replay_pause_state() to report the recovery state ... It gives more detailed information than pg_is_wal_replay_paused(), which still exists."⁸

After promotion: timeline file (<timeline>.history) records the divergence. Old primary becomes diverged — re-attaching requires pg_rewind or fresh pg_basebackup. Cross-reference 89-pg-rewind.md.

pg_stat_replication View

Run on primary to inspect downstream standbys.

Lag interpretation: pg_wal_lsn_diff(primary_lsn, standby_replay_lsn) returns bytes. replay_lag returns interval — but only meaningful when standby is actively replaying. Idle standby: replay_lag is NULL despite sent_lsn = replay_lsn.

Per-Version Timeline

Examples / Recipes

Recipe 1 — Baseline production primary + standby

Primary postgresql.conf:

# WAL + replication
wal_level = replica
max_wal_senders = 10
max_replication_slots = 10
wal_keep_size = 0           # rely on slots, not wal_keep_size
max_slot_wal_keep_size = 64GB

# Synchronous (one named standby must ack)
synchronous_standby_names = 'standby1'
synchronous_commit = on

# Crash safety
fsync = on
full_page_writes = on

# Archive (independent of streaming)
archive_mode = on
archive_command = 'test ! -f /archive/%f && cp %p /archive/%f'

# Logging
log_replication_commands = on

Primary pg_hba.conf:

# TYPE  DATABASE      USER          ADDRESS          METHOD
hostssl replication   replicator    10.0.0.0/8       scram-sha-256
host    all           all           0.0.0.0/0        reject

Replication user on primary:

CREATE ROLE replicator REPLICATION LOGIN PASSWORD '<scram-hash>';
SELECT pg_create_physical_replication_slot('standby1_slot');

Standby setup (run on standby host with empty $PGDATA):

sudo -u postgres pg_basebackup \
    -h primary.example.com -p 5432 -U replicator \
    -D $PGDATA -X stream -P -R -S standby1_slot

# pg_basebackup -R wrote standby.signal + appended primary_conninfo to postgresql.auto.conf

Standby postgresql.conf additions:

hot_standby = on
hot_standby_feedback = off       # HA standby — prefer query cancel over primary bloat
max_standby_streaming_delay = 30s
max_standby_archive_delay = 30s

# application_name set via primary_conninfo (in postgresql.auto.conf)
# Match against synchronous_standby_names = 'standby1'

Verify on primary:

SELECT application_name, state, sync_state,
       pg_size_pretty(pg_wal_lsn_diff(sent_lsn, replay_lsn)) AS lag_bytes,
       replay_lag
FROM pg_stat_replication;

Recipe 2 — Quorum sync across three AZs

Primary in AZ-A, two standbys (standby_az_b, standby_az_c) in AZ-B and AZ-C. Want any 1 of 2 to ack — survive single-AZ failure without blocking COMMITs.

synchronous_standby_names = 'ANY 1 (standby_az_b, standby_az_c)'
synchronous_commit = on

Each standby's primary_conninfo sets application_name=standby_az_b (or _c).

Verify quorum behavior:

SELECT application_name, sync_state FROM pg_stat_replication;
-- Expect: both rows show sync_state = 'quorum'

Stop one standby, verify primary still accepts writes (the other ack satisfies quorum). Stop both, verify primary blocks (no quorum possible).

Recipe 3 — Per-role async commit for batch jobs

Cluster default synchronous_commit = on (sync standby blocks). Batch ETL role can tolerate primary-only durability for known-resumable jobs.

ALTER ROLE batch SET synchronous_commit = local;  -- skip sync standby wait
ALTER ROLE webapp SET synchronous_commit = on;    -- explicit (default)
ALTER ROLE reporter SET default_transaction_read_only = on;  -- belt-and-braces

Cross-reference 46-roles-privileges.md for per-role baseline pattern.

Recipe 4 — Reporting standby with hot_standby_feedback

Long-running analytic queries on standby. Want no random query-cancel errors. Accept primary bloat trade-off.

Standby postgresql.conf:

hot_standby = on
hot_standby_feedback = on
max_standby_streaming_delay = 5min  # belt-and-braces; feedback should prevent the conflict
max_standby_archive_delay = 5min

Monitor primary bloat after enabling. If pg_stat_user_tables.n_dead_tup grows unbounded on hot tables, standby has stuck transaction. Diagnose:

-- Run on primary
SELECT application_name, backend_xmin, age(backend_xmin) AS xmin_age
FROM pg_stat_replication
WHERE backend_xmin IS NOT NULL
ORDER BY age(backend_xmin) DESC;

If xmin_age grows continuously, standby has long-running transaction. Either kill it on standby or accept bloat.

Cross-reference 27-mvcc-internals.md for xmin horizon.

Recipe 5 — Safe controlled switchover (planned promotion)

Primary becomes secondary, standby becomes primary. Zero data loss. Manual orchestration (use Patroni/repmgr in production — cross-reference 78-ha-architectures.md).

# Step 1: On primary — stop application traffic, force checkpoint
psql -h primary -c "CHECKPOINT;"

# Step 2: On primary — stop cleanly (waits for standby to catch up)
sudo systemctl stop postgresql

# Step 3: On standby — verify caught up to old primary's last LSN
psql -h standby -c "SELECT pg_last_wal_replay_lsn();"

# Step 4: On standby — promote
psql -h standby -c "SELECT pg_promote(true, 60);"

# Step 5: Verify standby is now primary
psql -h standby -c "SELECT pg_is_in_recovery();"  -- should be false

# Step 6: Reconfigure old primary as standby of new primary
# Either pg_rewind (if wal_log_hints or data_checksums enabled)
# or fresh pg_basebackup

# Step 7: Update application connection string to point at new primary

Cross-reference 89-pg-rewind.md for re-attaching old primary.

Recipe 6 — recovery_min_apply_delay for human-error rollback

Apply WAL with 1-hour delay. Bug-induced data loss can be reverted by promoting standby before delayed WAL applies.

Standby postgresql.conf:

recovery_min_apply_delay = 1h

Standby still receives WAL immediately (network) but applies it 1 hour late. If primary corrupts data at 10:00, you have until 11:00 to promote standby and stop replay.

Trade-offs:

• Standby data is always 1 hour stale.
• WAL accumulates on standby disk (1 hour worth).
• During the delay window, RPO is 0 but RTO is "promote + delete remaining WAL" = minutes.
• Slot retention on primary still measures "WAL written" not "WAL applied" — slot does NOT block primary from recycling.

Recipe 7 — Diagnose stuck state = 'catchup'

Standby connected but not caught up. Common when standby was offline for a while.

-- Run on primary
SELECT application_name, state,
       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), sent_lsn))   AS sent_behind,
       pg_size_pretty(pg_wal_lsn_diff(sent_lsn, write_lsn))               AS write_behind,
       pg_size_pretty(pg_wal_lsn_diff(write_lsn, flush_lsn))              AS flush_behind,
       pg_size_pretty(pg_wal_lsn_diff(flush_lsn, replay_lsn))             AS replay_behind
FROM pg_stat_replication
WHERE state = 'catchup';

Bottleneck identification:

• High sent_behind → primary CPU-bound or max_wal_senders saturated.
• High write_behind → standby network or OS write cache slow.
• High flush_behind → standby disk fsync slow.
• High replay_behind → standby CPU-bound on apply (typically: long transactions on standby blocking apply, or recovery_min_apply_delay set).

Recipe 8 — Failover slot sync (PG17+)

Logical replication slots normally only exist on primary. After failover, subscribers must rebuild slots from scratch (data loss). PG17 introduces failover slots.

Primary:

SELECT pg_create_logical_replication_slot('app_slot', 'pgoutput', false, true);
-- 4th arg = failover = true

Standby postgresql.conf (PG17+):

sync_replication_slots = on

Primary postgresql.conf (PG17+):

synchronized_standby_slots = 'standby1'

Verbatim PG17: "Allow specification of physical standbys that must be synchronized before they are visible to subscribers."²⁶

After promotion, standby's slot is in sync with subscribers' last-known LSN. Subscribers reconnect to new primary without restart-from-scratch.

Cross-reference 74-logical-replication.md and 75-replication-slots.md.

Recipe 9 — Cascading replication for geographic distribution

Primary in US-East, hub-standby in US-West, downstream standbys in US-West local DCs.

Hub-standby postgresql.conf:

hot_standby = on
max_wal_senders = 5
max_replication_slots = 5
# primary_conninfo points at primary (US-East)

Downstream standby postgresql.conf:

hot_standby = on
# primary_conninfo points at hub-standby (US-West) — NOT at primary
primary_conninfo = 'host=hub-standby.us-west.example.com user=replicator ...'

Bandwidth saving: primary ships WAL once across US-East→US-West. Hub then redistributes locally.

Caveat: cascading standbys are always async with respect to primary's COMMIT. Primary's synchronous_standby_names cannot include cascaded standbys.

Recipe 10 — Enable channel binding for replication

PG14 added SCRAM channel binding for client-side. Apply to replication connections too.

Primary pg_hba.conf:

hostssl replication replicator 10.0.0.0/8 scram-sha-256

Standby primary_conninfo:

primary_conninfo = 'host=primary.example.com port=5432 user=replicator
                    sslmode=verify-full sslrootcert=/etc/ssl/ca.crt
                    channel_binding=require
                    application_name=standby1'

Cross-reference 49-tls-ssl.md for full TLS hardening.

Recipe 11 — Detect query-cancel cascade

Standby logs flooded with ERROR: canceling statement due to conflict with recovery. Means max_standby_streaming_delay too low for query workload.

-- Run on standby
SELECT count(*) AS cancels_today
FROM pg_stat_database
WHERE datname = current_database();
-- conflicts column was added in PG14

Three mitigations:

1. Raise max_standby_streaming_delay to e.g., 5min. Trade off: lag can grow during heavy primary writes.
2. Enable hot_standby_feedback = on. Trade off: primary bloat.
3. Move queries to a dedicated reporting standby with both #1 and #2 enabled.

Recipe 12 — Force WAL switch + verify standby ack

For scripted operations that need confirmation a checkpoint reached the standby:

-- On primary
SELECT pg_switch_wal();

-- Wait for standby to catch up
DO $$
DECLARE
    target_lsn pg_lsn := pg_current_wal_lsn();
    standby_lsn pg_lsn;
BEGIN
    LOOP
        SELECT replay_lsn INTO standby_lsn
        FROM pg_stat_replication WHERE application_name = 'standby1';

        EXIT WHEN standby_lsn >= target_lsn;
        PERFORM pg_sleep(0.1);
    END LOOP;
    RAISE NOTICE 'standby1 caught up to %', target_lsn;
END$$;

Recipe 13 — Emergency demotion (force-pause apply)

Standby is about to apply destructive WAL. Pause replay immediately.

-- On standby
SELECT pg_wal_replay_pause();

-- Verify
SELECT pg_get_wal_replay_pause_state();  -- 'paused'

-- After investigation, either resume or promote
SELECT pg_wal_replay_resume();           -- continue
-- OR
SELECT pg_promote(true, 60);             -- promote, abandon remaining WAL

pg_get_wal_replay_pause_state() PG14+ returns three values: not paused, pause requested, paused. Pre-PG14 use pg_is_wal_replay_paused() (boolean only).

Gotchas / Anti-patterns

1. recovery.conf carried forward from PG≤11 prevents PG12+ startup. Server refuses to start with verbatim error referencing the file. Delete it and migrate settings to postgresql.conf + standby.signal.¹

2. promote_trigger_file removed in PG16. Custom failover scripts that touched a trigger file silently no-op on PG16+. Use pg_promote() or pg_ctl promote.²

3. synchronous_standby_names empty string ≠ no sync — sync is OFF. A common misconfiguration is to set synchronous_commit = on cluster-wide thinking it enables sync replication. Without synchronous_standby_names populated, every commit is "sync to primary disk only" — no standby is involved.

4. Sync standby disconnect blocks all writes. No automatic fallback to async. COMMIT hangs forever (or until wal_sender_timeout declares standby dead). Operator must explicitly remove from synchronous_standby_names and reload to unblock.

5. hot_standby_feedback = on + abandoned standby = unbounded primary bloat. If standby is offline but slot is retained, primary's xmin horizon is held back by the last reported standby xmin. Vacuum cannot remove dead tuples. Combine with max_slot_wal_keep_size AND monitor pg_stat_replication for missing standbys.

6. max_standby_streaming_delay = -1 is "wait forever" — apply lag grows unbounded. Standby reads block primary's commits if you also have sync replication. Pick a finite value or use hot_standby_feedback.

7. max_standby_streaming_delay = 0 does not mean "fail fast on any conflict" — it means "cancel as soon as conflict arises". WAL apply does not wait. If your reporting workload has even brief queries, you'll see frequent cancels.

8. primary_slot_name without max_slot_wal_keep_size = unbounded primary disk usage. Stuck/dead standby retains WAL forever. Combine with max_slot_wal_keep_size (PG13+) to cap.³² Cross-reference 75-replication-slots.md.

9. wal_keep_size is a fallback for slot-less replication. With slots, set wal_keep_size = 0 and let slots manage retention. Both at once = double-counting.

10. application_name in primary_conninfo must be unique per standby. Duplicate names → synchronous_standby_names matches whichever connects first; behavior undefined for the duplicate. Also breaks pg_stat_replication row identification.

11. Synchronous replication does NOT replicate atomically — it replicates on COMMIT. If primary crashes mid-transaction, the in-progress writes are not on the standby. After failover, the in-progress transaction is rolled back as if it never started. This is correct behavior, but subtle.

12. SERIALIZABLE isolation forbidden on standby. Verbatim from hot-standby.html: "Serializable transactions are not allowed on hot standby servers."⁴ Use REPEATABLE READ instead.

13. LISTEN/NOTIFY does not propagate to standby. A NOTIFY issued on primary does not fire LISTEN handlers on standby connections. Standby applications must connect to primary for notifications.

14. Temp tables not allowed on standby pre-PG14. PG14 relaxed: temp tables allowed via pg_temp namespace. Older versions: any CREATE TEMP TABLE errors out.

15. Standby does NOT serve transactions started on primary. Cannot start tx on primary, route SELECT to standby. synchronous_commit = remote_apply only ensures the COMMIT is visible on standby — does not transfer the transaction itself.

16. pg_basebackup -R writes primary_conninfo to postgresql.auto.conf. Hand-editing postgresql.conf does NOT override (postgresql.auto.conf precedence is higher). Use ALTER SYSTEM SET primary_conninfo = '' to clear, then re-set.

17. pg_promote() returns immediately if wait = false. Caller gets back false (because not yet complete) but promotion is in flight. Always check pg_is_in_recovery() to confirm.

18. recovery_target_inclusive = true (default) means STOP AFTER target. If recovery_target_xid = 12345, replay includes XID 12345 and stops just after. Set inclusive = false to stop just before.

19. Multiple recovery_target_* GUCs is an error since PG12. Verbatim: "only allow one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid."⁶

20. recovery_target_timeline = 'latest' is the PG12+ default. Pre-PG12 default was 'current'. After failover, new timeline is created — old standbys following current would be stuck on the dead branch. latest follows the newly promoted timeline automatically.⁵

21. pg_stat_replication.replay_lag is NULL on idle standby. The lag interval is computed from "primary commit timestamp" minus "standby reply at that LSN". If primary hasn't committed anything, there's nothing to compare. Insert a heartbeat row periodically if you need a non-NULL value.

22. Cascaded standbys cannot satisfy primary's synchronous_standby_names. Primary's sync requirement is only satisfied by standbys connected directly to primary. Cascaded standbys are always async from primary's perspective.

23. vacuum_defer_cleanup_age removed in PG16. Old advice "set this to defer vacuum until standby has caught up" no longer works. Use hot_standby_feedback + replication slots instead.¹⁹

See Also

• 33-wal.md — WAL format, wal_level deep dive, synchronous_commit low-level mechanics
• 34-checkpoints-bgwriter.md — checkpoint interaction with replication
• 46-roles-privileges.md — replication user privileges
• 48-authentication-pg-hba.md — hostssl replication rules
• 49-tls-ssl.md — channel binding for replication conns
• 58-performance-diagnostics.md — pg_stat_replication view full reference
• 63-internals-architecture.md — walsender / walreceiver / startup process
• 74-logical-replication.md — logical replication contrast
• 76-logical-decoding.md — logical decoding on standbys (PG16+); output-plugin surface
• 75-replication-slots.md — slot mechanics shared by physical + logical
• 77-standby-failover.md — failover decision-tree
• 78-ha-architectures.md — HA pattern catalog
• 79-patroni.md — Patroni cluster manager
• 84-backup-physical-pitr.md — PITR walkthrough
• 85-backup-tools.md — pgBackRest / Barman / WAL-G
• 89-pg-rewind.md — re-attach diverged former primary
• 90-disaster-recovery.md — DR runbook

Sources

Primary references:

• PG16 §27.2 Log-Shipping Standby Servers — https://www.postgresql.org/docs/16/warm-standby.html
• PG16 §20.6 Replication GUCs — https://www.postgresql.org/docs/16/runtime-config-replication.html
• PG16 §20.5 WAL GUCs — https://www.postgresql.org/docs/16/runtime-config-wal.html
• PG16 §27.4 Hot Standby — https://www.postgresql.org/docs/16/hot-standby.html
• PG16 §30.4 Asynchronous Commit — https://www.postgresql.org/docs/16/wal-async-commit.html
• PG16 Appendix O.1 (recovery.conf migration) — https://www.postgresql.org/docs/16/recovery-config.html
• PG16 §55.4 Streaming Replication Protocol — https://www.postgresql.org/docs/16/protocol-replication.html
• PG16 pg_basebackup reference — https://www.postgresql.org/docs/16/app-pgbasebackup.html
• PG16 pg_stat_replication view — https://www.postgresql.org/docs/16/monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW
• PG16 Recovery Control Functions — https://www.postgresql.org/docs/16/functions-admin.html#FUNCTIONS-RECOVERY-CONTROL