Database connection pooling
Application server connections routed through a pool to the database.
Database connection pooling is one of the highest-ROI performance optimizations in a microservices system. Opening a new database connection takes time (TCP handshake, SSL negotiation, authentication) — every single query. A connection pool maintains a set of reusable connections so applications get an idle one instead of waiting for a new one to open. This diagram shows two application servers sharing the same pool: when Server 1 finishes a query and returns its connection, Server 2 can immediately reuse it.
The pool also enforces a hard maximum on connections, preventing an out-of-control application from opening hundreds of connections and exhausting the database's capacity. Every production database system relies on this pattern.
When to use this template
- Database architecture documentation — show new backend engineers how connection pooling works and why it matters. Many engineers first encounter "connection pool exhausted" errors without understanding the mechanism.
- Performance tuning reviews — annotate this diagram with your actual pool size, connection timeout, and the peak concurrent queries you observe, so the team can see whether your pool is undersized.
- Scaling decision documents — when considering adding app servers, include this diagram to show how it affects pool utilization and predict whether your database connection limit is at risk.
How to adapt it
Extend the flow to show your specific architecture:
- Add PgBouncer or similar proxy as a separate participant between the app servers and the connection pool.
- Show connection validation logic — the pool checks if a reused connection is still alive before handing it to the app, or allows stale connections and lets the app detect disconnects.
- Document your connection timeout and queue behavior — does the app fail immediately if no connection is available, or does it retry with exponential backoff?
Visual edits regenerate clean Mermaid code, so you can sketch these variations and export to your operations runbook or new-engineer onboarding docs.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant A as App Server 1
participant B as App Server 2
participant P as Connection Pool
participant D as Database
A->>P: Request connection
P->>P: Check available connections
alt Connection available
P-->>A: Reuse idle connection
else No idle connection
P->>D: Open new connection (if < max)
D-->>P: Connected
P-->>A: New connection
end
A->>D: SELECT * FROM users
D-->>A: 200 rows
A->>P: Return connection
P->>P: Mark as idle
B->>P: Request connection
P-->>B: Reuse connection from A
B->>D: UPDATE users SET...
D-->>B: 1 row affected
B->>P: Return connection
Frequently asked questions
- What is database connection pooling?
- Connection pooling reuses database connections across multiple application servers instead of opening a new one for every query. The pool maintains a set of idle connections; when an app requests a connection, it gets an idle one from the pool instead of waiting for a new TCP handshake and authentication. This cuts latency and CPU overhead dramatically.
- How many connections should the pool maintain?
- Start with max_connections = (number of app servers × concurrent queries per server) + buffer. If you have 5 app servers, each handling 10 concurrent queries, aim for 50 + 10 = 60 connections. Too few and apps wait for idle connections; too many and the database runs out of memory. Monitor your actual usage and tune.
- What happens when the pool runs out of connections?
- Apps queue and wait for an idle connection, with a timeout (typically 30 seconds). If the timeout hits, the app fails with a "connection pool exhausted" error. To prevent this, monitor pool saturation and set alerts if 80%+ of connections are in use, then add app capacity or reduce connection-holding time.
- Should I use a proxy like PgBouncer or a driver-level pool?
- Both work; PgBouncer is a separate service (easier multi-language support, clearer diagnostics), while driver-level pools live in each app (one less network hop, simpler deployment). This diagram works for both — the Connection Pool box could be either. Visual edits regenerate clean Mermaid code if you need to show your specific choice.
Related templates
Database indexing strategy
Decision tree for choosing single-column, composite, and specialized indexes.
API gateway request routing
Gateway routing requests to microservices based on path and headers.
API rate limiting sequence
Client, gateway, and limiter handling a 429 with Retry-After.