Connection Routing with PgBouncer and HAProxy
Route clients to the current primary and balance read traffic across replicas to keep applications available through failovers.
Connection Routing with PgBouncer and HAProxy is a free Advanced PostgreSQL: Indexing, Partitioning, Replication lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Advanced PostgreSQL: Indexing, Partitioning, Replication learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
The Routing Problem
After a failover the primary moves to a new host. Applications need a stable endpoint so they do not have to be reconfigured each time. Connection routing solves this.
PgBouncer Basics
PgBouncer is a lightweight connection pooler. It multiplexes many client connections onto a small set of server connections, reducing backend load.
Pooling Modes
PgBouncer offers three pool modes:
- session — connection held for the whole client session
- transaction — returned after each transaction (most common)
- statement — returned after each statement
Basic Config
A minimal pgbouncer.ini points at the database and sets the pool mode.
[databases]
app = host=10.0.0.5 port=5432 dbname=app
[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20HAProxy for the Primary
HAProxy can health-check backends and forward traffic only to the node that is currently the primary, giving clients one fixed write endpoint.
Detecting the Primary
HAProxy uses an HTTP health check against a tool like Patroni's REST API. Only the primary returns 200 on the leader endpoint.
option httpchk GET /primary
http-check expect status 200Separate Read Endpoint
Define a second HAProxy frontend that balances across replicas (the /replica health check), so read-only queries scale across standbys.
listen postgres_read
bind *:5433
balance roundrobin
option httpchk GET /replicaRead/Write Splitting
Applications connect to port 5432 for writes (primary) and 5433 for reads (replicas). Many drivers and ORMs support separate read/write data sources.
Replica Lag Caution
Replicas can lag behind the primary. Route only queries that tolerate slightly stale data to replicas; read-your-own-write paths should hit the primary.
Putting It Together
A common stack: app -> PgBouncer -> HAProxy -> Patroni-managed PostgreSQL cluster. PgBouncer pools, HAProxy routes by role, Patroni manages failover.
Failover Behavior
On failover, Patroni promotes a new primary, HAProxy health checks flip the leader within seconds, and pooled connections reconnect to the new endpoint with minimal disruption.
Quick Check
How does HAProxy keep sending writes to the right node after failover?
Recap
You learned to route connections for high availability: PgBouncer pools connections, HAProxy health-checks to find the primary and balance reads across replicas, and the whole stack flips automatically on failover.
Frequently asked questions
Is the “Connection Routing with PgBouncer and HAProxy” lesson free?
Yes — the full text of “Connection Routing with PgBouncer and HAProxy” is free to read here on the web, and the Advanced PostgreSQL: Indexing, Partitioning, Replication course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Advanced PostgreSQL: Indexing, Partitioning, Replication course, upgrade to CoddyKit PRO.
What will I learn in “Connection Routing with PgBouncer and HAProxy”?
Route clients to the current primary and balance read traffic across replicas to keep applications available through failovers. You practise Advanced PostgreSQL: Indexing, Partitioning, Replication with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Advanced PostgreSQL: Indexing, Partitioning, Replication?
No prior experience is required. Advanced PostgreSQL: Indexing, Partitioning, Replication on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Connection Routing with PgBouncer and HAProxy” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Advanced PostgreSQL: Indexing, Partitioning, Replication lesson?
Yes. Every Advanced PostgreSQL: Indexing, Partitioning, Replication lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Automatic Failover Tools (Patroni)
- Monitoring Replication Health
- Disaster Recovery Strategies
- Connection Routing with PgBouncer and HAProxy