DocumentationpgBalancer Documentation

Getting Started with pgBalancer

Deploy the AI-powered PostgreSQL load balancer with intelligent routing, REST API management, and MQTT event streaming. Follow this step-by-step 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