REST API Usage

Enable REST API Server

pgBalancer includes an integrated REST API server running as a child process:

# REST API Server Configuration
enable_rest_api = on                # Enable HTTP API server
rest_api_port = 8080                # API listens on this port
rest_api_hostname = '0.0.0.0'       # Listen on all interfaces
rest_api_timeout = 30               # Request timeout (seconds)

# Authentication (optional)
rest_api_auth = on                  # Enable JWT authentication
rest_api_secret_key = 'your-secret-key-here'  # HMAC-SHA256 secret
rest_api_token_expiry = 3600        # Token expiry (seconds)

# CORS settings
rest_api_cors_enabled = on          # Enable CORS
rest_api_cors_origins = '*'         # Allowed origins

# Enable detailed logging
rest_api_log_requests = on          # Log all API requests
rest_api_log_level = 'info'         # info, debug, warn, error

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

# Verify API is running
curl -s http://localhost:8080/api/v1/health

# Response:
{
  "status": "ok",
  "version": "pgbalancer 5.0.0",
  "uptime_seconds": 12345,
  "timestamp": "2025-11-06T12:00:00Z"
}

Authentication & Security

Configure TLS, API keys, and RBAC for REST API access:

Core API Endpoints

Use the REST API to manage pools, view metrics, and automate failover:

# GET /api/v1/pool/processes
curl -s http://localhost:8080/api/v1/pool/processes | jq

{
  "processes": [
    {
      "pool_pid": 12345,
      "start_time": "2025-11-06T10:30:00Z",
      "database": "testdb",
      "username": "appuser",
      "create_time": "2025-11-06T10:30:01Z",
      "pool_counter": 150,
      "backend_id": 0,
      "connected": true
    }
  ],
  "total": 32,
  "active": 28,
  "idle": 4
}

# GET /api/v1/pool/stats
curl -s http://localhost:8080/api/v1/pool/stats | jq

{
  "total_capacity": 128,
  "active_connections": 45,
  "idle_connections": 83,
  "utilization_percent": 35.16,
  "cache_hits": 15420,
  "cache_misses": 89,
  "cache_hit_rate": 99.42,
  "mode": "transaction",
  "num_init_children": 32,
  "max_pool": 4
}

Connection Pool Management

Monitor and manage connection pools:

# GET /api/v1/pool/processes
curl -s http://localhost:8080/api/v1/pool/processes | jq

# GET /api/v1/pool/stats
curl -s http://localhost:8080/api/v1/pool/stats | jq

Failover & Health Checks

Automate failover and health monitoring:

# POST /api/v1/failover/promote
curl -X POST http://localhost:8080/api/v1/failover/promote \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

{
  "status": "success",
  "message": "Manual failover initiated"
}

Prometheus & Grafana

Access real-time metrics and monitoring data:

# GET /metrics (Prometheus format)
curl -s http://localhost:8080/metrics

# HELP pgbalancer_up Server status (1=up, 0=down)
# TYPE pgbalancer_up gauge
pgbalancer_up 1

# HELP pgbalancer_backend_up Backend status (1=up, 0=down)
# TYPE pgbalancer_backend_up gauge
pgbalancer_backend_up{node_id="0",hostname="db-primary.internal"} 1

# GET /api/v1/status
curl -s http://localhost:8080/api/v1/status | jq

{
  "server": {
    "version": "pgbalancer 5.0.0",
    "uptime_seconds": 432000
  },
  "backends": {
    "total": 3,
    "up": 3,
    "down": 0
  }
}

Full API Spec