pgbalancer Documentation

AI-Based PostgreSQL Load Balancer and Connection Pooler

pgbalancer is a modern PostgreSQL connection pooler and load balancer built as a fork of pgpool-II with significant enhancements for intelligent query routing, HTTP-based management, and real-time event streaming.

Overview

pgbalancer provides enterprise-grade connection pooling, load balancing, and high availability for PostgreSQL 13-18, enhanced with AI-powered load balancing, comprehensive REST API, MQTT event streaming, and professional CLI tools.

Key Features:

AI-Powered Load Balancing — Machine learning algorithms for intelligent query routing
REST API Management — 17 HTTP/JSON endpoints for complete cluster control
MQTT Event Streaming — Real-time publishing of cluster events
Professional CLI Tool (bctl) — Unified interface replacing 10+ pcp_* commands
Standard .conf Configuration — pgpool-II compatible configuration format
JWT Authentication — Secure API access with HMAC-SHA256 tokens
PostgreSQL 13-18 — Full support for latest versions
High Availability — Automatic failover with watchdog support
Connection Pooling — Efficient connection reuse and management
Health Monitoring — Continuous backend monitoring and health checks

Quick Install

# Prerequisites: PostgreSQL 13+ with development headers, autoconf, automake, libtool, make, gcc/clang

# Clone and configure
git clone https://github.com/pgelephant/pgbalancer.git
cd pgbalancer

# Generate configure script if needed
autoreconf -fi

# Configure with options
./configure --with-openssl --with-pam --with-ldap

# Build
make

# Install
sudo make install

# Configure
sudo cp /etc/pgbalancer/pgbalancer.conf.sample /etc/pgbalancer/pgbalancer.conf
sudo vi /etc/pgbalancer/pgbalancer.conf

# Start
pgbalancer -f /etc/pgbalancer/pgbalancer.conf -D

# Check status
bctl status

Why pgbalancer?

Modern API — HTTP/JSON REST API instead of binary PCP protocol
Unified CLI — Single bctl tool instead of 10+ separate pcp_* commands
AI Load Balancing — Machine learning algorithms for optimal query routing
MQTT Integration — Real-time event streaming for monitoring and automation
Better Monitoring — Prometheus metrics, Grafana dashboards, comprehensive health checks
Production Ready — Based on battle-tested pgpool-II with modern enhancements
Standard Configuration — Uses proven .conf format compatible with pgpool-II

Documentation Sections

Getting Started

Installation Guide - Complete setup instructions
Quick Start Guide - Get running in 5 minutes
Configuration Guide - All parameters explained

Core Features

AI Load Balancing - Machine learning algorithms
REST API Reference - Complete HTTP API documentation
MQTT Event Streaming - Real-time event publishing
CLI Tool (bctl) - Professional command-line interface

Operations

Connection Pooling - Efficient connection management
Load Balancing - Query distribution strategies
Failover & Recovery - High availability features
Health Monitoring - Backend monitoring
Performance Tuning - Optimization guidelines

Advanced Topics

Watchdog - High availability coordination
SSL/TLS - Secure connections
Authentication - PAM, LDAP, JWT
Monitoring Integration - Prometheus & Grafana

Reference

Configuration Parameters - Complete parameter reference
REST API Endpoints - All 17 HTTP endpoints
CLI Commands - bctl command reference
Error Codes - Troubleshooting guide
Examples - Configuration examples

Appendices

Release Notes - Version history
Migration Guide - From pgpool-II
FAQ - Frequently asked questions
License - PostgreSQL License

License

PostgreSQL License - see License for details.