pgraft Upgrade Tutorial

Prerequisites

1. Install pgraft

Build and install pgraft on each node. Enable the extension in postgresql.conf and restart the service.

# Install dependencies and build pgraft (example for Debian/Ubuntu)
sudo apt-get update && sudo apt-get install -y build-essential libpq-dev golang
make all
sudo make install

echo "shared_preload_libraries = 'pgraft'" | sudo tee -a /etc/postgresql/16/main/postgresql.conf
sudo systemctl restart postgresql@16-main

CREATE EXTENSION IF NOT EXISTS pgraft;

2. Bootstrap the Leader

Initialize cluster metadata and set a friendly cluster label. Confirm the node elected itself leader.

-- Run on the future leader after CREATE EXTENSION
dO $$ BEGIN PERFORM pgraft_init(); END $$;

SELECT pgraft_set_config('cluster_name', 'upgrade-cluster');
SELECT pgraft_save_config();

SELECT pgraft_is_leader();

3. Register Followers

Configure the remaining nodes with matching cluster identity and unique node IDs, then register them from the leader.

-- Execute on the leader once follower nodes are configured
SELECT pgraft_add_node(2, '10.0.0.12', 7002);
SELECT pgraft_add_node(3, '10.0.0.13', 7003);

SELECT node_id,
       state,
       match_index,
       commit_index
  FROM pgraft_get_nodes();

4. Configure Logical Replication

pgraft orchestrates leader elections while PostgreSQL logical replication migrates data between major versions.

-- Create publication on source (PostgreSQL 14)
CREATE PUBLICATION pgraft_upgrade FOR ALL TABLES;

-- On PostgreSQL 16 target node
CREATE SUBSCRIPTION pgraft_upgrade
  CONNECTION 'host=10.0.0.11 port=5432 user=replicator dbname=app sslmode=prefer'
  PUBLICATION pgraft_upgrade
  WITH (copy_data = true, create_slot = false);

Allow the subscription to copy existing data. Monitor pg_stat_subscription until catch-up is complete.

5. Verify Cluster Health

Before cutover, ensure Raft consensus is stable and replication slots are healthy.

SELECT node_id,
       state,
       messages_processed,
       lag_entries
  FROM pgraft_log_get_replication_status()
 ORDER BY node_id;

SELECT subname,
       (pg_current_xlog_location() - received_lsn) AS bytes_lag,
       last_msg_send_time,
       last_msg_receipt_time
  FROM pg_stat_subscription;

6. Perform Cutover

Drain application traffic, promote the new cluster, and redirect clients to the pgraft 16 cluster.

-- Drain application traffic
SELECT pgraft_transfer_leadership(3);

-- Confirm replication queues are empty
SELECT * FROM pg_stat_subscription_stats WHERE subname = 'pgraft_upgrade';

-- Promote new cluster and redirect clients
SELECT pgraft_set_config('failover_enabled', 'true');

# Example: Update PgBouncer configuration
echo "%include /etc/pgbouncer/pgraft-target.ini" | sudo tee /etc/pgbouncer/databases.ini
sudo systemctl reload pgbouncer

7. Post-Migration Validation

SELECT pgraft_quorum_met() AS quorum_ok,
       pgraft_get_leader() AS leader_id;

SELECT relname,
       relpages,
       reltuples
  FROM pg_catalog.pg_class
 WHERE relnamespace = 'public'::regnamespace
 ORDER BY reltuples DESC
 LIMIT 20;

Next Steps

Explore configuration tuning and the cluster management guide for more automation patterns.