Step-by-step Guide to Setting up Streaming Replication in PostgreSQL


PostgreSQL is an open-source relational database management system that has been in use for over 30 years. It is widely regarded as one of the most powerful and versatile database systems available today, with features like support for ACID transactions, advanced indexing options, and extensibility through user-defined functions. PostgreSQL is also known for its stability and reliability, making it a popular choice for enterprise-level applications.

In data management, PostgreSQL plays a crucial role in providing efficient storage and retrieval of data. Organizations can store large amounts of structured and unstructured data in PostgreSQL databases.

With the ability to handle complex queries quickly on large datasets, it provides faster response times and better performance for analytical workloads. One key aspect of managing a PostgreSQL database is ensuring high availability.

This means ensuring that the database remains operational even in the face of hardware failures or other disruptions. One way to achieve this is by using streaming replication.

The Importance of Streaming Replication

Streaming replication allows you to create a copy (or replica) of your PostgreSQL database on another server, which can provide redundancy if something happens to your primary server. This replica can serve as a standby server that automatically takes over if the primary server fails.

The benefits of streaming replication extend beyond just high availability though – it can also be used for load balancing purposes or offloading read-only queries from your primary server to improve performance. The replication process works by continuously streaming changes made on the primary server to the standby server(s).

As soon as changes are committed on the primary, they are transmitted via network connections to standby servers which then apply them locally. This process ensures that all transactions committed on the primary server are eventually transferred and applied on all standby servers.

Streaming replication offers several benefits including high availability, load balancing and read scaling capabilities while providing protection against hardware failures or other disruptions. In this article we will provide step-by-step instructions on how to set up streaming replication in PostgreSQL, including prerequisites, installation and configuration of both primary and standby servers.


List of requirements for setting up streaming replication

To set up streaming replication in PostgreSQL, there are a few requirements that must be met. Firstly, both the primary and secondary servers must have at least version 9.0 or later of PostgreSQL installed. It is also recommended to use the same version of PostgreSQL on both servers to avoid compatibility issues.

Secondly, both servers must have the same configuration settings for certain parameters such as listen_addresses, port, max_wal_senders and wal_level. These parameters can be modified in the postgresql.conf file located in the data directory of each server.

Thirdly, there must be a physical network connection between the primary and secondary servers with enough bandwidth to transfer WAL (Write-Ahead Log) data from one server to another. The network connection should also be reliable with low latency and minimal packet loss.

It is important to have an understanding of how WAL works in PostgreSQL as it is crucial for setting up streaming replication correctly. WAL contains all changes made to a database so that they can be replayed on a secondary server thereby keeping it in sync with the primary server.

Explanation of each requirement

Having at least version 9.0 or later of PostgreSQL installed on both servers ensures that they support streaming replication which was introduced in version 9.0. Using the same version on both servers minimizes any compatibility issues that might arise during setup. Configuring certain settings such as listen_addresses and port ensures that both servers are listening on the same network interface and port respectively thereby allowing them to communicate with each other over a network connection.

The max_wal_senders parameter determines how many concurrent connections can replicate data from the primary server while wal_level determines what level of information is written to WAL files. Both parameters need careful consideration depending on your use case as they can impact performance and disk space usage.

Having a reliable network connection is essential for streaming replication to work correctly. A slow or unreliable network connection can lead to lag in replication or even complete failure of replication.

It is important to choose a network connection with enough bandwidth and low latency for optimal performance. A good understanding of how WAL works in PostgreSQL is vital for setting up streaming replication correctly.

WAL contains a continuous stream of changes made to a database which can be replayed on secondary servers thereby keeping them in sync with the primary server. Understanding the lifecycle of WAL files and how they are used during replication can help in troubleshooting any issues that may arise during setup and operation of streaming replication.

Setting up the Primary Server

Step-by-step guide to installing PostgreSQL on the primary server

Before we begin, it is important to ensure that the primary server meets all of the necessary prerequisites for setting up streaming replication. This includes installing a compatible version of PostgreSQL, configuring networking settings, and enabling firewall rules.

Once these requirements have been met, we can proceed to install PostgreSQL on the primary server. It is recommended to use a package manager such as apt or yum for easy installation and updates.

To install PostgreSQL using apt on Ubuntu 20.04, run the following command: “` sudo apt install postgresql “`

This will install the latest version of PostgreSQL available in the Ubuntu package repository. After installation, start and enable PostgreSQL to run at boot with these commands: “`

sudo systemctl start postgresql sudo systemctl enable postgresql “`

Configuration of the primary server for streaming replication

To configure the primary server for streaming replication, we must first modify its configuration file. The configuration file can be found at `/etc/postgresql/{version}/main/postgresql.conf`, where `{version}` is replaced by your installed version number.

