royprasun/pgpool repository overview

⁠Pgpool-II Docker Image for PostgreSQL Load Balancing

This Docker image is based on bitnami/pgpool:latest and is tailored for a specific use case: providing full pgpool configuration through environment variables to simplify deployment without mounting configuration files.

It is designed primarily for scenarios where you use cloud-hosted PostgreSQL replicas and want lightweight load balancing in a single VM or serverless Docker environment, enabling quick, zero-config deployments.

⁠⚠️ Configuration Files vs. Environment Variables

While configuration files are commonly preferred for large-scale or Kubernetes-based deployments, this image focuses on simpler, cost-effective setups—such as cloud-hosted PostgreSQL with replicas—where lightweight load balancing is needed using Docker in a single VM or serverless environment.

By relying entirely on environment variables, it enables fast deployment without volume mounts or custom templates. This approach works well for SaaS platforms, testing, minimal infrastructure, and also scales efficiently at low operational cost without the complexity of orchestration layers.

⁠🚀 Features

• 🔧 Full Environment Variable Configuration: Configure pgpool entirely through environment variables
• ⚖️ Backend Node Load Balancing Weights: Support for load balancing weights in backend node configuration
• 🔄 Backward Compatibility: Compatible with existing Bitnami pgpool environment variables
• 📦 Ready-to-Deploy: No configuration files needed for standard deployments
• 🔐 SSL/TLS Support: Full SSL/TLS configuration via environment variables
• 🏥 Health Check Configuration: Comprehensive health check options
• 📊 Load Balancing: Advanced load balancing configuration options

⁠📋 Quick Start

⁠Basic Usage

docker run -d \
  --name pgpool \
  -p 5432:5432 \
  -e PGPOOL_BACKEND_NODES="0:postgres-master:5432:1,1:postgres-slave1:5432:2,2:postgres-slave2:5432:1" \
  -e PGPOOL_SR_CHECK_USER=postgres \
  -e PGPOOL_SR_CHECK_PASSWORD=password \
  -e PGPOOL_POSTGRES_USERNAME=postgres \
  -e PGPOOL_POSTGRES_PASSWORD=password \
  -e PGPOOL_ADMIN_USERNAME=admin \
  -e PGPOOL_ADMIN_PASSWORD=adminpass \
  royprasun/pgpool:latest

⁠With SSL/TLS

docker run -d \
  --name pgpool-ssl \
  -p 5432:5432 \
  -v /path/to/certs:/opt/bitnami/pgpool/certs \
  -e PGPOOL_BACKEND_NODES="0:postgres-master:5432,1:postgres-slave:5432" \
  -e PGPOOL_ENABLE_TLS=yes \
  -e PGPOOL_TLS_CERT_FILE=/opt/bitnami/pgpool/certs/postgres.crt \
  -e PGPOOL_TLS_KEY_FILE=/opt/bitnami/pgpool/certs/postgres.key \
  -e PGPOOL_SR_CHECK_USER=postgres \
  -e PGPOOL_SR_CHECK_PASSWORD=password \
  royprasun/pgpool:latest

⁠🔧 Environment Variables

⁠Enhanced Backend Configuration

⁠PGPOOL_BACKEND_NODES (Enhanced)

Configure backend PostgreSQL nodes with optional load balancing weights.

Format: index:hostname:port[:weight][,index:hostname:port[:weight]]...

Examples:

# Basic configuration (weight defaults to 1)
PGPOOL_BACKEND_NODES="0:postgres-master:5432,1:postgres-slave:5432"

# With custom weights (slave gets 2x more read traffic)
PGPOOL_BACKEND_NODES="0:postgres-master:5432:1,1:postgres-slave:5432:2"

# Multiple backends with different weights
PGPOOL_BACKEND_NODES="0:master:5432:1,1:slave1:5432:3,2:slave2:5432:2,3:slave3:5432:1"

⁠Connection Settings

⁠Streaming Replication

⁠Health Check Configuration

⁠Load Balancing

⁠Failover Configuration

⁠SSL/TLS Configuration

⁠Logging

⁠Authentication

⁠Bitnami Compatibility

All existing Bitnami pgpool environment variables are supported:

• PGPOOL_ENABLE_LDAP
• PGPOOL_ENABLE_LOAD_BALANCING
• PGPOOL_ENABLE_STATEMENT_LOAD_BALANCING
• PGPOOL_ENABLE_POOL_HBA
• PGPOOL_ENABLE_POOL_PASSWD
• PGPOOL_NUM_INIT_CHILDREN
• PGPOOL_RESERVED_CONNECTIONS
• PGPOOL_POSTGRES_CUSTOM_USERS
• PGPOOL_POSTGRES_CUSTOM_PASSWORDS
• And many more...

⁠📋 Docker Compose Examples

⁠Quick Start (Simple Setup)

For development, testing, or learning:

# Start simple setup with basic PostgreSQL instances
docker compose -f docker-compose-simple.yml up -d

⁠Production Setup (HA Cluster)

For production deployments with streaming replication:

# Start production HA cluster
docker compose -f docker-compose-production.yml up -d

⁠Simple Setup (docker-compose-simple.yml)

Perfect for development and testing. Uses basic PostgreSQL instances for quick validation of pgpool features.

⁠Production Setup (docker-compose-production.yml)

Full production-ready setup with PostgreSQL streaming replication using bitnami/postgresql:16 for high availability and reliability.

⁠🐛 Troubleshooting

⁠Common Issues

1. Backend nodes not connecting

   • Check the PGPOOL_BACKEND_NODES format
   • Verify network connectivity between pgpool and PostgreSQL instances
   • Check PostgreSQL credentials and permissions

2. Health checks failing

   • Verify PGPOOL_HEALTH_CHECK_USER has proper permissions
   • Check health check timeout values
   • Review PostgreSQL logs for connection issues

3. Load balancing not working

   • Ensure PGPOOL_LOAD_BALANCE_MODE=on
   • Check backend weights are properly configured
   • Verify streaming replication is working

⁠Checking Configuration

View the generated configuration:

# Access the container
docker exec -it pgpool-debug bash

# View the generated pgpool.conf
cat /opt/bitnami/pgpool/conf/pgpool.conf

# Check pgpool status
pgpool -f /opt/bitnami/pgpool/conf/pgpool.conf -F /opt/bitnami/pgpool/conf/pcp.conf -n

⁠📊 Monitoring

⁠Health Checks

The image includes built-in health checks:

# Manual health check
docker exec pgpool /opt/bitnami/scripts/pgpool/healthcheck.sh

⁠Monitoring Endpoints

Connect to pgpool and run monitoring queries:

-- Show pool nodes status
SHOW POOL_NODES;

-- Show pool processes
SHOW POOL_PROCESSES;

-- Show pool version
SHOW POOL_VERSION;

⁠🙏 Acknowledgments

• Bitnami⁠ for the excellent base pgpool image
• PostgreSQL⁠ community

⁠📞 Support

• 📧 Email: [email protected]⁠