Documentationpgraft Documentation

Getting Started with pgraft

Requirements

Before installing pgraft, ensure you have:

  • PostgreSQL 16, 17, or 18 plus development headers
  • Go toolchain 1.21+ and standard build essentials (gcc/clang, make)
  • Network reachability between nodes for Raft replication traffic
  • systemd or process supervisor for production deployments

Install pgraft in 3 Steps

Embed the Raft consensus protocol inside PostgreSQL. Follow this guide to install pgraft, promote your first leader, and scale out a resilient cluster in minutes.

Step 1 · Install Build Dependencies

Install PostgreSQL server headers, the Go toolchain, and build essentials on your platform.

Install prerequisites

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install postgresql-18 postgresql-server-dev-18 golang-go build-essential

# RHEL / Rocky / AlmaLinux
sudo yum install postgresql18 postgresql18-devel golang gcc make

# macOS (Homebrew)
brew install postgresql@18 go

Step 2 · Build the Extension

Clone the official repository, compile the C and Go components, and install the shared library into PostgreSQL.

Build from source

git clone https://github.com/pgElephant/pgraft.git
cd pgraft
make clean && make
sudo make install

Step 3 · Enable pgraft in postgresql.conf

Load pgraft at startup and set the Raft identity for your first node.

postgresql.conf

shared_preload_libraries = 'pgraft'

# pgraft identity for node 1
pgraft.cluster_id = 'production-cluster'
pgraft.node_id = 1
pgraft.address = '127.0.0.1'
pgraft.port = 7001
pgraft.data_dir = '/var/lib/postgresql/pgraft'

# Optional consensus tuning
pgraft.election_timeout = 1000
pgraft.heartbeat_interval = 100
pgraft.snapshot_interval = 10000

Initialize the First Raft Node

Restart PostgreSQL to load the extension, then create the pgraft schema and bootstrap the node inside your primary database.

Initialize pgraft

-- Create the extension in your database
CREATE EXTENSION pgraft;

-- Bootstrap the local node (creates Raft metadata)
SELECT pgraft_init();

-- Confirm the worker is running and node is ready
SELECT pgraft_is_leader() AS is_leader,
       pgraft_get_term() AS current_term,
       pgraft_get_worker_state() AS worker_state;

The first node elects itself as leader within roughly 10 seconds. Additional nodes will join the cluster via the leader.

Scale Out the Cluster

Repeat installation on each follower, adjusting pgraft.node_id, pgraft.port, and data directories. Register followers from the leader once they are online and the extension is created.

Add follower nodes

-- Run on the leader node after followers are online
SELECT pgraft_add_node(2, '10.0.0.12', 7002);
SELECT pgraft_add_node(3, '10.0.0.13', 7003);

-- Review replication status and leader assignment
SELECT * FROM pgraft_get_cluster_status();
SELECT * FROM pgraft_get_nodes();

Verify Health & Operational Metrics

Use these diagnostics to confirm Raft health, replication progress, and quorum availability before production rollout.

Operational health checks

-- Leader / follower roles and commit positions
SELECT * FROM pgraft_get_cluster_status();

-- Detailed Raft log metrics (append, commit, snapshot counts)
SELECT * FROM pgraft_log_get_stats();

-- Verify quorum availability
SELECT pgraft_quorum_met() AS quorum_met,
       pgraft_get_leader() AS leader_node,
       pgraft_get_term() AS current_term;

Next Steps

NextInstallation