High availability and disaster recovery capabilities are essential for any production-ready database system. PostgreSQL is reliable, but by itself it does not provide automatic failover, leader election, or cluster coordination. To achieve a fully automated DR environment, we can combine four mature open-source tools: Patroni, Etcd, HAProxy, and Docker.

This article explains how to build a three-node containerized PostgreSQL DR setup using these components. The architecture includes one primary PostgreSQL node, one replica node, and a third node dedicated to running Etcd and HAProxy. This design provides a simple but robust foundation for high availability, automatic failover, and transparent client routing.

Architecture Overview

The architecture consists of three separate servers (or virtual machines), each running containers for specific roles.

Node 1: Patroni + PostgreSQL (Primary)

This node runs:

• Patroni to manage PostgreSQL

• PostgreSQL data directory
  This node becomes the initial leader of the cluster during bootstrapping.

Node 2: Patroni + PostgreSQL (Replica)

This node runs:

• Patroni

• PostgreSQL as a hot standby replica
  It continuously receives WAL data from the primary node and stays ready to take over when required.

Node 3: Etcd + HAProxy

This is the control plane of the cluster. It runs:

• Etcd, which is used as the Distributed Configuration Store (DCS)

• HAProxy, which acts as a single routing endpoint for client connections

Node 3 does not store database data. Its responsibility is cluster coordination and routing.

Role of Each Component

Docker

Docker provides a clean, reproducible, and isolated runtime environment for each service. Because Patroni, Etcd, PostgreSQL, and HAProxy run inside containers, the setup is easy to deploy, rebuild, scale, or migrate.

Etcd

Etcd is a strongly consistent distributed key-value store. Patroni uses it to maintain cluster metadata, including:

• Leader lock (who is the primary)

• Health information of each node

• Failover coordination

• Heartbeat and status information

Etcd is central to ensuring that only one node acts as the primary at a time, which prevents data corruption.

Patroni

Patroni provides the automation layer for PostgreSQL high availability. It handles:

• Initial cluster bootstrap

• Leader election

• Replication configuration

• Automatic failover and promotion of replicas

• Continuous health monitoring

• Integration with Etcd

Patroni exposes a REST API on each node, allowing HAProxy to understand which node is currently the primary.

PostgreSQL

PostgreSQL runs inside each Patroni container. On the primary node it accepts read/write traffic, while the replica node uses streaming replication to continuously synchronize its data directory.

HAProxy

HAProxy acts as a reverse proxy and load balancer for PostgreSQL connections. Instead of pointing applications directly at a particular PostgreSQL server, all connections go through HAProxy. HAProxy uses Patroni’s REST API to determine which node is currently the primary and routes traffic accordingly. During failover, connections automatically shift to the new primary with no application-side configuration changes.

Cluster Workflow

The cluster operates as follows:

1. Etcd starts on Node 3 and listens on port 2379.

2. Patroni on Node 1 and Node 2 both connect to Etcd.

3. Patroni performs leader election. Node 1 becomes the primary, and Node 2 registers as a replica.

4. Patroni configures PostgreSQL streaming replication automatically.

5. HAProxy, also on Node 3.

6. All client connections are directed to HAProxy, which forwards the traffic to the current primary.

7. If Node 1 fails, Patroni promotes Node 2 to primary. Etcd records this change.

8. HAProxy begins routing traffic to Node 2 without requiring any manual intervention.

This results in a fully automated failover setup.

Step-by-Step Deployment

Below is a condensed version of how the cluster is deployed using Docker.

1. Create a Docker Network on Each Node

This ensures all containers can communicate using container names.

2. Deploy Etcd on Node 3

Create a directory and add the following docker-compose file:

Start Etcd:

Verify that Etcd is reachable:

3. Deploy Patroni + PostgreSQL on Node 1 (Primary)

Create a patroni-primary.yml configuration file:

Create a docker-compose file:

Start the container:

4. Deploy Patroni + PostgreSQL on Node 2 (Replica)

Create a patroni-replica.yml file similar to the primary, with the name updated:

Start Node 2:

5. Deploy HAProxy on Node 3

Create the HAProxy configuration file:

Run HAProxy:

Failover Testing

1. Confirm that Node 1 is the leader:

2. Stop Node 1:

Patroni on Node 2 will promote itself as the new primary. Etcd records the leadership change and HAProxy automatically reroutes traffic.

3. Restart Node 1:

Node 1 re-enters the cluster as a replica.

Conclusion

This three-node architecture delivers a fully automated PostgreSQL DR solution with transparent failover and a dedicated configuration and routing layer. By leveraging Patroni, Etcd, HAProxy, and Docker, the environment becomes both powerful and portable.

Lochan R