Replication Category Parameters

This document describes the parameters related to the replication category in the system configuration parameters.

Note!
To ensure system stability and security, please exercise caution when manually modifying the relevant parameters.

These settings control the behavior of stream replication features. The server can be either a master server or a standby server. The master server can send data, while the standby server is always the recipient of replicated data. These parameters are primarily used for sending servers and standby servers, although some are only meaningful on the master server.

Sending Servers

These parameters must be set on the Master and any Standby that will send replica data.

max_replication_slots

Specifies the maximum number of replication slots that the server can support.

This parameter can only be set when the server is started.
Setting it to a value lower than the current number of existing replication slots will prevent the server from starting.
To enable the use of replication slots, wal_level must be set to replica or higher.

Data type	Default value	Valid range	Setting category
int	10	1 ～ 262143	segments；system；restart

max_slot_wal_keep_size

Set the maximum WAL size (MB) that can be retained by the replication slot.

If the WAL on the disk occupies space equal to this parameter value, the replication slot will be marked as failed, and segments will be released for deletion or recycling.
The default value is -1, which disables this feature.

Data type	Default value	Value range	Setting category
int	-1	-1 ～ INT_MAX/1024	segments；system；reload

max_wal_senders

Specify the maximum number of concurrent connections from standby servers or streaming base backup clients (i.e., the maximum number of WAL send processes that can run simultaneously).

A value of 0 disables replication.
Sudden disconnections from streaming clients may leave an orphaned connection slot (until the timeout is reached), so this parameter should be set slightly higher than the maximum number of client connections, allowing disconnected clients to reconnect immediately.
This parameter can only be set at server startup. Additionally, wal_level must be set to replica or higher to allow connections from standby servers.
When running a standby server, you must set this parameter to the same or a higher value than on the primary server. Otherwise, queries will not be allowed on the standby server.

Data type	Default value	Valid range	Setting category
int	10	0 ～ 262143	segments；system；restart

track_commit_timestamp

Record the commit time of transactions.

| Data type | Default value | Setting category | | --- | --- | --- | --- | | boolean | off | segments；system；restart |

wal_init_zero

When this parameter is set to on, new WAL files are padded with zeros.

In some file systems, this ensures that file space is allocated before we need to write WAL records.
However, Copy-On-Write (COW) file systems may not benefit from this parameter setting, so this parameter skips unnecessary work.
If set to off, only the last bytes are written when the file is created, so it has an expected size.

Data type	Default value	Setting category
boolean	on	segments；session；reload；superuser

wal_keep_segments

Specifies the minimum number of past log file segments that can be retained in the pg_wal directory when a standby server needs to obtain log segments for streaming replication.

Each segment is typically 16 megabytes. If a standby server connected to the sending server falls behind by more than wal_keep_segments segments, the sending server may remove a WAL segment that the standby server still needs, in which case the replication connection will be interrupted. Ultimately, the downstream connection will also fail (however, if WAL archiving is in use, the standby server can recover by retrieving segments from the archive).
Only sets the minimum number of retained WAL segments in pg_wal; the system may need to retain more segments for WAL archiving or recovery from a checkpoint.
When this parameter is set to 0 (default), the system does not retain any extra segments for standby purposes, so the number of old WAL segments available to the standby server is a function of the previous checkpoint position and the WAL archiving status.

Data type	Default value	Value range	Setting category
int	64	0 ~ INT_MAX	segments；system；reload

wal_recycle

Recycle WAL files.

When this parameter is set to on, WAL files are recycled by renaming them to avoid creating new files.
In COW file systems, creating new files may be faster, so this parameter is automatically disabled.

Data type	Default value	Setting category
boolean	on	segments；session；reload；superuser

wal_sender_timeout

Disconnect replication connections that have been inactive for longer than this specified time (in milliseconds).

This is useful for the sending server to detect a failure of a standby server or a network interruption.
A value of 0 disables the timeout mechanism.
For clusters distributed across multiple geographic locations, using different values for each location can provide greater flexibility in cluster management. For backup servers with low-latency network connections, smaller values facilitate faster fault detection; for backup servers located at remote locations with high-latency network connections, larger values help better assess the health status of the backup server.
The default value is 300000 milliseconds, equivalent to 5 minutes.

