DocumentationpgBalancer Documentation

Getting Started with pgBalancer

Deploy the PostgreSQL load balancer with routing, REST API management, and MQTT event streaming. Follow this guide to build from source, configure pools, and verify your installation.

Requirements

  • PostgreSQL 13–18 (server + development headers)
  • Build toolchain: gcc/clang, make, autoconf, automake, libtool
  • Optional: OpenSSL, PAM, LDAP for advanced authentication
  • System access to manage /etc/pgbalancer configuration directory

Build and Install

Compile pgBalancer from source using autotools, then install binaries and CLI utilities.

Step 1 · Clone Repository

Clone pgBalancer

git clone https://github.com/pgElephant/pgBalancer.git
cd pgBalancer

Step 2 · Generate Build Scripts

Autotools

autoreconf -fi
# Generates configure script and build files

Step 3 · Configure Options

Configure build

# Basic configure
./configure

# Enable SSL, PAM, LDAP, custom prefix
./configure \
  --with-openssl \
  --with-pam \
  --with-ldap \
  --prefix=/usr/local/pgbalancer

Step 4 · Compile and Install

Build & deploy

make -j$(nproc)
sudo make install

# Verify binaries
pgbalancer --version
bctl --version

Configure pgBalancer

pgBalancer uses .conf files (not YAML). Set up configuration, authentication, and directories as shown below.

Step 5 · Create Config Directory

Config directory

sudo mkdir -p /etc/pgbalancer
sudo cp /usr/local/etc/pgbalancer.conf.sample /etc/pgbalancer/pgbalancer.conf
sudo cp /usr/local/etc/pool_hba.conf.sample /etc/pgbalancer/pool_hba.conf
sudo cp /usr/local/etc/pcp.conf.sample /etc/pgbalancer/pcp.conf
sudo chown -R postgres:postgres /etc/pgbalancer
sudo chmod 600 /etc/pgbalancer/pgbalancer.conf

Step 6 · Edit pgbalancer.conf

Configure listeners, backend servers, AI policies, and observability features.

Sample configuration

# Connection settings
listen_addresses = '*'
port = 5432
pcp_port = 9898

# Backend servers
backend_hostname0 = 'localhost'
backend_port0 = 5433
backend_flag0 = 'ALLOW_TO_FAILOVER'

backend_hostname1 = 'localhost'
backend_port1 = 5434
backend_flag1 = 'ALLOW_TO_FAILOVER'

# AI load balancing
enable_ai_load_balance = on
ai_learning_rate = 0.01
ai_exploration_rate = 0.1

# REST API
enable_rest_api = on
rest_api_port = 8080
rest_api_auth = off

# MQTT events
enable_mqtt = on
mqtt_broker_address = 'localhost'

# Pool settings
num_init_children = 32
max_pool = 4

Step 7 · Configure Authentication (pool_hba.conf)

pool_hba.conf

# TYPE  DATABASE    USER        CIDR-ADDRESS        METHOD
local   all         all                               trust
host    all         all         127.0.0.1/32         trust
host    all         all         192.168.1.0/24       md5
host    all         all         ::1/128              trust

Start and Verify

Launch pgBalancer as a service, then validate health via CLI and REST API diagnostics.

Step 8 · Launch pgBalancer

Start service

# Foreground (testing)
pgbalancer -n -f /etc/pgbalancer/pgbalancer.conf

# Background daemon
pgbalancer -f /etc/pgbalancer/pgbalancer.conf -D

# systemd
sudo systemctl start pgbalancer
sudo systemctl enable pgbalancer

Step 9 · Verify Health

Verification

# CLI checks
bctl node-status --format=table
bctl pool-status --format=table

# REST API (if enabled)
curl http://localhost:8080/api/health
curl http://localhost:8080/api/backends | jq

# Test connection through pgBalancer
psql -h localhost -p 5432 -U postgres -c "SELECT version();"

Next Steps

⚙️ Configuration Guide

Full reference for AI tuning, routing policies, and security settings.

🌐 REST API Reference

17 HTTP/JSON endpoints for cluster management.

⌨️ bctl CLI Reference

Complete command-line interface documentation.

🤖 AI Load Balancing

Machine learning algorithms and intelligent routing.

Support Resources

PreviouspgBalancer Documentation
NextConfiguration Reference