wal_sender_shutdown_timeout

Definition PG 20 devel manual

Specifies the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver. If this value is specified without units, it is taken as milliseconds. A value of -1 (the default) disables the timeout mechanism, allowing the WAL sender to wait as long as necessary for the receiver to catch up. A value of 0 causes the WAL sender to terminate without waiting for the receiver to catch up.

When replication is in use, the sending server normally waits until all WAL data has been transferred to the receiver before completing shutdown. This helps keep sender and receiver in sync after shutdown, which is especially important for physical replication switchovers, but it can delay shutdown.

If this parameter is set to zero or a positive value, the server stops waiting and completes shutdown when the timeout expires. This can shorten shutdown time, for example, when replication is slow on high-latency networks or when a logical replication apply worker is blocked waiting for locks. However, in this case the sender and receiver may be out of sync after shutdown. Care should be taken to select a value high enough to allow all WAL data to be replicated to the receiver under normal circumstances.

This parameter can be set in primary_conninfo and in the CONNECTION clause of CREATE SUBSCRIPTION (for example, include options=-cwal_sender_shutdown_timeout=10s in the connection string), allowing different timeouts per replication connection. For example, when both physical and logical replication are used, it can be disabled for physical replication (e.g., for switchovers) while enabled for logical replication to limit shutdown time.

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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: 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.