CLI Management (bctl)

Install and Configure bctl

bctl is the unified CLI tool that replaces multiple pcp_* commands:

# bctl is included with pgBalancer
# After installing pgbalancer, bctl is in /usr/local/bin

# Verify installation
which bctl
bctl --version

# Configuration file location
~/.config/pgbalancer/bctl.conf

Check Cluster Status

View overall cluster status and health:

# Show cluster status (table format - default)
bctl status

# JSON format for scripting
bctl status --format json | jq

# Quick health check
bctl health

# Exit code 0 = healthy, non-zero = unhealthy
# Useful in monitoring scripts

if bctl health --quiet; then
    echo "Cluster is healthy"
else
    echo "Cluster has issues!"
    bctl health --verbose
fi

Node Management

Manage backend nodes using bctl:

# List all backend nodes (table format)
bctl nodes list

# Get detailed info about node 0
bctl nodes info 0

# Detach node for maintenance
bctl nodes detach 2

# Attach node back
bctl nodes attach 2

# Promote standby to primary
bctl nodes promote 1 --force

Pool Management

Monitor and manage connection pools:

# List all pool processes
bctl pool processes

# Get pool statistics
bctl pool stats

Watchdog Management

Monitor watchdog status and coordination:

# View watchdog status
bctl watchdog status

Configuration and Logs

View configuration and logs:

# Show current configuration
bctl config show

# Get specific parameter
bctl config get pool_mode

# Tail pgBalancer logs
bctl logs --follow

# Filter by level
bctl logs --level error --tail 50

# Search logs
bctl logs --grep "failover" --tail 100

Command Reference

Automation Scripts

#!/bin/bash
# Monitor cluster health

if ! bctl health --quiet; then
    echo "⚠️  Cluster unhealthy!"
    
    # Get node status
    bctl nodes list --format json | jq -r '.nodes[] | select(.status=="down") | "Node \(.node_id) DOWN: \(.hostname)"'
    
    # Send alert
    curl -X POST https://alerts.example.com/webhook \
      -d '{"text": "pgBalancer cluster has issues"}'
    
    exit 1
fi

echo "✓ Cluster healthy"
exit 0

#!/bin/bash
# Alert on high pool utilization

UTILIZATION=$(bctl pool stats --format json | jq -r '.utilization_percent')

if (( ${UTILIZATION%.*} > 90 )); then
    echo "⚠️  High pool utilization: $UTILIZATION%"
    # Send alert
fi

Best Practices