---
title: "PostgreSQL Streaming Replication Setup"
description: "A comprehensive guide to configuring PostgreSQL streaming replication, including WAL shipping, replication slots, monitoring, and advanced settings"
keywords: ["postgresql", "replication", "streaming", "high availability", "disaster recovery"]
category: "databases"
---

To configure PostgreSQL streaming replication, you must first set up WAL (Write-Ahead Log) shipping from the primary to the standby server. In the postgresql.conf file on the primary, set wal_level to 'replica', max_wal_senders to the maximum number of concurrent standbys, and hot_standby to 'on'. On the standby, configure primary_conninfo with the connection details of the primary, and set hot_standby to 'on' as well.

Replication slots are used to ensure that the primary retains all the WAL segments required by the standby, even if the standby falls behind. On the primary, create a replication slot using the command CREATE_REPLICATION_SLOT. The standby will then automatically use this slot, ensuring that the required WAL segments are not prematurely removed.

To monitor the replication status, use the pg_stat_replication view on the primary. This will show the state of each connected standby, including the current replay location, write location, flush location, and the lag between the primary and standby. Pay attention to the differences between replay lag, write lag, and flush lag, as they can indicate potential performance issues.

The synchronous_commit setting controls how durable writes are on the primary. Setting it to 'on' ensures that transactions are not reported as committed until the WAL has been flushed to the standby, providing the highest level of durability but potentially impacting write performance. Setting it to 'off' or 'local' can improve write performance but reduces durability guarantees.

Cascading replicas are a common PostgreSQL replication topology, where a standby server can also serve as a primary for another standby. This allows for complex high availability and disaster recovery setups. To configure a cascading replica, simply set the primary_conninfo on the downstream standby to the connection details of the upstream standby.

The pg_basebackup command can be used to take a full backup of the primary database cluster, which can then be used to initialize a new standby server. This is often faster and more efficient than using file-level backups, especially for large databases. The recovery_target_timeline option can be used to specify which timeline the standby should recover to, in case of a failover scenario.Replication slots are a crucial feature for ensuring that the primary PostgreSQL server retains all the necessary Write-Ahead Log (WAL) segments required by the standby servers, even if a standby falls behind. When a replication slot is created on the primary using the CREATE_REPLICATION_SLOT command, the standby automatically uses this slot, preventing the premature removal of WAL segments that the standby may still need. This is particularly important in scenarios where the standby lags behind the primary due to network issues or high load, as it ensures that the standby can always catch up without losing data.

The pg_stat_replication view on the primary server provides valuable insights into the status of connected standby servers. This view displays information such as the current replay location, write location, flush location, and the lag between the primary and the standby. Understanding the differences between replay lag, write lag, and flush lag is important, as these metrics can help identify potential performance bottlenecks or replication issues. For example, a high replay lag may indicate that the standby is struggling to keep up with the primary, while a high write lag could suggest network latency or I/O issues on the standby.

Synchronous replication is a powerful feature in PostgreSQL that ensures the highest level of data durability. By setting the synchronous_commit parameter to 'on', transactions are not reported as committed on the primary until the WAL has been flushed to the standby server. This provides the strongest possible durability guarantees, but can also impact write performance on the primary. Alternatively, setting synchronous_commit to 'off' or 'local' can improve write performance, but reduces the durability guarantees, as transactions may be reported as committed before the WAL has been flushed to the standby.

Cascading replicas, where a standby server can also serve as a primary for another standby, are a common and highly flexible PostgreSQL replication topology. This allows for complex high availability and disaster recovery setups, where multiple layers of redundancy can be achieved. To configure a cascading replica, the primary_conninfo parameter on the downstream standby must be set to the connection details of the upstream standby.

