Getting Started

pgraft
Quick Start Guide

Get your first pgraft cluster up and running in minutes. pgraft is a production-ready PostgreSQL extension that embeds the Raft consensus protocol for automatic leader election, deterministic failover, and 100% split-brain protection.

InstallationQuick StartFull Tutorial

Installation

Install pgraft on your system with these simple steps

Prerequisites

  • PostgreSQL 16, 17, or 18
  • Go 1.21 or higher
  • GCC C compiler
  • PostgreSQL development headers

System Requirements

  • Minimum 2GB RAM per node
  • 10GB free disk space
  • Network connectivity between nodes
  • Linux, macOS, or Windows

Installation Steps

1. Install Dependencies

# Ubuntu/Debian (PostgreSQL 16-18)
sudo apt-get install postgresql-17 postgresql-server-dev-17 golang-go build-essential
# CentOS/RHEL/Rocky Linux
sudo yum install postgresql17 postgresql17-devel golang gcc make
# macOS
brew install postgresql@17 go

2. Clone and Build

# Clone the repository
git clone https://github.com/pgelephant/pgraft.git
cd pgraft
# Build the extension (includes Go compilation)
make clean && make

Note: The build process compiles both C and Go components, including the etcd-io/raft library integration.

3. Install Extension

sudo make install
# Verify installation
ls -la $(pg_config --libdir)/pgraft*
# Check Go library
ls -la $(pg_config --libdir)/pgraft_go.*

Quick Start

Get your first cluster running in 5 minutes

Step 1: Configure PostgreSQL

Add these settings to your postgresql.conf:

# Load pgraft extension
shared_preload_libraries = 'pgraft'
# Core cluster configuration (etcd-style)
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'
# Consensus settings (optional)
pgraft.election_timeout = 1000
pgraft.heartbeat_interval = 100
pgraft.snapshot_interval = 10000

Note: Each node needs a unique node_id and port.

Step 2: Initialize pgraft

Connect to PostgreSQL and create the extension:

# Create extension
CREATE EXTENSION pgraft;
# Initialize node
SELECT pgraft_init();

Step 3: Add Additional Nodes

Repeat steps 1-2 on other nodes, then add them to the cluster:

# Wait 10 seconds for leader election, then add nodes
SELECT pgraft_add_node(2, '127.0.0.1', 7002);
SELECT pgraft_add_node(3, '127.0.0.1', 7003);

Step 4: Verify Cluster Status

Check that your cluster is healthy and working properly:

# Get detailed cluster status
SELECT * FROM pgraft_get_cluster_status();
# Get all nodes in cluster
SELECT * FROM pgraft_get_nodes();
# Quick health check
SELECT pgraft_is_leader() as is_leader, pgraft_get_term() as term, pgraft_get_leader() as leader_id;
# Check worker status
SELECT pgraft_get_worker_state();
# Get log statistics
SELECT * FROM pgraft_log_get_stats();

The cluster should show one leader node and the worker should be running. Wait 10 seconds after initialization for leader election to complete.

What's Next?

Complete Tutorial

Follow our comprehensive tutorial to master pgraft cluster management.

SQL Functions

Explore the complete API reference for all pgraft SQL functions.

Architecture

Understand how pgraft works under the hood with detailed architecture docs.