pgraft — PostgreSQL Raft Consensus Extension

Production-ready Raft consensus for distributed PostgreSQL clusters

📚 Documentation • 🚀 Quick Start • 📦 Releases • 💬 Discussions

Overview

pgraft is a PostgreSQL extension that implements the Raft consensus algorithm for distributed PostgreSQL clusters. It provides automatic leader election, crash-safe log replication, and 100% split-brain prevention.

Key Features

✅ Automatic Leader Election — Quorum-based, deterministic, fully automated
✅ Crash-Safe Replication — All state changes replicated and persisted across nodes
✅ 100% Split-Brain Prevention — Mathematical guarantee via Raft consensus protocol
✅ Zero-Downtime Failover — Sub-second detection and automatic recovery
✅ Production-Grade Raft — Built on proven etcd-io/raft library
✅ Native PostgreSQL Integration — Background worker architecture, no external dependencies
✅ Comprehensive SQL API — Full cluster management via SQL functions
✅ Built-in Observability — Status functions, metrics, and detailed logging
✅ etcd-Compatible KV Store — Raft-replicated key-value storage included

Supported Platforms

Platform	PostgreSQL Versions	Status
Linux (RHEL/Rocky/AlmaLinux)	14, 15, 16, 17	✅ Supported
Linux (Ubuntu/Debian)	14, 15, 16, 17	✅ Supported
macOS	14, 15, 16, 17	✅ Supported

Quick Start

Installation

From Source

# Prerequisites: PostgreSQL 14+, Go 1.15+, json-c
git clone https://github.com/pgelephant/pgraft.git
cd pgraft
make
sudo make install

Pre-built Packages

Download from Releases:

RPM (RHEL/Rocky/AlmaLinux):

sudo dnf install pgraft_17-1.0.0-1.el9.x86_64.rpm

DEB (Ubuntu/Debian):

sudo apt install ./postgresql-17-pgraft_1.0.0-1_amd64.deb

📖 Complete Installation Guide →

Configuration

Add to postgresql.conf on each node:

shared_preload_libraries = 'pgraft'

# Cluster identification and networking
pgraft.name = 'node1'                    # Unique node name
pgraft.listen_address = '0.0.0.0:7001'   # Raft communication port
pgraft.initial_cluster = 'node1=10.0.1.11:7001,node2=10.0.1.12:7002,node3=10.0.1.13:7003'

# Storage
pgraft.data_dir = '/var/lib/postgresql/pgraft'

# Consensus settings (optional)
pgraft.election_timeout = 1000           # milliseconds
pgraft.heartbeat_interval = 100          # milliseconds

Important:

pgraft.name must be unique and match a name in initial_cluster
pgraft.initial_cluster must be identical on all nodes
Node IDs are automatically assigned based on position in initial_cluster

Restart PostgreSQL after configuration changes.

📖 Configuration Reference →

Initialize Cluster

On each node:

-- Create extension (automatically initializes from postgresql.conf)
CREATE EXTENSION pgraft;

-- Check cluster status
SELECT * FROM pgraft_get_cluster_status();

-- View all nodes
SELECT * FROM pgraft_get_nodes();

The cluster automatically forms based on the initial_cluster configuration!

🚀 Quick Start Guide →

Usage Examples

Check Cluster Status

-- Check if current node is the leader
SELECT pgraft_is_leader();

-- Get current leader ID
SELECT pgraft_get_leader();

-- Full cluster status
SELECT * FROM pgraft_get_cluster_status();

-- List all nodes
SELECT * FROM pgraft_get_nodes();

Monitor Health

-- Quick health check
SELECT 
    node_id,
    state,
    leader_id,
    current_term,
    num_nodes
FROM pgraft_get_cluster_status();

-- Check log replication status
SELECT * FROM pgraft_log_get_replication_status();

-- Get log statistics
SELECT * FROM pgraft_log_get_stats();

Key-Value Store (etcd-compatible)

-- Store configuration (must run on leader)
SELECT pgraft_kv_put('app/config', '{"timeout":30,"retries":3}');

-- Retrieve configuration (works on any node)
SELECT pgraft_kv_get('app/config');

-- List all keys
SELECT pgraft_kv_list_keys();

-- Delete key (must run on leader)
SELECT pgraft_kv_delete('app/config');

Dynamic Node Management

-- Add a node (must run on leader)
SELECT pgraft_add_node(4, '10.0.1.14', 7004);

-- Remove a node (must run on leader)
SELECT pgraft_remove_node(4);

