pgraft — PostgreSQL Raft Consensus Extension (pgElephant Suite)¶

Unified High-Availability Suite¶

pgraft is part of the unified pgElephant high-availability suite, alongside RAM, RALE, and FauxDB. All product pages and documentation share a consistent, professional template and feature matrix.

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
• 100% split-brain prevention
• Zero-downtime failover
• Unified configuration and monitoring

Detailed Features List¶

• Raft Consensus Engine: Embedded etcd-io/raft for proven, production-grade consensus
• Automatic Leader Election: Quorum-based, deterministic, and fully automated
• Crash-Safe Log Replication: All state changes are replicated and persisted across nodes
• 100% Split-Brain Prevention: Mathematical guarantee—never more than one leader per term
• Zero-Downtime Failover: Seamless failover with sub-second detection and recovery
• Leader-Driven Cluster Management: Node addition/removal and configuration changes are always performed by the elected leader and automatically replicated
• Background Worker Architecture: PostgreSQL C background worker drives Raft ticks and state transitions
• Persistent Storage: HardState, log entries, and snapshots survive crashes and restarts
• Production-Ready Quality: 0 compilation errors/warnings, 100% PostgreSQL C standards compliant, and comprehensive test coverage
• Observability: Built-in monitoring functions, Prometheus metrics, and detailed logging
• Secure by Design: Follows PostgreSQL security best practices; supports SSL/TLS and role-based access
• Unified UI & Documentation: Consistent, professional product pages and documentation across the pgElephant suite

Quick Example¶

-- Create extension
CREATE EXTENSION pgraft;

-- Initialize node
SELECT pgraft_init();

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

-- If leader, add other nodes
SELECT pgraft_add_node(2, '127.0.0.1', 7002);
SELECT pgraft_add_node(3, '127.0.0.1', 7003);

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

Architecture at a Glance¶

PostgreSQL Background Worker (C)
    ↓ Every 100ms
pgraft_go_tick() [C→Go]
    ↓
raftNode.Tick() [etcd-io/raft]
    ↓
Ready() messages
    ↓
raftProcessingLoop() [Goroutine]
    ↓
Persist → Send → Apply → Advance

Why pgraft?¶

Split-Brain Protection¶

pgraft provides 100% split-brain protection through:

• Quorum Requirement: Leader needs majority votes (N/2 + 1)
• Term Monotonicity: Higher term always wins
• Log Completeness: Only up-to-date nodes can be elected
• Single Leader Per Term: Mathematical guarantee from Raft algorithm

Automatic Replication¶

When you add a node to the leader, it automatically appears on ALL other nodes. You only need to run ONE command on the leader. The Raft consensus protocol handles everything else.

Production Quality¶

• 0 compilation errors/warnings
• PostgreSQL C coding standards compliant
• All variables at function start (C89/C90)
• C-style comments only
• Tab indentation
• Production-ready error handling

Performance¶

• Tick Interval: 100ms (worker-driven)
• Election Timeout: 1000ms (default, configurable)
• Heartbeat: 100ms (default, configurable)
• Memory: ~50MB per node
• CPU: <1% idle, <5% during elections

Next Steps¶

Related Projects¶

• RAM — PostgreSQL clustering and failover manager
• RALE — Distributed consensus and key-value store
• FauxDB — MongoDB-compatible query proxy for PostgreSQL

License¶

MIT License - see LICENSE file for details.