The pg_basebackup command is a powerful tool for taking a full backup of the primary PostgreSQL database cluster, which can then be used to initialize a new standby server. This method is often faster and more efficient than using file-level backups, especially for large databases. The recovery_target_timeline option can be used to specify which timeline the standby should recover to, which is particularly useful in failover scenarios where the primary may have been promoted to a new timeline.When configuring PostgreSQL streaming replication, the recovery_target_timeline option is crucial for managing failover scenarios. This setting specifies the timeline that the standby server should recover to during the replay of the Write-Ahead Log (WAL) segments. In a typical failover scenario, where the primary server fails and a standby is promoted to become the new primary, the new primary will be on a different timeline than the old primary. By setting recovery_target_timeline to 'latest', the standby server can automatically recover to the latest timeline, ensuring a seamless transition and preventing data loss.

Monitoring the performance and health of a PostgreSQL streaming replication setup is essential for maintaining a robust and reliable system. The pg_stat_replication view provides a wealth of information, including the current replay location, write location, and flush location of each connected standby server. By analyzing the differences between these metrics, known as replay lag, write lag, and flush lag, administrators can identify potential performance bottlenecks or replication issues. For example, a high replay lag may indicate that the standby is struggling to keep up with the primary, while a high write lag could suggest network latency or I/O issues on the standby.

Cascading replicas, where a standby server can also serve as a primary for another standby, offer a highly flexible and scalable PostgreSQL replication topology. This allows for complex high availability and disaster recovery setups, where multiple layers of redundancy can be achieved. To configure a cascading replica, the primary_conninfo parameter on the downstream standby must be set to the connection details of the upstream standby. This enables the downstream standby to replicate from the upstream standby, creating a chain of replication that can be expanded as needed.

The pg_basebackup command is a powerful tool for taking a full backup of the primary PostgreSQL database cluster, which can then be used to initialize a new standby server. This method is often faster and more efficient than using file-level backups, especially for large databases, as it allows for the transfer of the entire data directory in a single operation. The --progress option can be used to monitor the progress of the backup, while the --max-rate option can be used to throttle the backup speed to avoid overwhelming the primary server.Replication slots are a crucial feature in PostgreSQL streaming replication, as they ensure that the primary server retains all the necessary Write-Ahead Log (WAL) segments required by the standby servers, even if a standby falls behind. When a replication slot is created on the primary using the CREATE_REPLICATION_SLOT command, the standby automatically uses this slot, preventing the premature removal of WAL segments that the standby may still need. This is particularly important in scenarios where the standby lags behind the primary due to network issues or high load, as it ensures that the standby can always catch up without losing data.

The synchronous_commit setting in PostgreSQL controls the level of durability guarantees for writes on the primary server. Setting synchronous_commit to 'on' ensures that transactions are not reported as committed until the WAL has been flushed to the standby, providing the highest level of durability but potentially impacting write performance. Conversely, setting synchronous_commit to 'off' or 'local' can improve write performance, but reduces the durability guarantees, as transactions may be reported as committed before the WAL has been flushed to the standby. Administrators must carefully consider the trade-offs between write performance and data durability when configuring this setting.

Cascading replicas, where a standby server can also serve as a primary for another standby, offer a highly flexible and scalable PostgreSQL replication topology. This allows for complex high availability and disaster recovery setups, where multiple layers of redundancy can be achieved. To configure a cascading replica, the primary_conninfo parameter on the downstream standby must be set to the connection details of the upstream standby, enabling the downstream standby to replicate from the upstream standby and creating a chain of replication that can be expanded as needed.

The pg_basebackup command is a powerful tool for taking a full backup of the primary PostgreSQL database cluster, which can then be used to initialize a new standby server. This method is often faster and more efficient than using file-level backups, especially for large databases, as it allows for the transfer of the entire data directory in a single operation. The --progress option can be used to monitor the progress of the backup, while the --max-rate option can be used to throttle the backup speed to avoid overwhelming the primary server. Additionally, the recovery_target_timeline option can be used to specify which timeline the standby should recover to, which is particularly useful in failover scenarios where the primary may have been promoted to a new timeline.