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

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();

 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¶

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();

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;

Next Steps¶

• Learn more about configuration options
• Follow the complete tutorial
• Understand the architecture
• Learn about automatic replication

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