Why does `configure` fail with "pg_config not found"?

Because PostgreSQL splits its packages and doesn't tell you. You need the development libraries that your distro probably doesn't install by default: ```bash # Ubuntu/Debian apt-get install libpq-dev postgresql-server-dev-XX # RHEL/CentOS yum install postgresql-devel ``` Replace XX with your PostgreSQL version. This will save you 30 minutes of Googling the same error message everyone else hits.

Can I mix PostgreSQL versions in a Pgpool cluster?

No, and [the error messages won't help you figure out why things are breaking](https://www.pgpool.net/mediawiki/index.php/FAQ). All servers must be the same major version (e.g., all 15.x). Mixing 14.x and 15.x will cause weird protocol errors that look like network issues.

Why does authentication always fail?

Because Pgpool-II authentication is a special kind of hell. You need to sync **three** different auth configs and they all use slightly different formats. When you get `authentication failed for user`, it's usually the `pool_passwd` file. Use the `pg_md5` utility to generate password hashes: ```bash pg_md5 -m -u myuser mypassword ``` Don't try to manually create MD5 hashes. It won't work and you'll waste hours debugging why.

Why aren't my connections load balanced evenly?

Because load balancing in Pgpool-II is **session-based**, not query-based. If your app holds connections open (like every modern web framework), your "load balancing" becomes "randomly stick to one server for 10 minutes." [This is by design, not a bug](https://www.pgpool.net/mediawiki/index.php/FAQ). Long-lived connections will hammer one replica while others sit idle. If you need statement-level balancing, use application-level routing or HAProxy with custom rules.

Why does failover take forever?

Default health check settings are conservative to avoid false positives. You're probably seeing 10-30 seconds of downtime while Pgpool figures out your primary is dead. Tune `health_check_period` and `health_check_timeout` but be prepared for false positives during network hiccups: ``` health_check_period = 5 # Check every 5 seconds health_check_timeout = 3 # 3 second timeout health_check_max_retries = 2 # Retry twice before giving up ```

Why do I get "connection not available" errors?

You hit the connection limit. With default settings (32 child processes, `max_pool = 4`), you can handle 128 client connections max. Each process maintains its own connection pool, so math gets weird quickly. Either increase `num_init_children` or tune `max_pool` based on your database capacity. Remember: 32 processes × 4 pools × 3 backends = 384 database connections.

Why is my CPU usage at 300%?

[SSL termination at Pgpool-II will murder your CPU](https://www.pgpool.net/mediawiki/index.php/FAQ), especially with OpenSSL 3.0.2. We've seen 4-core boxes max out handling 50 SSL connections. Either upgrade to Pgpool-II 4.6.3+ or terminate SSL at a load balancer: ``` # HAProxy in front of Pgpool, SSL to plain HTTP frontend ssl_frontend bind *:5432 ssl crt /etc/ssl/certs/postgres.pem default_backend pgpool_plain backend pgpool_plain server pgpool1 127.0.0.1:5433 check ```

How do I fix "relation does not exist" errors?

This happens when different connections end up in different database contexts. Pgpool-II doesn't maintain session state across pooled connections, so if your app relies on session-specific settings, it'll break randomly. Either: 1. Always specify database names explicitly in connection strings 2. Set `reset_query_list` to restore session state on connection reuse 3. Switch to PgBouncer's transaction-level pooling if this keeps happening

Why does Watchdog keep split-brain?

Because network partitions are real and Watchdog assumes perfect connectivity. When Pgpool instances can't talk to each other, they both think they're primary. Monitor your VIP assignments and have a plan for manual intervention. Network-level split-brain is an infrastructure problem, not a Pgpool problem.

What happens during failover?

All client connections to the failed backend get dropped with `ECONNRESET`. Your application **must** handle connection failures gracefully and retry. [This is documented behavior](https://www.pgpool.net/mediawiki/index.php/FAQ), not a bug. Plan for it or users will see errors during database failover.

Is Pgpool-II stable enough for production?

Yes, but it requires proper tuning and monitoring. We've run it in production handling thousands of connections, but it took weeks to get the configuration right. Start with PgBouncer if you just need connection pooling. Move to Pgpool-II only if you specifically need its advanced features and have time to configure it properly.

How many backend servers can Pgpool-II handle?

Theoretically many, but practical limits depend on your network and hardware. Most production deployments use 2-5 backends. Beyond that, the complexity and coordination overhead usually aren't worth it.

Should I use Pgpool-II with cloud databases?

Maybe. Azure PostgreSQL requires [clear text passwords instead of MD5](https://www.pgpool.net/mediawiki/index.php/FAQ), which breaks default authentication. AWS RDS works better but you're probably better off using RDS Proxy if you're already on AWS. Cloud databases have their own connection pooling and high availability features. Pgpool-II adds value mainly for read/write splitting and query caching in cloud environments.

Currently viewing the AI version

Switch to human version

Pgpool-II: PostgreSQL Connection Pooling & High Availability

Technical Specifications

Architecture

Process Model: Fork-based like PostgreSQL (not thread-based)
Child Processes: 32 maximum default, each uses 2MB RAM baseline
Connection Pooling: Per-process pools, not shared between processes
Baseline Memory: 64MB+ before handling any connections
Failure Behavior: Single child crash kills all children and respawns them

Connection Management

Pool Structure: Each process maintains separate backend connection pools
Connection Calculation: processes × max_pool × backend_servers = total DB connections
- Example: 32 processes × 4 pool × 3 backends = 384 potential DB connections
Client Connection Limit: num_init_children × max_pool (128 with defaults)
Connection Establishment: Reduces latency from 45ms to <1ms for pooled connections

Performance Characteristics

SSL Performance Issue: 300% CPU utilization with OpenSSL 3.0.2
SSL Connection Handling: 75% CPU utilization with SSL enabled on 4-core systems
Version 4.6.3: Fixes SSL performance issues with OpenSSL 3.x
Health Check Overhead: 10-30 second failover detection with default settings

Critical Configuration Requirements

Essential Files

pgpool.conf: 200+ parameters controlling all functionality
pcp.conf: Administrative command authentication
pool_hba.conf: Must mirror PostgreSQL's pg_hba.conf
pool_passwd: Password hashes using pg_md5 utility

Authentication Synchronization

CRITICAL: Three separate auth configurations must be synchronized:

PostgreSQL pg_hba.conf
Pgpool pool_hba.conf
pool_passwd file with correct MD5 hashes

Failure Point: Password hash mismatches cause "authentication failed" errors

Production Configuration Gotchas

Health Check Tuning: Default 10s intervals too conservative, 5s recommended but increases false positives
Connection Math: Calculate total DB connections carefully before deployment
Log Rotation: Query logging can fill 20GB in 6 hours during connection storms
DNS Dependencies: listen_addresses = '*' fails if DNS hiccups occur

Operational Limitations

Load Balancing Reality

Session-Based Routing: NOT statement-based routing
Long-Lived Connections: Web frameworks hold connections open, causing uneven distribution
Typical Result: One replica gets 80% traffic while others idle
Query Awareness: Analyzes SQL for routing but limited by session affinity

Failover Characteristics

Connection Drops: ALL client connections dropped during failover (ECONNRESET)
Detection Time: 10-30 seconds with default health check settings
Application Requirement: Must handle connection failures gracefully
Detection Method: Uses SELECT pg_is_in_recovery() to identify primary

SSL Implementation Issues

CPU Impact: SSL termination at Pgpool destroys CPU performance
Workaround: Terminate SSL at load balancer, use plaintext to Pgpool
OpenSSL 3.0 Problem: Documented performance regression in older versions

Resource Requirements

Time Investment

Initial Setup: 2-3 days for basic configuration
Production Tuning: Additional 1 week for optimization
Learning Curve: Weekend project for configuration complexity

System Resources

Memory: 64MB baseline + 2MB per child process
CPU: Significant SSL overhead, monitor usage carefully
Network: Health checks generate constant backend traffic

Expertise Requirements

PostgreSQL Knowledge: Deep understanding of pg_hba.conf and authentication
Network Architecture: SSL termination and load balancer integration
Debugging Skills: Complex error messages require systematic troubleshooting

Decision Matrix: Pgpool-II vs Alternatives

Capability	Pgpool-II	PgBouncer	HAProxy + Patroni	AWS RDS Proxy
Connection Pooling	Complex but functional	Simple and reliable	External solution needed	Managed service
Query-Aware Routing	Session-based	Manual only	Rule-based	Automatic
Automatic Failover	Usually works	Requires external tools	Excellent with Patroni	Managed
Configuration Complexity	Weekend project	10 lines	Moderate	Point-and-click
Production Stability	Requires tuning	Rock solid	Complex but stable	Vendor responsibility
Resource Overhead	64MB+ baseline	~10MB total	Python + etcd cluster	N/A
Cost	Time investment	Minimal	Operational complexity	$ per connection

Critical Warnings

Authentication Failures

Primary Cause: pool_passwd file with incorrect MD5 hashes
Solution: Always use pg_md5 utility, never manual hash generation
Debug Time: Hours wasted on auth issues with unhelpful error messages

Version-Specific Issues

OpenSSL 3.0.2: Causes severe CPU performance degradation
Minimum Recommended: Version 4.6.3 for SSL performance fixes
Azure PostgreSQL: Requires clear text passwords instead of MD5

Split-Brain Scenarios

Watchdog Clustering: Network partitions cause dual-primary situations
Monitoring Required: Track VIP assignments for manual intervention
Infrastructure Problem: Network-level issue, not Pgpool limitation

Production Failure Modes

Connection Storms: Max connections reached, new connections dropped
False Positives: Aggressive health checks trigger unnecessary failovers
Session State Loss: Applications relying on session-specific settings break randomly
Child Process Crashes: Single failure can temporarily kill entire connection pool

When to Choose Pgpool-II

Use Cases That Justify Complexity

Read/Write Splitting: Automatic query routing required
Query Caching: Built-in memcached functionality needed
Advanced Load Balancing: Query-aware routing despite session limitations
Integrated HA: Single solution for pooling, routing, and failover

When to Choose Alternatives

Simple Connection Pooling: PgBouncer for reliability and simplicity
Cloud Environments: RDS Proxy or native cloud pooling
Pure Load Balancing: HAProxy with custom rules
Enterprise HA: Patroni + etcd for robust cluster management

Implementation Prerequisites

Technical Requirements

PostgreSQL development libraries (libpq-dev, postgresql-server-dev)
Same major PostgreSQL version across all cluster nodes
Proper DNS resolution for all backend hostnames
SSL certificate management strategy

Operational Prerequisites

Monitoring system for connection metrics and CPU usage
Log rotation strategy for query logging
Network connectivity monitoring between all nodes
Disaster recovery procedures for split-brain scenarios

Team Readiness

PostgreSQL authentication expertise
Network troubleshooting capabilities
24/7 operational support for complex failure scenarios
Rollback plan to simpler connection pooling solution

Useful Links for Further Investigation

Link Group

Link	Description
Pgpool-II Official Website	The main site with downloads and project updates. Clean layout, current information, but the docs can be overwhelming for beginners.
Latest Release Notes	Version 4.6.3 release info from August 2025. Actually worth reading - they fixed the SSL CPU murder bug and PostgreSQL 17 compatibility.
Official Documentation Wiki	Comprehensive but dense. Good for reference, terrible for learning. The example configs actually work, unlike most documentation.
Pgpool-II FAQ	This is gold. Bookmark it now. The FAQ has better troubleshooting info than the main docs and covers the gotchas that aren't documented elsewhere.
ScaleGrid Connection Pooling Guide	Best hands-on tutorial for beginners. Shows real config examples and explains why settings matter. Skip the marketing fluff, focus on the technical content.
Basic Configuration Examples	Official step-by-step configs that actually work in development. Don't use these in production without tuning, but good for getting started.
Watchdog Clustering Setup	Advanced clustering configuration. Dense reading but necessary if you need high availability. Plan a weekend to implement this properly.
MyDBOps Installation Guide	Practical installation walkthrough with real-world considerations. Covers the dependency issues that trip up first-time installers.
PgBouncer vs Pgpool-II Decision Guide	2025 comparison that actually helps you decide between tools. No bullshit feature lists - just practical advice for real use cases.
ScaleGrid Pooling Comparison Series	Multi-part series with benchmarks and performance data. The numbers are from real tests, not theoretical maximums.
Percona PostgreSQL Performance Blog	Enterprise-focused analysis with production examples. Good for understanding when Pgpool-II makes sense vs simpler alternatives.
EDB Connection Pool Analysis	Real-world case study showing connection pool performance impact. Has actual numbers instead of marketing claims.
Stack Overflow Pgpool Tag	Best place for troubleshooting specific issues. Search here before asking questions - most problems have been solved already.
GitHub Issues Repository	Bug reports and feature requests. Check here if you hit weird edge cases. Maintainers are responsive to legitimate bugs.
PostgreSQL General Mailing Lists	For complex deployment questions that don't fit Stack Overflow. Serious PostgreSQL folks hang out here.
Reddit r/PostgreSQL Community	Less formal discussion about PostgreSQL tooling. Good for "should I use X or Y" type questions. Search for "pgpool" or "connection pooling" to find relevant discussions.
Google Cloud HA Architecture Guide	Comprehensive guide to building resilient PostgreSQL infrastructure. Shows Pgpool-II in context with other HA tools.
Confluence Enterprise Setup	Real enterprise deployment example. Shows integration with business applications and operational considerations.
Instaclustr PostgreSQL Cluster Guide	End-to-end cluster setup with monitoring and optimization. Heavy reading but covers production deployment properly.
PCP Command Documentation	Management commands for monitoring Pgpool clusters. Essential for production operations but the syntax is cryptic.
Sample Configuration Files	Official config templates for different scenarios. Better starting point than writing configs from scratch.
Docker Images Hub	Community Docker images for development and testing. Quality varies - read the README files carefully.
Debian Security Advisories	Security updates and CVE information. Set up alerts if you're running Pgpool in production.
PostgreSQL Security Information	General PostgreSQL security guidelines that apply to Pgpool deployments. Covers authentication and network security.
EDB Security Hardening Guide	Comprehensive security checklist for PostgreSQL deployments. More relevant for the backend databases than Pgpool itself.

31%

Recommendations combine user behavior, content similarity, research intelligence, and SEO optimization