Open this file in a text editor with root access and add or modify several lines: 1. Uncomment or add `listen_addresses = ‘*’` so that PostgreSQL can accept incoming connections from any IP address.

2. Add `wal_level = replica` to enable WAL (Write Ahead Logging) replication. 3. Add `archive_mode = on` so that completed WAL segments are archived.

4. Add `max_wal_senders = 10` to limit how many connections are allowed for replication. After making these changes, save and close the configuration file and restart PostgreSQL with: “`

sudo systemctl restart postgresql “` Your primary server has now been configured for streaming replication!

Setting up the Secondary Server

In order to set up streaming replication in PostgreSQL, it is necessary to have a primary server and at least one secondary server. The secondary server will replicate the data from the primary server, allowing for high availability and failover in case of issues with the primary.

Step-by-step guide to installing PostgreSQL on the secondary server

The first step in setting up a secondary server is to install PostgreSQL. This can be done using the same installation method as used for the primary server. Once installed, it is important to ensure that all required dependencies are also installed on the secondary server.

After installing PostgreSQL, create a new database cluster on the secondary server using initdb. This will create an empty database cluster with default configuration settings:

$ sudo su - postgres $ /usr/lib/postgresql/12/bin/initdb -D /var/lib/postgresql/12/main --auth-local=trust --auth-host=md5 

Configuration of the secondary server for streaming replication

The next step is to configure the secondary server for streaming replication. This involves creating a new replication slot on the primary server and configuring access to that slot from the secondary.

To create a new replication slot on the primary, connect to it using psql and run this command:

SELECT * FROM pg_create_physical_replication_slot('replica_slot_name'); 

This will create a new replication slot named “replica_slot_name”. To allow access from this newly created replica slot from our replica instance we need an IP address or subnet mask assigned to our master instance. Edit your pg_hba.conf on the primary instance and add this line:

host replication all IP_ADDRESS/32 md5

To configure streaming replication on the secondary server, create a new configuration file named “recovery.conf” in the PostgreSQL data directory. This file should contain the following information:

standby_mode = 'on' 

primary_conninfo = ‘host=PRIMARY_SERVER_IP port=5432 user=replicator password=password_here’ primary_slot_name = ‘replica_slot_name’

The “standby_mode” parameter tells PostgreSQL that this is a standby server, while “primary_conninfo” provides information about how to connect to the primary server for replication. The “primary_slot_name” parameter specifies which replication slot to use on the primary. Once configured, start the PostgreSQL service on the secondary server and it will begin replicating data from the primary.

Configuring Streaming Replication

Step-by-Step Guide to Configuring Streaming Replication between Primary and Secondary Servers

After completing the installation and configuration of PostgreSQL on both the primary and secondary servers, the next step is to configure streaming replication between them. The following is a step-by-step guide:

1. Create a backup of the primary database: Before we can configure streaming replication, we need to create a backup of the primary database that will serve as the starting point for replication on the secondary server. This can be done using either pg_basebackup or pg_dump.

2. Configure replication settings on the primary server: We have to modify some settings in our postgresql.conf file on our primary server to allow it to send WAL (Write Ahead Log) data over TCP/IP. 3. Modify pg_hba.conf: To enable incoming connections from our replica server, we need to modify our pg_hba.conf file.

Explanation of Different Methods for Configuring Replication

There are various methods for configuring streaming replication in PostgreSQL, including: 1. Asynchronous Streaming Replication: In this method, changes made on the primary are asynchronously streamed (sent) over TCP/IP connection(s) with one or more standby servers. 2. Synchronous Replication: In this mode, each transaction committed by a client waits until confirmation is received from at least one standby that it has received all WAL records up to and including those generated by that transaction.

3. cascading replication: Consists of multiple standby servers connected in a chain with each subsequent standby being connected directly or indirectly with its immediate upstream standby; therefore retrieving data from another downstream standby. Each method has its benefits and drawbacks, depending on your use case requirements.

Synchronous replication offers maximum data durability but can cause delays if network latency is high. Asynchronous replication provides better performance but might lead to data loss if the primary server fails before sending all changes.

Cascading replication can be useful in scenarios where the primary server is physically distant from multiple standbys and network bandwidth is limited. Whichever method you choose to configure streaming replication, it is recommended that you plan for load balancing, monitor your servers for consistency and performance issues, and have a well-designed backup and recovery plan in place in case of any failures.

Testing Replication

Testing replication is an essential step in the process of setting up streaming replication in PostgreSQL. You need to ensure that the data from the primary server is being replicated to the secondary server without any errors or inconsistencies. Here are some steps you can take to test if your replication is working correctly:

