Quick Start (pgElephant Suite)¶

Get your first pgraft cluster up and running in minutes! All steps and health checks are up to date for the latest release and unified with the pgElephant suite.

Step 1: Configure PostgreSQL¶

Add these settings to your postgresql.conf:

shared_preload_libraries = 'pgraft'  # Core cluster configuration 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, these are defaults) pgraft.election_timeout = 1000 # milliseconds pgraft.heartbeat_interval = 100 # milliseconds pgraft.snapshot_interval = 10000 # entries pgraft.max_log_entries = 1000 # compaction threshold

Configuration Tips

node_id must be unique for each node (1, 2, 3, ...)
cluster_id must be the same for all nodes in the cluster
port is for Raft communication (not PostgreSQL port)

Step 2: Restart PostgreSQL¶

# Restart PostgreSQL to load the extension pg_ctl restart -D /path/to/data

Step 3: Initialize pgraft¶

Connect to PostgreSQL and create the extension:

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

Expected Output

 pgraft_init -------------  t (1 row)

Step 4: Set Up Additional Nodes¶

Repeat steps 1-3 on other nodes with different node_id values:

Node 2 (postgresql.conf):

pgraft.node_id = 2 pgraft.port = 7002

Node 3 (postgresql.conf):

pgraft.node_id = 3 pgraft.port = 7003

Step 5: Add Nodes to Cluster¶

Leader Only

Node addition must be performed only on the leader node.

Wait 10 seconds for leader election, then check which node is the leader:

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

On the leader node, add the other nodes:

SELECT pgraft_add_node(2, '127.0.0.1', 7002); SELECT pgraft_add_node(3, '127.0.0.1', 7003);

Step 6: Verify Cluster Status¶

On any node, check the cluster status:

-- Get cluster status SELECT * FROM pgraft_get_cluster_status();  -- Get all nodes SELECT * FROM pgraft_get_nodes();  -- Check worker status SELECT pgraft_get_worker_state();

Expected Output

SELECT * FROM pgraft_get_nodes();   node_id | address | port | is_leader  ---------+-------------+------+-----------  1 | 127.0.0.1 | 7001 | t  2 | 127.0.0.1 | 7002 | f  3 | 127.0.0.1 | 7003 | f (3 rows)

Quick Health Check¶

Run this query to quickly verify your cluster is healthy:

SELECT   pgraft_is_leader() as is_leader,  pgraft_get_term() as term,  pgraft_get_leader() as leader_id,  pgraft_get_worker_state() as worker;

Success

You now have a working pgraft cluster with automatic leader election and log replication!

Next Steps¶

Using the Test Harness¶

For testing and development, use the included test harness:

cd examples  # Destroy existing cluster ./run.sh --destroy  # Initialize new cluster ./run.sh --init  # Check status ./run.sh --status  # View logs tail -f logs/primary1/postgresql.log