pgraft Configuration

Baseline postgresql.conf Settings

Add these settings to postgresql.conf on every node. Adjust values to match your deployment size and performance goals.

# Load pgraft and enable WAL information for Raft replication
shared_preload_libraries = 'pgraft'
wal_level = logical
max_wal_senders = 16
max_replication_slots = 16
synchronous_commit = on

# Connection limits sized for Raft background workers
max_connections = 200
max_worker_processes = 32

# Recommended durability defaults
shared_buffers = 1GB
wal_keep_size = '4GB'

Restart PostgreSQL after updating shared_preload_libraries or WAL parameters.

pgraft GUC Parameters

GUC parameters can be defined in postgresql.conf or set dynamically with ALTER SYSTEM. At minimum, set the identity for each node.

# Unique identity per node
pgraft.cluster_id = 'production-cluster'
pgraft.node_id = 1
pgraft.address = '10.0.0.11'
pgraft.port = 7001

# Storage and snapshot configuration
pgraft.data_dir = '/var/lib/postgresql/pgraft'
pgraft.snapshot_interval = 10000
pgraft.snapshot_threshold = 5000

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

pg_hba.conf Access Control

Allow pgraft nodes to exchange Raft traffic and standard replication data. Apply these rules on every server.

# Local Raft + replication control connections
local   replication     postgres                                trust
host    replication     postgres        10.0.0.0/24             md5
host    all             pgraft_cluster  10.0.0.0/24             md5

Reload PostgreSQL after editing pg_hba.conf (SELECT pg_reload_conf();).

Runtime Configuration & Introspection

Tune pgraft on the fly and inspect the current Raft state without restarting the cluster.

-- Inspect the current configuration values
SELECT * FROM pgraft_get_config();

-- Change consensus timing at runtime
SELECT pgraft_set_config('heartbeat_interval', '50ms');
SELECT pgraft_set_config('election_timeout', '750ms');

-- Persist changes to disk
do $$
BEGIN
  PERFORM pgraft_set_config('snapshot_threshold', '8000');
  PERFORM pgraft_save_config();
END;
$$;

Cluster Management Commands

Use these SQL helpers to initialize, expand, and validate Raft clusters. Execute them from the elected leader node.

-- Bootstrap the leader after CREATE EXTENSION
dO $$ BEGIN PERFORM pgraft_init(); END $$;

-- Register follower nodes by ID, address, and Raft port
SELECT pgraft_add_node(2, '10.0.0.12', 7002);
SELECT pgraft_add_node(3, '10.0.0.13', 7003);

-- Remove a node gracefully
SELECT pgraft_remove_node(3);

-- Current leader, term, and quorum health
SELECT * FROM pgraft_get_cluster_status();

-- Per-node replication metrics and lag
SELECT * FROM pgraft_get_nodes();

-- Log, snapshot, and apply statistics
SELECT * FROM pgraft_log_get_stats();

Performance Profiles

Choose a profile matching your workload characteristics. Apply settings across all nodes to maintain symmetry.

pgraft.heartbeat_interval = 75
pgraft.election_timeout = 900
pgraft.append_batch_size = 1024
pgraft.replay_parallelism = 8
pgraft.snapshot_threshold = 12000

pgraft.heartbeat_interval = 40
pgraft.election_timeout = 400
pgraft.append_batch_size = 256
pgraft.replay_parallelism = 4
pgraft.snapshot_threshold = 6000

pgraft.heartbeat_interval = 150
pgraft.election_timeout = 1800
pgraft.append_batch_size = 512
pgraft.replay_parallelism = 6
pgraft.quorum_required = 3

Troubleshooting Configuration

Use these diagnostics when configuration issues arise.