Data type	Default value	Value range	Setting category
int	300000	0 ～ INT_MAX	segments；session；reload；superuser

Master Server

This section is skipped on the Standby server.

Note!
In addition to these parameters, the appropriate wal_level must be set on the Master server, and optional WAL archiving must also be enabled.

synchronous_standby_names

This parameter specifies a list of standby servers that support synchronous replication.

There may be one or more active synchronous standby servers. Once these standby servers confirm receipt of their data, pending transactions will be allowed to proceed.
Synchronous standby servers refer to servers whose names appear at the beginning of this list, are currently connected, and are streaming data in real time. Specifying more than one synchronous standby server can achieve very high availability and prevent data loss.
The names of the standby servers used for this purpose are the application_name set in their connection information, separated by commas in the list.
In the case of physical replication standbys, this should be set in the primary_conninfo setting. If set, the default is the cluster_name setting; otherwise, it is walreceiver.
For logical replication, it can be set in the subscription connection information. For other replication stream consumers, refer to their documentation.
The special item ‘*’ matches any standby name.

This parameter uses one of the following syntaxes to specify a list of standby servers:

[FIRST] num_sync ( standby_name [, ...] )
ANY num_sync ( standby_name [, ...] )
standby_name [, ...]

Where num_sync is the number of synchronous standby servers that the transaction must wait for a response from, and standby_name is the name of a standby server. FIRST and ANY specify the method for selecting synchronous standbys from the listed servers.
The keyword FIRST combined with num_sync specifies a priority-based synchronous replication, causing transactions to wait for commit until their WAL records are replicated to the num_sync synchronous standby servers selected based on priority. For example, setting FIRST 3 (s1, s2, s3, s4) will cause each commit to wait for responses from the three highest-priority standby servers, which are selected from the standby servers s1, s2, s3, and s4.
Standby servers appearing earlier in the list are given higher priority and are considered synchronous standbys. Other standby servers in the list represent potential synchronous standbys. If any current synchronous standby disconnects for any reason, it is immediately replaced by the next highest-priority standby server. The keyword FIRST is optional.
The keyword ANY combined with num_sync specifies a synchronization-based replication method, causing transaction commits to wait until their WAL records are replicated to at least num_sync of the listed standby servers. For example, setting ANY 3 (s1, s2, s3, s4) will cause each commit to proceed immediately after receiving responses from any three of the standby servers s1, s2, s3, and s4.
FIRST and ANY are case-insensitive. If these keywords are used as standby server names, their standby_name must be enclosed in double quotes.
The third syntax is equivalent to the first syntax with FIRST and num_sync set to 1. For example, FIRST 1 (s1, s2) and s1, s2 have the same meaning: either s1 or s2 will be selected as the synchronized standby server.
There is no mechanism to enforce the uniqueness of standby server names. In case of duplicates, one of the matching standbys will be considered higher priority, but it is impossible to determine which one.
Note: Each standby_name should be in the form of a valid SQL identifier, unless it is *. You can use double quotes if necessary. However, note that when comparing standby_name and standby application names, case sensitivity is ignored (regardless of whether double quotes are used). If no synchronous standby names are specified here, synchronous replication cannot be enabled, and transaction commits will not wait for replication. This is the default configuration. Even when synchronous replication is enabled, individual transactions can be configured not to wait for replication by setting the synchronous_commit parameter to local or off.

Data Type	Default Value	Setting Category
string		segments；system；reload

vacuum_defer_cleanup_age

Specify how long (in terms of transaction count) to delay VACUUM and HOT updates before clearing dead row versions.

The default value is 0 transactions, meaning that dead row versions will be cleared as quickly as possible, i.e., as soon as they are no longer visible to any open transactions.
On a primary server that supports a hot standby server, you may want to set this parameter to a non-zero value, which allows queries on the standby server more time to complete without conflicts caused by previous row deletions. However, since this value is measured in terms of the number of write transactions occurring on the primary server, it is difficult to predict exactly how much additional time will be available for queries on the standby server.
You may also consider setting hot_standby_feedback on the standby server as an alternative to using this parameter.
This does not prevent dead rows that have reached the age specified by old_snapshot_threshold from being cleared.