-- Check if operation is allowed
DO $$
BEGIN
    IF NOT pgraft_is_leader() THEN
        RAISE EXCEPTION 'Must run on leader node';
    END IF;
    PERFORM pgraft_add_node(4, '10.0.1.14', 7004);
END $$;

📖 SQL Functions Reference →

Architecture

PostgreSQL Process
│
├─ Background Worker (C)
│  └─ Tick every 100ms
│     └─ pgraft_go_tick()
│        └─ Go Raft Engine (etcd-io/raft)
│           ├─ Leader Election
│           ├─ Log Replication
│           ├─ Persistent Storage
│           └─ Network Communication
│
└─ SQL API (C)
   ├─ Cluster Management Functions
   ├─ Status & Monitoring Functions
   ├─ Key-Value Store Functions
   └─ Log Replication Functions

Components

Component	Description
C Layer	PostgreSQL integration, SQL functions, background worker
Go Layer	Raft consensus engine using etcd-io/raft library
Storage	Persistent logs, snapshots, HardState on disk
Network	TCP server for inter-node Raft communication

How It Works

Background Worker ticks every 100ms, driving Raft state machine
Go Raft Engine handles leader election, log replication, and consensus
Persistent Storage ensures crash safety with durable logs and snapshots
SQL Functions provide management API accessible via standard SQL

📐 Architecture Details → 🛡️ Split-Brain Protection →

Docker Quick Start

The pgraft_cluster.py script provides an easy way to test pgraft:

cd examples

# Start 3-node cluster (1 primary + 2 replicas)
./pgraft_cluster.py --docker --init --nodes 3

# Check status
./pgraft_cluster.py --docker --status

# Destroy cluster
./pgraft_cluster.py --docker --destroy

🐳 Docker Cluster Guide →

Documentation

Getting Started

Installation — Install pgraft on your system
Quick Start — Get running in 5 minutes

User Guide

Configuration — Complete GUC parameter reference
SQL Functions — All SQL functions and tables
Cluster Operations — Add/remove nodes, failover
Tutorial — Step-by-step complete guide
Docker Cluster Script — Test with Docker

Core Concepts

Architecture — How pgraft works internally
Automatic Replication — Raft log replication explained
Split-Brain Protection — Consensus guarantees

Operations

Monitoring — Health checks and metrics
Troubleshooting — Common issues and solutions
Best Practices — Production deployment guide

Development

Building from Source — Developer setup
Testing — Test suite and procedures
Contributing — How to contribute

📚 View All Documentation →

Performance Characteristics

Metric	Value	Notes
Tick Interval	100ms	Background worker execution frequency
Election Timeout	1000ms	Default, configurable (500-3000ms recommended)
Heartbeat Interval	100ms	Default, configurable (50-500ms recommended)
Memory per Node	~50MB	Includes Go runtime and Raft state
CPU (Idle)	<1%	Background worker overhead
CPU (Election)	<5%	During leader election
Network Overhead	~1KB/s	Heartbeats and small messages
Failover Time	1-3s	Election timeout + detection

Production Deployment

System Requirements

Minimum (Testing):

CPU: 2 cores
RAM: 2GB per node
Disk: 10GB
Network: 100 Mbps

Recommended (Production):

CPU: 4+ cores
RAM: 8GB+ per node
Disk: 50GB+ SSD
Network: 1 Gbps+ with <10ms latency

Best Practices

Odd Number of Nodes: Always use 3, 5, or 7 nodes for optimal quorum
Network Latency: Keep inter-node latency <10ms for best performance
Separate Networks: Use dedicated network for Raft communication
Monitoring: Set up alerts for leader changes and replication lag
Backups: Regular PostgreSQL backups in addition to Raft logs
Testing: Test failover scenarios before production deployment

📖 Best Practices Guide →

Troubleshooting

Common Issues

Background worker not starting:

-- Check if pgraft is loaded
SHOW shared_preload_libraries;

-- Must include 'pgraft' and require PostgreSQL restart

No leader elected:

# Wait 10 seconds after creating extension
sleep 10

# Check leader status
psql -c "SELECT pgraft_get_leader(), pgraft_is_leader();"

Node cannot join cluster:

-- Verify configuration
SELECT name, setting FROM pg_settings WHERE name LIKE 'pgraft.%';

-- Check pgraft.initial_cluster matches on all nodes

High CPU usage:

-- Check if too many elections
SELECT elections_triggered FROM pgraft_get_cluster_status();

-- Increase election_timeout if needed

⚠️ Full Troubleshooting Guide →

Building from Source

Prerequisites

Ubuntu/Debian:

sudo apt update
sudo apt install build-essential postgresql-server-dev-17 golang-go \
                 libjson-c-dev pkg-config git

