Release History
Requirements

Introduction

Quick onboard

Deployment

Data Modeling

Connecting

Write data

Migration

Query

Operations and Maintenance

Performance Tuning

Troubleshooting

Reference Guide

SQL Reference

FAQ

Replication Category Parameters

This document describes the system configuration parameters in the Replication category.

Warning!
To ensure system stability and security, manually modifying these parameters should be done with caution.

These settings control the behavior of streaming replication. A server can act as either a primary (master) or standby. The primary server sends data, while the standby always acts as the receiver of replicated data. These parameters are primarily used on both sending servers and standby servers, although some are meaningful only on the master.


Sending Servers

The parameters in this section must be set on the Master and on any Standby that will send replication data.

max_replication_slots

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

  • This parameter can only be set at server startup.
  • 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 Range Category
int 10 1 ～ 262143 segments; system; restart

max_slot_wal_keep_size

Sets the maximum WAL size (in MB) that can be retained by replication slots.

  • If the WAL on disk occupies space equal to this parameter value, the replication slot will be marked as failed, and segments will be released for deletion or reuse.
  • The default value is -1, which disables this feature.
Data Type Default Value Range Category
int -1 -1 ～ INT_MAX/1024 segments; system; reload

max_wal_senders

Sets the maximum number of concurrent connections from standby servers or streaming base backup clients (i.e., the maximum number of WAL sender processes running simultaneously).

  • A value of 0 disables replication.
  • Sudden disconnections from streaming clients may leave behind isolated connection slots (until timeout), so this parameter should be set slightly higher than the maximum number of client connections to allow 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 master. Otherwise, queries will not be allowed on the standby.
Data Type Default Value Range Category
int 10 0 ～ 262143 segments; system; restart

track_commit_timestamp

Enables tracking of transaction commit timestamps.

Data Type Default Value Category
boolean off segments; system; restart

wal_init_zero

When set to on, fills new WAL files with zeros.

  • On some file systems, this ensures that file space is allocated before WAL records are written.
  • However, Copy-On-Write (COW) file systems may not benefit from this setting, so the parameter skips unnecessary work in such cases.
  • If set to off, only the last byte is written when the file is created, giving it the expected size.
Data Type Default Value Category
boolean on segments; session; reload; superuser

wal_keep_segments

Specifies the minimum number of past log file segments to retain in the pg_wal directory, in case a standby server needs them for streaming replication.

  • Each segment is typically 16 MB in size. If a connected standby falls more than wal_keep_segments segments behind, the sending server may remove a WAL segment still needed by the standby, breaking the replication connection. Eventually, the downstream connection will also fail (though if WAL archiving is used, the standby may recover by fetching segments from the archive).
  • This only sets the minimum number of file segments retained in pg_wal; the system may retain additional segments for WAL archiving or checkpoint recovery.
  • When this parameter is 0 (default), the system retains no extra segments for standby purposes. Thus, the number of old WAL segments available to the standby depends on the position of the last checkpoint and the WAL archiving status.
Data Type Default Value Range Category
int 64 0 ~ INT_MAX segments; system; reload

wal_recycle

Enables recycling of WAL files.

  • When set to on, WAL files are reused via renaming to avoid creating new files.
  • On COW file systems, creating new files may be faster, so this parameter is automatically disabled.
Data Type Default Value Category
boolean on segments; session; reload; superuser

wal_sender_timeout

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

  • This helps the sending server detect standby crashes or network interruptions.
  • A value of 0 disables the timeout.
  • For geographically distributed clusters, using different values per location provides greater flexibility in cluster management. Smaller values help detect failures faster for standbys with low-latency networks; larger values help better assess health for standbys with high-latency connections.
  • The default value is 300000毫秒, i.e., 5 minutes.
Data Type Default Value Range Category
int 300000 0 ～ INT_MAX segments; session; reload; superuser


Master Server

These settings are ignored on Standby servers.

Note!
In addition to these parameters, an appropriate wal_level must be set on the Master, and WAL archiving should be enabled as needed.


synchronous_standby_names

Specifies a list of standby servers that support synchronous replication.

  • One or more standby servers can be active. Once these standbys confirm receipt of data, waiting transactions are allowed to proceed.
  • A synchronous standby is a server whose name appears early in this list, is currently connected, and is streaming data in real time. Specifying multiple synchronous standbys enables high availability and prevents data loss.
  • The name used for this purpose is the application_name set in the connection information. List entries are separated by commas.
  • For physical replication standbys, this should be set in the primary_conninfo configuration. If not set, it defaults to cluster_name, otherwise walreceiver.
  • For logical replication, it can be set in the subscription's connection info. For other replication consumers, refer to their documentation.
  • The special entry '*' matches any standby name.

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

[FIRST] num_sync ( standby_name [, ...] )
ANY num_sync ( standby_name [, ...] )
standby_name [, ...]
  • Where num_sync is the number of synchronous standbys whose replies a transaction must wait for, and standby_name is a standby server name. FIRST and ANY specify how synchronous standbys are selected from the list.
  • The keyword FIRST with num_sync specifies priority-based synchronous replication. Transaction commits wait until WAL records are replicated to num_sync highest-priority standbys selected from the list. For example, FIRST 3 (s1, s2, s3, s4) causes each commit to wait for replies from three highest-priority standbys chosen from s1, s2, s3, and s4.
  • Standbys appearing earlier in the list have higher priority and are considered synchronous. Others are potential standbys. If a current synchronous standby disconnects, it is immediately replaced by the next highest-priority standby. The keyword FIRST is optional.
  • The keyword ANY with num_sync specifies quorum-based synchronous replication. Commits wait until WAL records are replicated to at least num_sync of the listed standbys. For example, ANY 3 (s1, s2, s3, s4) allows a commit to proceed after receiving replies from any three of s1, s2, s3, and s4.
  • FIRST and ANY are case-insensitive. If used as standby names, they must be enclosed in double quotes.
  • The third syntax is equivalent to the first syntax with FIRST and num_sync equal to 1. For example, FIRST 1 (s1, s2) means the same as s1, s2: either s1 or s2 will be selected as the synchronous standby.
  • No mechanism enforces standby name uniqueness. If duplicates exist, one matching standby will be treated as higher priority, but it is indeterminate which one.
  • Note: Each standby_name should be a valid SQL identifier unless it is *. Double quotes may be used if necessary. However, comparison of standby_name and standby application names is case-insensitive (regardless of quoting).
  • If no standby names are specified, synchronous replication cannot be enabled, and transaction commits will not wait for replication. This is the default. Even when synchronous replication is enabled, individual transactions can be configured not to wait by setting the synchronous_commit parameter to local or off.
Data Type Default Value Category
string segments; system; reload

vacuum_defer_cleanup_age

Specifies how long (in number of transactions) updates to VACUUM and HOT should defer cleanup of dead row versions.

  • The default is 0 transactions, meaning dead rows are cleaned up as quickly as possible—once they are no longer visible to any open transaction.
  • On a master supporting hot standby, you may want to set this to a non-zero value, allowing more time for queries on the standby to complete without conflicts due to earlier row cleanup. However, since this value is measured in write transactions on the master, it is difficult to predict the exact additional time available for standby queries.
  • You may also consider setting hot_standby_feedback on the standby as an alternative.
  • This does not prevent cleanup of rows that have reached the age specified by old_snapshot_threshold.
Data Type Default Value Range Category
int 0 0 ～ 1000000 segments; system; reload


Standby Servers

These settings are ignored on the Master server.

hot_standby

Specifies whether connections and queries can be run during recovery.

  • This parameter can only be set at server startup.
  • It is effective only during archive recovery or standby mode.
Data Type Default Value Category
boolean off segments; system; restart

hot_standby_feedback

Specifies whether a hot standby sends feedback to the master or upstream standby about currently executing queries on the standby.

  • This can help avoid query cancellations due to vacuuming, but may cause database bloat on the master under certain workloads.
  • Feedback messages are sent no more frequently than once per wal_receiver_status_interval cycle.
  • In cascaded replication, feedback is passed upstream until it reaches the master. Standbys only forward feedback and take no other action upon receipt.
  • This setting does not override old_snapshot_threshold behavior on the master. A snapshot on the standby exceeding the master's age threshold may become invalid, causing transaction cancellation on the standby. This is because old_snapshot_threshold imposes an absolute limit on how long dead rows can persist, preventing disruption due to standby configuration.
Data Type Default Value Category
boolean off segments; system; reload

max_standby_archive_delay

When hot standby is active, this parameter sets the maximum time (in milliseconds) the standby waits before canceling queries that conflict with WAL entries about to be applied. See Handling Query Conflicts.

  • -1 applies when WAL data is being read from WAL archives (and thus not current WAL).
  • If no unit is specified, the value is in milliseconds.
  • A value of max_standby_archive_delay allows the standby to wait indefinitely until the conflicting query ends.
  • Note: max_standby_streaming_delay is not the maximum time a single query can run before cancellation; it is the maximum total time allowed to apply any WAL segment. Thus, if an early query causes significant delay, subsequent conflicting queries will have less time.
Data Type Default Value Range Category
int 30000 -1 ～ INT_MAX segments; system; reload

max_standby_streaming_delay

When hot standby is active, this parameter sets the maximum time (in milliseconds) the standby waits before canceling queries that conflict with WAL entries about to be applied. See Handling Query Conflicts.

  • max_standby_streaming_delay applies when WAL data is received via streaming replication.
  • If no unit is specified, the value is in milliseconds.
  • A value of -1 allows the standby to wait indefinitely until the conflicting query ends.
  • Note: This parameter is not the maximum time a single query can run before cancellation; it is the maximum total time allowed between receiving WAL data from the master and applying it. If a query causes significant delay, subsequent conflicting queries will have less time until the standby catches up.
