Architecture & Internals

pgbalancer is built for performance and reliability with a modern, scalable architecture:

Core Architecture

  • Written in C with PostgreSQL integration for optimal performance
  • Event-driven, non-blocking I/O with epoll/kqueue support
  • Modular design with pluggable components for pooling, routing, and metrics
  • Cloud-native architecture designed for container and Kubernetes environments

Worker Lifecycle

pgbalancer uses a multi-process architecture with specialized workers:

Main Process

  • • Configuration loading and validation
  • • Worker process management
  • • Signal handling and graceful shutdown
  • • Health monitoring and restart logic

Worker Processes

  • • Client connection handling
  • • Backend connection pooling
  • • Query routing and load balancing
  • • Health checks and failover

Technical Details

Connection Pooling

Intelligent connection management with automatic scaling and health monitoring.

Load Balancing

Multiple algorithms including round-robin, least connections, and weighted distribution.

Monitoring

Built-in metrics collection with Prometheus integration and REST API endpoints.

See the Configuration page for YAML options and setup details.