wal_sender_shutdown_timeout
Fact — official short description: “Sets the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver.”
Identity
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG19 Beta 3 |
| Present in | PG19 Beta 3 |
| Removed in | No |
| Introduction commit | a8f45dee9176 — Add wal_sender_shutdown_timeout GUC to limit shutdown wait for replication |
| Commit date | 2026-04-06 |
| Discussion | thread 1 |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG19 Beta 3 | -1 |
ms |
-1 ms |
How it works
PostgreSQL describes wal_sender_shutdown_timeout as follows: “Sets the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. The atlas measures it in PG19 Beta 3; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.
During shutdown a sender normally waits until outstanding WAL reaches its receiver. The default -1 waits without a timeout, zero stops immediately, and a positive interval bounds the wait at the cost of possible sender/receiver divergence; connection options can set different policies for physical and logical replication links.
Read it together with wal_sender_timeout, wal_receiver_timeout, synchronous_commit, synchronous_standby_names. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | Model normal failover and worst-case lag before setting a bound. Observe sender state, retained WAL, shutdown time, and receiver catch-up; preserve enough capacity for monitoring and planned switchovers. |
| OLAP | Account for large transactions, bulk loads, slow apply, and long-distance links. A short timeout can make shutdown faster but transfer recovery work and inconsistency risk to the next startup. |
| Small nodes | Use few slots and senders, watch pg_wal disk consumption, and keep timeout behavior explicit. Test shutdown and restart with the receiver both healthy and unavailable. |
Pigsty
Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.
| Template | Effective value | Versus upstream boot | Source expression |
|---|---|---|---|
| OLTP | Unmodified | — | — |
| OLAP | Unmodified | — | — |
| CRIT | Unmodified | — | — |
| TINY | Unmodified | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG19 Beta 3 unmodified; OLAP: PG19 Beta 3 unmodified; CRIT: PG19 Beta 3 unmodified; TINY: PG19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Treating the measured boot_val for wal_sender_shutdown_timeout as proof of the effective value on an initialized or managed cluster.
- Applying a change as though it were immediate while pg_settings reports user context.
- Changing this setting in isolation without checking the linked limits, observability, and rollback path.
- Depending on beta behavior in production without retesting the PostgreSQL 19 final release.
Related parameters
wal_sender_timeout · wal_receiver_timeout · synchronous_commit · synchronous_standby_names · max_wal_senders
References
- PostgreSQL 19 Beta 3 — wal_sender_shutdown_timeout
- PostgreSQL 19 release notes
- Machine-readable GUC export