First, create a database on the primary server and add some sample data into it. Wait for a few minutes and then check if the data has been replicated to the secondary server by connecting to it using psql and running a SELECT query on the same table you inserted data into on the primary server.

Another way to test replication is by creating a temporary table on the primary server, adding some data into it, and then dropping it after a few minutes. If this action gets replicated onto your secondary server without any issues or errors, your streaming replication setup is working as expected.

Troubleshooting common issues with replication

Even after following all of these steps, you may still encounter problems with streaming replication. It’s essential to know how to troubleshoot these issues so that you can identify and fix them quickly.

One common issue that can occur during this process involves network latency between servers. In such cases, you may need to optimize your network settings further or adjust your configuration parameters within PostgreSQL.

Another problem that could arise from time-to-time concerns latency for larger databases where there are many updates per second. In this case, consider increasing shared buffers size as well as setting max_wal_size parameter values appropriately.

If nothing seems wrong with your setup but you’re still experiencing issues with data consistency across servers, consider double-checking firewall settings around ports used by PostgreSQL services (5432). There might be something blocking communication between both servers – such circumstances are rare but possible – protection software in place could be responsible for blocking port access too.


Testing and troubleshooting are necessary steps in setting up streaming replication for PostgreSQL. It’s important to ensure that data is being replicated across servers correctly and without errors. As long as you follow the steps outlined in this guide, you should be able to identify and resolve any issues that may arise during the replication process.

Monitoring Replication

Monitoring streaming replication is crucial to ensure that the data being replicated between the primary and secondary server is consistent and up-to-date. There are various tools available for monitoring replication status and performance. Here are some of the most commonly used tools:


pg_stat_replication is a PostgreSQL module that provides real-time statistics about streaming replication. It allows database administrators to monitor the status of each standby server, including its current state, delay, and lag time. The module also provides information about the amount of data transmitted between servers and can help identify issues in case of delays or data loss.

To use pg_stat_replication, you need to enable it in your PostgreSQL configuration file by setting the parameter “track_commit_timestamp” to on. Once enabled, you can use SQL queries to retrieve statistics from this module.

Replication Slots

Replication slots are a feature introduced in PostgreSQL 9.4 that allow for better management of streaming replication. A replication slot is a persistent point in the WAL stream where a standby server has confirmed receipt of all changes up to that point.

Using replication slots ensures that required data is retained on both servers even if either server goes down temporarily. If no more slots are available on the primary server, streaming replication will stop until an existing slot gets freed or a new one gets created.

Best practices for monitoring and maintaining a replicated environment

Maintaining a replicated environment requires proactive monitoring, proper planning, and good housekeeping practices to avoid potential issues caused by inconsistencies or performance bottlenecks. Here are some best practices for effectively maintaining replicated environments:

Monitor Replication Lag Time

One common issue with streaming replication is lag time between primary and secondary servers due to network latency or excessive load on the secondary server. It’s important to regularly monitor replication lag time to ensure that the secondary server is keeping up with the primary server. If there is a significant delay, it may be necessary to upgrade the hardware or make changes to network infrastructure and database configuration settings.

Test Failover

Testing failover scenarios is an important part of maintaining a replicated environment. In case of a primary server failure, standby servers should automatically take over without any data loss. To ensure this, it’s essential to test failover scenarios regularly.

You can simulate failures by intentionally shutting down the primary server and verifying that the standby servers take over as expected. This helps identify any issues with automated failover processes and ensures that your replicated environment is resilient in case of unexpected outages.

Regularly Clean Up Replication Slots

Replication slots are persistent objects that continue consuming disk space even after they are no longer needed. It’s important to regularly clean up unused replication slots to avoid excessive disk usage on both primary and secondary servers.

To clean up replication slots, identify slots that are no longer needed and use SQL queries to drop them. By following this best practice, you ensure efficient use of disk space while maintaining optimal performance for your replicated environment.


Throughout this guide, we have covered the step-by-step process of setting up streaming replication in PostgreSQL. By following these detailed instructions, you can ensure that your data is being replicated in real-time to a secondary server, providing an added layer of protection against data loss and ensuring high availability for your applications. As discussed in the previous sections, it is crucial to properly monitor and maintain your replication environment to ensure its continued success.

By regularly checking replication status and performance, as well as implementing best practices for database maintenance like routine backups and updates, you can avoid potential issues that could impact the availability or integrity of your data. Overall, setting up streaming replication in PostgreSQL can be a complex process but it is one that offers many benefits to businesses of all sizes.

With proper planning and execution, you can ensure that your data is always available when you need it and protected against potential disasters. We hope this guide has been helpful in getting you started on the path to building a reliable and high-performing replicated environment.

Related Articles