Make recovery_target_time reloadable without server restart

[NikolayS]

Summary

This change makes the recovery_target_time parameter reloadable via SIGHUP without requiring a full server restart, improving operational flexibility for standby/replica servers during point-in-time recovery operations.

Key Changes

• GUC Context Change: Changed recovery_target_time from PGC_POSTMASTER to PGC_SIGHUP context, allowing dynamic reload via pg_reload_conf() or SIGHUP signal

• Validation Hook Refactoring: Moved mutual-exclusion validation from the assign hook (which cannot safely throw errors in PGC_SIGHUP context) to the check hook, which can safely reject invalid values

• Dynamic Timestamp Parsing: Modified the assign hook to re-parse recovery_target_time_string into recoveryTargetTime on each reload, ensuring the parsed timestamp is always in sync with the GUC value

• Resume-on-Change Logic: Added mechanism to automatically resume recovery when recovery_target_time is changed to a later value while recovery is paused at the previous target, eliminating the need for manual intervention

• Backward Target Protection: Added validation to prevent setting recovery_target_time to an earlier value than already-replayed WAL during active recovery

• Documentation & Tests: Updated configuration documentation and added comprehensive TAP tests covering reload scenarios, edge cases, and interaction with recovery_target_action

Implementation Details

The solution maintains backward compatibility by:

• Keeping all other recovery_target_* parameters as PGC_POSTMASTER (preventing target type switches without restart)
• Preserving existing startup-time behavior unchanged
• Using the standard GUC check/assign hook pattern for safe value validation and application

The most significant architectural change is the resume-on-change logic in the pause handler, which detects when the recovery target has been updated to a point beyond the current replay position and automatically resumes replay to reach the new target.

https://claude.ai/code/session_01MWrPG3xKvaiEEXmrCrTDLE

[NikolayS]

Implementation Complete — All Tests Pass ✅

What was implemented

Commit 1: Core implementation (e82c524)

• Changed recovery_target_time GUC context from PGC_POSTMASTER → PGC_SIGHUP
• Rewrote check/assign hooks: safe timestamp parsing via parse_recovery_target_time_safe(), mutual-exclusion via raw GUC string inspection (target_type_conflict_exists())
• Added RecoveryPauseReason enum to distinguish "paused at target" from "paused via pg_wal_replay_resume()"
• Modified recoveryPausesHere() to detect target-time advances and resume replay
• Added goto redo mechanism in PerformWalRecovery() to re-enter replay loop

Commit 2: Tests and docs (266d4de)

• TAP test with 9 assertions covering 5 core scenarios
• Updated config.sgml documentation
• Updated spec doc with completion checkboxes

Files changed

File	Change
src/backend/utils/misc/guc_parameters.dat	PGC_POSTMASTER → PGC_SIGHUP
src/backend/utils/misc/guc_tables.c	Made 4 GUC string vars non-static for conflict detection
src/include/access/xlogrecovery.h	RecoveryPauseReason enum, extern declarations
src/backend/access/transam/xlogrecovery.c	All runtime logic (~200 lines changed)
doc/src/sgml/config.sgml	Documentation update
src/test/recovery/t/053_recovery_target_time_reload.pl	New TAP test
src/test/recovery/meson.build	Test registration

Docker test evidence

Built from source and ran TAP tests in debian:bookworm-slim container:

$ docker run --rm pg-recovery-test

t/053_recovery_target_time_reload.pl .. ok
All tests successful.
Files=1, Tests=9, 13 wallclock secs ( 0.01 usr  0.00 sys +  0.11 cusr  0.26 csys =  0.38 CPU)
Result: PASS

Test scenarios verified

1. Pause at T1, advance to T2: Recovery pauses at T1 (200 rows), target advanced via pg_reload_conf(), recovery resumes and re-pauses at T2 (300 rows) ✅
2. Same target reload: No-op, stays paused ✅
3. Earlier target reload: No-op, stays paused ✅
4. pg_wal_replay_resume(): Proceeds to promotion (not re-enter replay) ✅
5. Mutual exclusion: Rejects conflicting recovery target types ✅