Data type	Default value	Value range	Setting category
int	0	0 to 1000000	segments; system; reload

Standby Servers

This section will be skipped on the Master server.

hot_standby

Specify whether it is possible to connect and run queries during recovery.

This parameter can only be set when the server starts.
It is only effective during archive recovery or in standby mode.

Data type	Default value	Setting category
boolean	off	segments; system; restart

hot_standby_feedback

Specify whether a hot standby server will send feedback to the primary server or upstream standby server regarding queries currently being executed on the standby server.

This parameter can be used to prevent query cancellations caused by record purging, but may result in database bloat on the primary server for certain workloads.
Feedback messages are sent no more frequently than once per wal_receiver_status_interval cycle.
If cascading replication is used, feedback will be propagated upstream until it finally reaches the primary server. The standby server will not perform any other operations after receiving feedback, except for propagating it upstream.
This setting does not override the behavior of old_snapshot_threshold on the primary server. A snapshot on the standby server that exceeds the primary server's age threshold may become unavailable, leading to transaction cancellations on the standby server. This is because old_snapshot_threshold imposes an absolute limit on how long dead rows can exist, thereby preventing the configuration of a standby server from being compromised.

Data Type	Default Value	Setting Category
boolean	off	segments；system；reload

max_standby_archive_delay

When the hot standby server is active, this parameter determines the amount of time (in milliseconds) the standby server should wait before canceling standby queries that conflict with upcoming WAL items. For more details, see Handling Query Conflicts.

When WAL data is archived from the WAL (and is therefore no longer the current WAL), max_standby_archive_delay can be applied.
If no unit is specified, the value is in milliseconds.
The value -1 allows the standby server to wait indefinitely until the conflicting query completes.
Note: max_standby_archive_delay is different from the maximum time a query can run before being canceled; it represents the maximum total time allowed for applying any WAL segment data. Therefore, if a query prior to the WAL segment causes significant delay, subsequent conflicting queries will have less time.

Data type	Default value	Value range	Setting category
int	30000	-1 ～ INT_MAX	segments；system；reload

max_standby_streaming_delay

When WAL data is being received via streaming replication, max_standby_streaming_delay can be applied.
If no unit is specified, the value is in milliseconds.
The value -1 allows the standby server to wait indefinitely until the conflicting query completes.
Note: This parameter is different from the maximum time a previous query can run before being canceled; it represents the maximum total time allowed for receiving WAL data from the primary server and immediately applying it. Therefore, if a query causes significant delay, subsequent conflicting queries will have less time until the standby server catches up again.

Data type	Default value	Valid range	Setting category
int	30000	-1 ～ INT_MAX	segments；system；reload

primary_conninfo

Specify the connection string for the backup server used to connect to the sending server. - If any options are not specified in this string, the corresponding environment variables will be checked. If the environment variables are also not set, the default values will be used.

