pgraft SQL Functions

Complete reference for all pgraft SQL functions. pgraft provides a comprehensive set of functions for cluster management, leader election, log operations, and monitoring.

Core Initialization Functions

pgraft_init() → boolean

Initialize the pgraft node using GUC configuration variables. Must be called after CREATE EXTENSION.

SELECT pgraft_init();
-- Returns: true on success, false on failure
-- Uses: pgraft.cluster_id, pgraft.node_id, pgraft.address, pgraft.port, etc.

pgraft_init_guc(cluster_id, node_id, address, port) → boolean

Initialize pgraft with explicit parameters instead of GUC variables.

SELECT pgraft_init_guc('prod-cluster', 1, '127.0.0.1', 7001);

pgraft_get_version() → text

Get the current pgraft version information.

SELECT pgraft_get_version();
-- Returns: "pgraft 1.0.0"

Cluster Management Functions

pgraft_add_node(node_id int, address text, port int) → boolean

Add a new node to the cluster. Must be called on the leader node.

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

pgraft_remove_node(node_id int) → boolean

Remove a node from the cluster. Must be called on the leader node.

SELECT pgraft_remove_node(3);

pgraft_get_cluster_status() → TABLE(...)

Get comprehensive cluster status information including all nodes.

SELECT * FROM pgraft_get_cluster_status();
-- Returns: node_id, address, port, is_leader, term, state

pgraft_get_nodes() → TABLE(node_id, address, port, is_leader)

Get information about all nodes in the cluster.

SELECT * FROM pgraft_get_nodes();

Leadership Functions

pgraft_is_leader() → boolean

Check if the current node is the cluster leader.

SELECT pgraft_is_leader();
-- Returns: true if current node is leader, false otherwise

pgraft_get_leader() → bigint

Get the ID of the current cluster leader.

SELECT pgraft_get_leader();
-- Returns: leader node ID, or 0 if no leader

pgraft_get_term() → bigint

Get the current Raft term number.

SELECT pgraft_get_term();
-- Returns: current term number

Log Operations

pgraft_log_append(data text) → boolean

Append a new entry to the Raft log. Only works on leader.

SELECT pgraft_log_append('"user_created"');
-- Returns: true on success

pgraft_log_commit(log_index int) → boolean

Commit a log entry at the specified index.

SELECT pgraft_log_commit(1);

pgraft_log_apply(log_index int) → boolean

Apply a committed log entry to the state machine.

SELECT pgraft_log_apply(1);

pgraft_log_get_stats() → TABLE(log_size, last_index, commit_index, last_applied)

Get statistics about the Raft log.

SELECT * FROM pgraft_log_get_stats();

pgraft_log_get_entry_sql(log_index int) → TABLE(index, term, data)

Retrieve a specific log entry by index.

SELECT * FROM pgraft_log_get_entry_sql(1);

Monitoring and Debugging

pgraft_get_worker_state() → text

Get the current state of the pgraft background worker.

SELECT pgraft_get_worker_state();
-- Returns: "RUNNING", "STOPPED", "INITIALIZING", etc.

pgraft_get_queue_status() → TABLE(command_type, status, count)

Get status of the command queue.

SELECT * FROM pgraft_get_queue_status();

pgraft_set_debug(enabled boolean) → boolean

Enable or disable debug logging.

SELECT pgraft_set_debug(true);
-- Returns: true on success

pgraft_test() → boolean

Run basic functionality tests.

SELECT pgraft_test();
-- Returns: true if all tests pass