Step-by-Step Guide to Setting Up a Highly Available PostgreSQL Cluster with Citus, Patroni, HAProxy, and etcd.

PostgreSQL is one of the popular relational database management systems. This article will guide you to deploy the PostgreSQL database server in a high-availability cluster that can handle any single point of failure in case one of the node is down.

Introduction: In this guide, we will walk you through the process of setting up a robust and scalable PostgreSQL cluster using Citus for sharding, Patroni for high availability, HAProxy for load balancing, and etcd for distributed coordination. This setup ensures fault tolerance and high performance for your database environment.


  • A Linux-based system with root access.
  • Familiarity with basic command-line operations.

Step 1: Installing Dependencies: Begin by installing the necessary dependencies. Open a terminal and run:

sudo apt-get update
sudo apt-get install -y build-essential libreadline-dev zlib1g-dev flex bison

These packages are required for building PostgreSQL and its extensions.

Step 2: Installing PostgreSQL: Download, compile, and install PostgreSQL:

tar xzf postgresql-15.3.tar.gz
cd postgresql-15.3
./configure --prefix=/usr/local/pgsql --with-openssl --with-libxml --with-libxslt --with-uuid=e2fs --with-system-tzdata=/usr/share/zoneinfo
sudo make install
echo "export PATH=/usr/local/pgsql/bin:\$PATH" >> ~/.bashrc
source ~/.bashrc

This sequence of commands downloads the PostgreSQL source code, compiles it with required options, installs it, and adds PostgreSQL’s bin directory to your PATH.

Step 3: Installing Citus Extension: Clone Citus repository and install the extension:

git clone
cd citus
git checkout 11.3.0
sudo PATH=$PATH:/usr/local/pgsql/bin make install

Citus provides horizontal scaling capabilities for PostgreSQL.

Step 4: Installing and Configuring etcd: Download etcd and start a single-node cluster:

tar xzf etcd-v3.5.0-linux-amd64.tar.gz
sudo mv etcd-v3.5.0-linux-amd64/etcd* /usr/local/bin/

# Start etcd

etcd enables distributed coordination among Patroni instances.

Step 5: Installing and Configuring Patroni: Install Patroni and create a configuration file patroni.yml:

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

# Create patroni.yml and configure nodes
nano patroni.yml

In the patroni.yml file, you’ll configure settings for each node, including their roles, credentials, and failover behavior. Refer to the previous responses for an example patroni.yml configuration.

Troubleshooting Tip: If you encounter issues with Patroni, ensure that etcd is up and running correctly. Check its logs and status to diagnose any problems.

Step 6: Installing and Configuring HAProxy: Install HAProxy and configure load balancing:

sudo apt-get install -y haproxy
sudo nano /etc/haproxy/haproxy.cfg

In the HAProxy configuration file haproxy.cfg, you’ll define how incoming connections are distributed across your PostgreSQL nodes. Refer to the previous responses for an example haproxy.cfg configuration.

Troubleshooting Tip: If you face connection issues, verify that HAProxy is correctly forwarding requests to PostgreSQL nodes. You can check HAProxy’s logs and status to identify problems.

Step 7: Testing the Setup: Connect to the PostgreSQL cluster using HAProxy’s IP and port:

psql -h <haproxy-ip> -p 5432 -U postgres

Perform basic database operations to verify the setup.

Conclusion: By following this comprehensive guide, you’ve successfully set up a highly available PostgreSQL cluster using Citus, Patroni, HAProxy, and etcd. This setup ensures fault tolerance and scalability for your database environment. Further, you can explore additional configuration options and security measures to enhance your setup.

Leave a Reply