RHEL/Rocky/AlmaLinux:

sudo dnf install gcc make postgresql17-devel golang json-c-devel \
                 pkg-config git

macOS:

brew install postgresql@17 go json-c pkg-config

Compile & Install

# Clone repository
git clone https://github.com/pgelephant/pgraft.git
cd pgraft

# Build
make clean
make

# Install (requires sudo)
sudo make install

Build for Specific PostgreSQL Version

# PostgreSQL 16
make PG_CONFIG=/usr/pgsql-16/bin/pg_config

# PostgreSQL 17
make PG_CONFIG=/usr/local/pgsql.17/bin/pg_config

🛠️ Development Guide →

Contributing

We welcome contributions from the community! Whether it's:

🐛 Bug reports
💡 Feature requests
📝 Documentation improvements
🔧 Code contributions

How to Contribute

Check existing issues — See if your idea/bug is already discussed
Open an issue — Describe the problem or enhancement
Fork & develop — Make your changes in a feature branch
Submit PR — Include tests and documentation updates
Code review — Collaborate with maintainers

📝 Contributing Guidelines →

Quick Links

Testing

# Run regression tests
make installcheck

# Run Docker cluster test
cd examples
./pgraft_cluster.py --docker --init --nodes 3

🧪 Testing Guide →

Project Status

Current Version: 1.0.0
Status: ✅ Production Ready

Quality Standards

✅ Zero compilation errors/warnings
✅ 100% PostgreSQL C coding standards compliant
✅ C89/C90 compatible (variables at function start)
✅ Comprehensive error handling
✅ Complete test coverage
✅ Full documentation
✅ Multi-platform support (Linux, macOS)
✅ Multi-version support (PostgreSQL 14-17)

Roadmap

Technology Stack

Component	Technology
Core Language	C (PostgreSQL extension)
Consensus Engine	Go (etcd-io/raft)
Build System	PostgreSQL PGXS, GNU Make
JSON Parsing	json-c library
Documentation	MkDocs with Material theme
CI/CD	GitHub Actions
Packaging	RPM (RHEL/Rocky), DEB (Ubuntu/Debian)

Related Projects

etcd-io/raft — Raft consensus algorithm implementation (used by pgraft)
PostgreSQL — The world's most advanced open source database
Patroni — HA solution for PostgreSQL (complementary to pgraft)
Stolon — PostgreSQL cloud native HA replication manager

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See LICENSE file for full text.

Support

Community Support

Documentation: https://pgelephant.github.io/pgraft/
GitHub Issues: Report bugs or request features
GitHub Discussions: Ask questions and share ideas

Professional Support

For enterprise support, custom development, or consulting services, please contact the maintainers.

Acknowledgments

PostgreSQL Community — For the amazing database system
etcd-io/raft — For the production-grade Raft implementation
Contributors — Everyone who has contributed code, documentation, or feedback

Made with ❤️ for the PostgreSQL community

⭐ Star us on GitHub • 📚 Read the Docs • 💬 Join Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github		.github
docs		docs
examples		examples
include		include
packaging		packaging
src		src
.gitignore		.gitignore
AUTHORS		AUTHORS
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
Makefile.macos		Makefile.macos
Makefile.rocky		Makefile.rocky
Makefile.ubuntu		Makefile.ubuntu
README.md		README.md
SECURITY.md		SECURITY.md
docs-requirements.txt		docs-requirements.txt
go.sum		go.sum
mkdocs.yml		mkdocs.yml
pgraft--1.0.sql		pgraft--1.0.sql
pgraft.control		pgraft.control

Uh oh!

License

Uh oh!

pgElephant/pgraft

Folders and files

Latest commit

History

Repository files navigation

pgraft — PostgreSQL Raft Consensus Extension

Overview

Key Features

Supported Platforms

Quick Start

Installation

From Source

Pre-built Packages

Configuration

Initialize Cluster

Usage Examples

Check Cluster Status

Monitor Health

Key-Value Store (etcd-compatible)

Dynamic Node Management

Architecture

Components

How It Works

Docker Quick Start

Documentation

Getting Started

User Guide

Core Concepts

Operations

Development

Performance Characteristics

Production Deployment

System Requirements

Best Practices

Troubleshooting

Common Issues

Building from Source

Prerequisites

Compile & Install

Build for Specific PostgreSQL Version

Contributing

How to Contribute

Quick Links

Testing

Project Status

Quality Standards

Roadmap

Technology Stack

Related Projects

License

Support

Community Support

Professional Support

Acknowledgments

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages