In this blog post, we will walk through the process of setting up PostgreSQL replication using Docker. Replication is a critical feature for ensuring high availability and fault tolerance in database systems. By the end of this guide, you will have a primary PostgreSQL instance and a replica instance running in Docker containers, with replication configured between them.

Prerequisites

Before we begin, make sure you have the following installed on your system:

🐳 Docker
🐙 Docker Compose (optional, but recommended for managing multi-container applications)

Step 1: Create Docker Network

First, we need to create a Docker network that will allow our PostgreSQL containers to communicate with each other.

docker network create pg-network

Step 2: Run PostgreSQL Containers

Next, we will run two PostgreSQL containers: one for the primary instance and one for the replica instance.

docker run -d --name pg-primary --network=pg-network -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres -v pg-primary-data:/var/lib/postgresql/data -p 5432:5432 postgres
docker run -d --name pg-replica --network=pg-network -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres -v pg-replica-data:/var/lib/postgresql/data -p 5433:5432 postgres

Step 3: Configure the Primary Instance

We need to configure the primary PostgreSQL instance to allow replication. This involves setting several parameters in the postgresql.conf file and updating the pg_hba.conf file to allow replication connections.

Access the Primary Container

docker exec -it pg-primary bash

Update postgresql.conf

echo "wal_level = replica" >> /var/lib/postgresql/data/postgresql.conf
echo "max_wal_senders = 3" >> /var/lib/postgresql/data/postgresql.conf
echo "wal_keep_size = 64MB" >> /var/lib/postgresql/data/postgresql.conf

Update pg_hba.conf

echo "host replication all 0.0.0.0/0 md5" >> /var/lib/postgresql/data/pg_hba.conf

Restart the Primary Container

docker restart pg-primary

Step 4: Configure the Replica Instance

Now, we need to configure the replica PostgreSQL instance to connect to the primary instance and start replication.

Access the Replica Container

docker exec -it pg-replica bash

Stop PostgreSQL Service

/usr/lib/postgresql/17/bin/pg_ctl stop -D /var/lib/postgresql/data

Remove Existing Data

rm -rf /var/lib/postgresql/data/*

Perform Base Backup

/usr/lib/postgresql/17/bin/pg_basebackup -h pg-primary -D /var/lib/postgresql/data -U postgres -v -P --wal-method=stream

Update postgresql.conf

echo "primary_conninfo = 'host=pg-primary port=5432 user=postgres password=postgres'" >> /var/lib/postgresql/data/postgresql.conf

Create Standby Signal File

touch /var/lib/postgresql/data/standby.signal

Start PostgreSQL Service

/usr/lib/postgresql/17/bin/pg_ctl start -D /var/lib/postgresql/data

Conclusion

Congratulations 🥳🥳! You have successfully set up PostgreSQL replication using Docker. The primary instance is now configured to allow replication, and the replica instance is set up to replicate data from the primary instance. This setup ensures that your data is replicated in real-time, providing high availability and fault tolerance for your PostgreSQL database.

By following these steps, you can easily scale your PostgreSQL deployment and ensure that your data is always available, even in the event of a failure. Happy coding!