The connection string should specify the hostname (or address) of the sending server, as well as the port number (if it differs from the default port of the backup server). It should also specify the username corresponding to the appropriate permission role on the sending server (https://www.postgresql.org/docs/12/warm-standby.html#STREAMING-REPLICATION-AUTHENTICATION).
If the sending server requires password authentication, a password must also be provided. It can be specified in the primary_conninfo string or in a separate ~/.pgpass file on the backup server (using replication as the database name).
Do not specify a database name in the primary_conninfo string.
This parameter can only be set when the server starts. If the server is not in standby mode, this setting is invalid.

Data type	Default value	Setting category
string		segments；system；restart；superuser

primary_slot_name

When selectively specifying a connection to the sending server via stream replication, use an existing replication slot to control resource removal on the upstream node.

This parameter can only be set at server startup.
If primary_conninfo is not set, this setting is invalid.

Data type	Default value	Setting category
string		segments；system；restart

promote_trigger_file

Specify a trigger file whose existence will end the recovery state in the standby machine.

Even if this value is not set, you can use pg_ctl promote or call pg_promote to promote the standby machine.

Data type	Default value	Setting category
string		segments；system；reload

recovery_min_apply_delay

By default, the standby server will recover WAL records from the sending server as soon as possible.

A delayed copy of the data is useful as it provides an opportunity to correct data loss errors. This parameter allows the system to recover the delay after a specified time. For example, if you set this parameter to 5min, for a transaction commit operation, the standby server will only replay the transaction when the system clock on the standby server is at least 5 minutes ahead of the commit time reported by the primary server.
If no unit is specified, the value is in milliseconds.
It is possible that the replication delay between servers may exceed the value of this parameter, in which case the delay will not be increased.

Note: The delay is calculated based on the timestamp when the WAL was written on the primary server and the current time on the standby server. Network latency or transmission delays caused by cascading replication configurations may significantly reduce the actual wait time.

If the system clocks on the primary server and standby server are not synchronized, this may cause records to be applied earlier than expected. However, this is not a major issue, as the advantage of this parameter setting far outweighs any time discrepancies between servers.
Delay only occurs on WAL records committed by transactions. Other records are still replayed as quickly as possible, which is not an issue because MVCC visibility rules ensure their effects are not visible until the corresponding commit records are applied.
Once the database being recovered has reached a consistent state, delay is applied until the standby is promoted or triggered. After that, the standby will complete recovery and no longer wait.
Note: This parameter is intended for use with streaming replication deployments. However, if specified, it will be honored in all cases except crash recovery. Using this feature will also delay hot_standby_feedback, which may cause the primary server to swell; use with caution when using both together.
The default value is 0, meaning no delay is added.

Note!
When synchronous_commit is set to remote_apply, synchronous replication is affected by this setting, and each COMMIT must wait to be applied.

Data type	Default value	Valid range	Setting category
int	0	0 ～ INT_MAX	segments；system；reload

wal_receiver_status_interval

Specify the minimum frequency (in seconds) at which the WAL receiver process on the standby server sends information about replication progress to the primary server or upstream standby server.

The standby server will report the last WAL position it has written, the last position flushed to disk, and the last position it has applied.
The value of this parameter is the maximum time interval between reports. Status updates are sent whenever the write or flush position changes, or at least at the frequency specified by this parameter. Therefore, the applied position may lag slightly behind the actual position.
Setting this parameter to 0 completely disables status updates.

Data type	Default value	Valid range	Setting category
int	10	0 ~ INT_MAX/1000	segments；system；reload

wal_receiver_timeout

Stop replicating links that have been inactive for longer than the value specified by this parameter (in milliseconds).

This parameter is useful for backup servers that are receiving data to detect crashes or network disconnections on the primary server.
If no unit is specified, the value is in milliseconds.
A value of 0 indicates that the feature is disabled.

Data type	Default value	Value range	Setting category
int	60000	0 ～ INT_MAX	segments；system；reload

wal_retrieve_retry_interval

Specifies how long (in milliseconds) the standby server should wait before retrying to retrieve WAL data when WAL data is unavailable from any source (stream replication, local pg_wal, or WAL archive).

This parameter is useful for configuring how long a node in recovery should wait for new WAL data to become available. For example, during archive recovery, reducing this parameter's value can make the recovery process more aggressively detect new WAL log files. On a system with low WAL activity, increasing this parameter's value can reduce the number of requests required to access the WAL archive. This is useful in environments such as cloud computing, where infrastructure access time is also a consideration.

Data type	Default value	Valid range	Setting category
int	5000	1 ~ INT_MAX	segments；system；reload

Subscribers

These parameters control the behavior of logical replication subscribers. Their values on the publisher are irrelevant.

Note!
The configuration parameters wal_receiver_timeout, wal_receiver_status_interval, and wal_retrieve_retry_interval also affect logical replication workers.

max_logical_replication_workers

Specify the maximum number of logical replication workers. This includes both application workers and table synchronization workers.

Logical replication workers are taken from the pool defined by max_worker_processes.

Data type	Default value	Value range	Setting category
int	4	0 ～ 262143	segments；system；restart

max_sync_workers_per_subscription

The maximum number of synchronous workers per subscription.

This parameter controls the parallelism of the initial data copy during subscription initialization or when a new table is added.
Currently, each table can only have one synchronous worker.
Synchronous workers are taken from the pool defined by max_logical_replication_workers.

数据类型	默认值	取值范围	设置分类
int	2	0 ～ 262143	segments；system；reload