What are the steps to set up a fault-tolerant PostgreSQL database using Patroni and etcd?

12 June 2024

In today's data-driven world, ensuring that your databases are fault-tolerant is crucial to maintain business continuity and data integrity. PostgreSQL, a powerful and open-source relational database system, can be made highly available and fault-tolerant using tools like Patroni and etcd. This article will guide you through the steps to set up a fault-tolerant PostgreSQL database using these technologies.

Understanding the Basics: PostgreSQL, Patroni, and etcd

Before diving into the setup process, it's essential to understand the key components involved in this architecture: PostgreSQL, Patroni, and etcd.

PostgreSQL: The Database

PostgreSQL is an open-source relational database management system known for its robustness, extensibility, and SQL compliance. It supports a wide range of data types and allows for complex queries and transactions.

Patroni: The High Availability Orchestrator

Patroni is an open-source tool for managing PostgreSQL clusters. It automates the failover process and ensures high availability by continuously monitoring the health of the database nodes. Patroni leverages etcd for distributed configuration and leader election.

etcd: The Configuration Store

etcd is a distributed key-value store used for shared configuration and service discovery. In our setup, etcd will be responsible for storing the cluster configuration and managing the leader election process, which is vital for maintaining a fault-tolerant PostgreSQL cluster.

Setting Up the Environment: Initial Steps

To set up a fault-tolerant PostgreSQL database, you need multiple servers or nodes. Each node will run PostgreSQL, Patroni, and etcd components. For demonstration purposes, we will assume a three-node cluster.

Step 1: Install PostgreSQL on Each Node

First, ensure that PostgreSQL is installed on each node. Use the following commands to install PostgreSQL:

sudo apt update
sudo apt install postgresql postgresql-contrib

Step 2: Install Patroni on Each Node

Next, install Patroni. Patroni can be installed using pip, the Python package manager:

sudo apt install python3-pip
sudo pip3 install patroni[etcd]

Step 3: Install and Configure etcd

Now, install etcd on each node. You can download etcd from the official repository or use your package manager:

sudo apt install etcd

Configure etcd by editing the /etc/default/etcd file. Ensure that the ETCD_INITIAL_CLUSTER variable includes the addresses of all nodes in your cluster. For example:


Start the etcd service:

sudo systemctl start etcd
sudo systemctl enable etcd

Configuring Patroni for High Availability

With PostgreSQL and etcd installed, the next step is to configure Patroni. Patroni requires a configuration file to manage the PostgreSQL cluster.

Step 4: Create the Patroni Configuration File

Create a configuration file for Patroni on each node, typically named patroni.yml. The configuration should include details about the cluster, etcd, and PostgreSQL settings. Below is an example configuration:

scope: postgres-cluster
namespace: /service/
name: node1



    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
      use_pg_rewind: true
      use_slots: true

  - encoding: UTF8
  - locale: en_US.UTF-8

      password: replicator_password
        - replication
        - superuser

  post_init: /path/to/post_init_script.sh

  data_dir: /var/lib/postgresql/data
  bin_dir: /usr/lib/postgresql/12/bin
      username: replicator
      password: replicator_password
      username: postgres
      password: postgres_password
    max_connections: 100
    shared_buffers: 128MB

Step 5: Start the Patroni Service

With the configuration file in place, start the Patroni service on each node:

sudo systemctl start patroni
sudo systemctl enable patroni

Setting Up Replication and Failover

Patroni will manage replication and failover automatically, but there are additional steps to ensure everything runs smoothly.

Step 6: Configure Streaming Replication

In the postgresql section of the patroni.yml file, ensure the replication settings are configured correctly. Patroni will use these settings to manage streaming replication between the nodes.

Step 7: Verify the Cluster Status

After starting Patroni on all nodes, verify the cluster status. You can use the Patroni REST API to check the status of the cluster:


This command will return detailed information about the cluster, including the current leader and any replicas.

Step 8: Testing Failover

To test failover, you can simulate a failure on the primary node and verify that Patroni promotes a replica to the primary role. Stop the Patroni service on the primary node:

sudo systemctl stop patroni

Monitor the cluster status to ensure that a new primary is elected.

Integrating HAProxy for Load Balancing

To distribute the database load and ensure high availability, you can integrate HAProxy as a load balancer.

Step 9: Install HAProxy

Install HAProxy on a separate server or on each database node:

sudo apt install haproxy

Step 10: Configure HAProxy

Edit the HAProxy configuration file, typically located at /etc/haproxy/haproxy.cfg, to include the PostgreSQL nodes. Below is an example configuration:

frontend postgresql_front
    bind *:5432
    mode tcp
    default_backend postgresql_back

backend postgresql_back
    mode tcp
    balance roundrobin
    option httpchk OPTIONS /master
    server node1 check port 8008
    server node2 check port 8008
    server node3 check port 8008

Start the HAProxy service:

sudo systemctl start haproxy
sudo systemctl enable haproxy

Step 11: Verify Load Balancing

Connect to the HAProxy address using a PostgreSQL client to ensure that the load is distributed among the nodes:

psql -h <haproxy_server_ip> -U postgres -d postgres

Maintaining and Monitoring Your PostgreSQL Cluster

Ongoing maintenance and monitoring are crucial for ensuring the high availability and performance of your PostgreSQL cluster.

Step 12: Regular Backups

Even with high availability, regular backups are essential. Use tools like pg_dump or continuous archiving methods to back up your data regularly.

Step 13: Monitor Cluster Health

Monitor the health of your PostgreSQL cluster using tools like pg_stat_activity and the Patroni REST API. Set up alerts for critical events, such as node failures or replication lag.

Step 14: Update and Patch

Regularly update PostgreSQL, Patroni, and etcd to the latest versions to benefit from new features and security patches. Test updates in a staging environment before applying them to production.

Setting up a fault-tolerant PostgreSQL database using Patroni and etcd involves a series of well-defined steps. By following this guide, you can create a highly available and resilient PostgreSQL cluster. The key components—PostgreSQL for the database, Patroni for high availability orchestration, and etcd for distributed configuration—work together to ensure your data is always available, even in the event of node failures. Integrating HAProxy as a load balancer further enhances the reliability and performance of your database service.

By diligently installing, configuring, and maintaining each of these components, you can achieve a robust, fault-tolerant PostgreSQL setup that meets the demands of modern, data-centric applications.

Copyright 2024. All Rights Reserved