Documentationpgraft Documentation

Install pgRaft on PostgreSQL 16–18

Prerequisites

Before installing pgRaft, ensure you have:

  • PostgreSQL 16, 17, or 18 installed with development headers
  • Go toolchain 1.21+ available on PATH
  • gcc/clang, make, and pkg-config installed on build host
  • Ability to restart PostgreSQL after updating postgresql.conf

Run which pg_config to confirm it points to the target PostgreSQL installation before compiling.

Install system dependencies

Install PostgreSQL packages and build prerequisites on your operating system.

Ubuntu / Debian

Install packages

sudo apt-get update
sudo apt-get install -y postgresql-18 postgresql-server-dev-18     postgresql-contrib-18 golang-go build-essential pkg-config

RHEL / Rocky / AlmaLinux

Install packages

sudo yum install -y postgresql18 postgresql18-devel     postgresql18-contrib golang gcc make pkgconfig

macOS (Homebrew)

Install packages

brew install postgresql@18 go pkg-config
brew link --overwrite postgresql@18

Clone repository and build

Compile the PostgreSQL extension plus the Go-based Raft worker library.

Build pgRaft binaries

Compile

git clone https://github.com/pgElephant/pgraft.git
cd pgraft
make clean && make

# Override PostgreSQL location as needed
# make clean && make PG_CONFIG=/path/to/pg_config

Expected artifacts

Validate output

ls -lh ./dist
# pgraft.so      (SQL extension)
# pgraft_go.so   (embedded Raft worker)

Install pgRaft into PostgreSQL

Install the compiled shared libraries and SQL files into PostgreSQL's extension directories.

make install

sudo make install

# Validate install directories
pg_config --libdir
ls -lh $(pg_config --libdir)/pgraft*

Update postgresql.conf and restart

Load pgRaft at startup and define node identity for your cluster.

Configure Raft identity

postgresql.conf

shared_preload_libraries = 'pgraft'

# Node identity (adjust per node)
pgraft.cluster_id = 'production-cluster'
pgraft.node_id = 1
pgraft.address = '10.0.0.11'
pgraft.port = 7001
pgraft.data_dir = '/var/lib/postgresql/pgraft'

# Recommended WAL settings
synchronous_commit = on
wal_level = logical
max_wal_senders = 10

Restart PostgreSQL

Apply configuration

sudo systemctl restart postgresql   # systemd
# or
brew services restart postgresql@18  # macOS

Create extension and verify

Register pgRaft in your database, initialize metadata, and confirm worker health.

Enable pgRaft

Initialize node

CREATE EXTENSION pgraft;
SELECT pgraft_init();
SELECT extversion
FROM   pg_extension
WHERE  extname = 'pgraft';

Verify worker state

Diagnostics

SELECT pgraft_is_leader()  AS is_leader,
       pgraft_get_term()   AS current_term,
       pgraft_get_worker_state() AS worker_state;

df+ pgraft_*

Next Steps

PreviousGetting Started
NextConfiguration