Data Type Default Value Range Category
int 30000 -1 ～ INT_MAX segments; system; reload

primary_conninfo

Specifies the connection string used by the standby to connect to the sending server.

  • If any option is not specified in the string, the corresponding environment variable is checked. If the environment variable is also unset, the default value is used.
  • The connection string should specify the host (or address) and port (if different from the standby's default) of the sending server, and a username corresponding to a role with appropriate privileges on the sending server.
  • If the sending server requires password authentication, the password must also be provided. It can be included in the primary_conninfo string or in a separate ~/.pgpass file on the standby (using replication as the database name).
  • Do not specify a database name in the primary_conninfo string.
  • This parameter can only be set at server startup. It has no effect if the server is not in standby mode.
Data Type Default Value Category
string segments; system; restart; superuser

primary_slot_name

Optionally specifies an existing replication slot to use when connecting via streaming replication, to control resource removal on the upstream node.

  • This parameter can only be set at server startup.
  • This setting has no effect if primary_conninfo is not set.
Data Type Default Value Category
string segments; system; restart

promote_trigger_file

Specifies a trigger file whose existence ends recovery on the standby.

  • Even without this value set, you can promote the standby using pg_ctl promote or by calling pg_promote.
Data Type Default Value Category
string segments; system; reload

recovery_min_apply_delay

By default, the standby applies WAL records from the sending server as quickly as possible.

  • A delayed copy of data can be useful to correct data loss errors. This parameter allows the system to delay recovery by the specified amount. For example, setting this parameter to 5min means a transaction will only be replayed on the standby when the system clock on the standby is at least 5 minutes past the commit time reported by the master.
  • If no unit is specified, the value is in milliseconds.
  • Replication delay between servers may exceed this parameter's value, in which case no additional delay is added. Note: Delay is calculated based on the timestamp when WAL was written on the master and the current time on the standby. Network or cascading replication delays may significantly reduce the actual wait time.
  • If system clocks on master and standby are not synchronized, recovery may apply records earlier than expected. However, this is not a major issue, as the benefit of this parameter setting is typically much larger than inter-server time skew.
  • Delay is applied only to WAL records for transaction commits. Other records are replayed as quickly as possible. This is safe because MVCC visibility rules ensure their effects are not visible until the corresponding commit record is applied.
  • Delay is enforced once the recovering database reaches a consistent state, and continues until the standby is promoted or triggered. After that, recovery ends and no further delay occurs.
  • Note: This parameter is intended for use with streaming replication. However, if set, it applies in all cases except crash recovery. Using this feature also delays hot_standby_feedback, potentially causing master bloat—use with caution when both are enabled.
  • The default value is 0, meaning no delay is added.

Note!
When synchronous_commit is set to remote_apply, synchronous replication is affected—each COMMIT must wait for the delay to elapse before applying.

Data Type Default Value Range Category
int 0 0 ～ INT_MAX segments; system; reload

wal_receiver_status_interval

Sets the minimum frequency (in seconds) at which the WAL receiver process on the standby sends status information about replication progress to the master or upstream standby.

  • The standby reports the last WAL position written, flushed to disk, and applied.
  • This parameter sets the maximum time between status reports. Status updates are sent whenever the write or flush position changes, or at least as frequently as this parameter specifies. Thus, the applied position may lag slightly behind reality.
  • Setting this parameter to 0 disables status updates entirely.
Data Type Default Value Range Category
int 10 0 ~ INT_MAX/1000 segments; system; reload

wal_receiver_timeout

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

  • This helps the receiving standby detect master crashes or network disconnections.
  • If no unit is specified, the value is in milliseconds.
  • A value of 0 disables the timeout.
Data Type Default Value Range Category
int 60000 0 ～ INT_MAX segments; system; reload

wal_retrieve_retry_interval

Specifies how long (in milliseconds) a standby should wait before retrying to fetch WAL data when no data is available from any source (streaming replication, local pg_wal, or WAL archive).

  • This parameter helps configure how long a recovering node waits for new WAL data. For example, in archive recovery, reducing this value makes recovery more aggressive in detecting new WAL files. On systems with low WAL activity, increasing this value reduces the number of requests to the WAL archive, which is useful in environments like the cloud where infrastructure access timing matters.
Data Type Default Value Range 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

Sets the maximum number of logical replication workers. This includes both apply workers and table synchronization workers.

  • Logical replication workers are drawn from the pool defined by max_worker_processes.
Data Type Default Value Range Category
int 4 0 ～ 262143 segments; system; restart

max_sync_workers_per_subscription

Sets the maximum number of synchronization workers per subscription.

  • This parameter controls the parallelism of initial data copy during subscription initialization or when adding new tables.
  • Currently, only one sync worker is allowed per table.
  • Sync workers are drawn from the pool defined by max_logical_replication_workers.
Data Type Default Value Range Category
int 2 0 ～ 262143 segments; system; reload
← Previous
Write-Ahead log
Next →
PL/JAVA