Design decisions (per spec v2)

• Uses goto redo (PostgreSQL-idiomatic) instead of outer while loop
• RecoveryPauseReason distinguishes target-advance unpause from manual resume
• Raw GUC string inspection avoids SIGHUP processing-order sensitivity
• parse_recovery_target_time_safe() shared by check hook and startup validation

🤖 Generated with Claude Code

[NikolayS]

Prior Art Research: No Previous Attempts Found

Searched PostgreSQL mailing lists (pgsql-hackers, pgsql-general), commitfest, and community resources. No prior patch or proposal exists for making recovery_target_time reloadable via SIGHUP.

Related history

• PostgreSQL 12 (2019): All recovery.conf params moved to GUCs as PGC_POSTMASTER, with explicit note: "this could be refined in the future case by case"
• 6+ recovery params already loosened to PGC_SIGHUP: archive_cleanup_command, promote_trigger_file, recovery_end_command, recovery_min_apply_delay (Peter Eisentraut, 2019), restore_command (Sergei Kornilov, 2020), primary_conninfo/primary_slot_name (by PG 17)
• None of the recovery_target_* family was ever proposed for reloadability
• Known blocker documented in source (xlogrecovery.c:4776): "XXX this code is broken by design. Throwing an error from a GUC assign hook breaks fundamental assumptions of guc.c." — our patch fixes this by moving validation to check hooks
• No objections specific to recovery_target_time reloadability were found in any mailing list thread
• Operational pain well-documented: PostgreSQL docs and Percona blog both describe the restart-to-change-target workflow as a friction point for PITR operations

Conclusion

Strong precedent exists for loosening recovery GUCs case-by-case. The original conservatism was explicitly framed as temporary. This patch is the first to address the recovery_target_* family.

🤖 Generated with Claude Code

[NikolayS]

Phase 2 Complete: All recovery_target_* Parameters Now Reloadable ✅

Scope expanded

In addition to recovery_target_time (Phase 1), these parameters are now reloadable via pg_reload_conf() without restart:

Parameter	Context	Resume behavior when paused
recovery_target_time	PGC_SIGHUP	Auto-resume if new time > paused time
recovery_target_lsn	PGC_SIGHUP	Auto-resume if new LSN > paused LSN
recovery_target_xid	PGC_SIGHUP	Auto-resume on any XID change
recovery_target_name	PGC_SIGHUP	Auto-resume on any name change
recovery_target	PGC_SIGHUP	Accepted on reload
recovery_target_inclusive	PGC_SIGHUP	Takes effect on next stop eval
recovery_target_action	PGC_SIGHUP	pause→promote triggers promotion; pause→shutdown triggers shutdown
recovery_target_timeline	PGC_POSTMASTER	Stays restart-only (unsafe to change mid-recovery)

Key implementation details

• error_multiple_recovery_targets() removed entirely — conflict detection now in check hooks via target_type_conflict_exists() using raw GUC strings
• recoveryPausesHere() generalized with a switch on recoveryTarget type to detect advances for TIME (forward), LSN (forward), XID (any change), NAME (any change)
• recovery_target_action change detection: if action changes away from 'pause' while paused at target, recovery unpauses and the new action (promote/shutdown) takes effect

Docker test evidence

t/053_recovery_target_time_reload.pl .. ok
All tests successful.
Files=1, Tests=14, 18 wallclock secs
Result: PASS

14 assertions across 8 test scenarios:

1. Time target: pause → advance → resume → re-pause ✅
2. Same target reload = no-op ✅
3. Earlier target reload = no-op ✅
4. pg_wal_replay_resume() → promotion ✅
5. Mutual exclusion of target types ✅
6. LSN target: pause → advance LSN → resume → re-pause ✅
7. Action change: pause → promote while paused ✅
8. Inclusive toggle accepted on reload ✅

Prior art

No previous attempt to make any recovery_target_* parameter reloadable was found in PostgreSQL mailing lists or commitfest (see previous comment). Strong precedent from 6+ recovery GUCs already loosened to PGC_SIGHUP since PostgreSQL 12.

🤖 Generated with Claude Code