Connection Pool Sizing, Timeouts, Lifetime, Health Checks, and Avoiding One-Session-per-Request Anti-Patterns

Learning outcomes

AtlasMart receives a burst of 200 concurrent API calls and someone proposes “set the pool to 1000.” That number is meaningless without database capacity, per-host semantics, request duration, transaction concurrency and connection budgets. This lesson treats the pool as a queueing boundary with explicit timeouts and failure signals.

1. Correct the anti-pattern wording first

2. Pool size follows concurrency math, not folklore

If an instance receives 40 concurrent database-active requests and each request holds one connection while streaming for 200 ms, a pool of 10 creates queueing by design; a pool of 1000 may only move overload to Neo4j. Start from measured concurrent database occupancy, server connection capacity, number of application instances and cluster hosts.

driver = GraphDatabase.driver(    URI,    auth=AUTH,    max_connection_pool_size=20,    connection_acquisition_timeout=2.0,    connection_timeout=5.0,    max_connection_lifetime=1800.0,    liveness_check_timeout=60.0,    max_transaction_retry_time=10.0,)

The numbers above are a lab starting point, not a production recommendation. In a routing driver the pool limit is per host, so total possible connections can scale with discovered cluster members and application identities.

3. Timeouts answer different failure questions

A good service has an explicit outer SLO/deadline and chooses inner budgets that leave time for useful error handling. A client-side timeout can leave commit outcome ambiguous; do not infer “rolled back” merely because the caller stopped waiting.

4. Health checks: useful but not free

verify_connectivity() is a startup/readiness diagnostic, not a per-request prerequisite. liveness_check_timeout optionally checks connections that have sat idle longer than a threshold; setting it to zero causes a check every acquisition and adds round trips. Usually leave it alone until network equipment is proven to drop idle connections.

def readiness(store: AtlasMartNeo4j) -> tuple[bool, str]:    try:        store.driver.verify_connectivity()        return True, "neo4j reachable"    except Exception as exc:        # map to structured internal diagnostics; do not leak credentials        return False, type(exc).__name__

5. Load-test the pool without hiding failures

from concurrent.futures import ThreadPoolExecutor, as_completedfrom statistics import medianfrom time import perf_counterQUERY = "CYPHER 25 MATCH (p:Product {productId:$id}) RETURN p.name AS name"def one(i):    t0 = perf_counter()    try:        records, summary, _ = store.driver.execute_query(            QUERY, id="P-1001", database_="neo4j", routing_=RoutingControl.READ)        return {"ok": True, "ms": (perf_counter()-t0)*1000,                "available_ms": summary.result_available_after}    except Exception as exc:        return {"ok": False, "ms": (perf_counter()-t0)*1000,                "error": type(exc).__name__}with ThreadPoolExecutor(max_workers=32) as pool:    results = [f.result() for f in as_completed([pool.submit(one, i) for i in range(200)])]ok = [r["ms"] for r in results if r["ok"]]errors = [r for r in results if not r["ok"]]print("success", len(ok), "errors", len(errors), "median_ms", median(ok) if ok else None)print("error_types", sorted({e["error"] for e in errors}))

Record p50/p95/p99 with an actual percentile library or stable helper, not only median. Repeat at controlled concurrency levels. Pool acquisition failures are valuable evidence: do not “fix” them by removing limits until you know whether the database itself is saturated.

6. Wrong approach: driver creation inside request handler

def endpoint(product_id):    with GraphDatabase.driver(URI, auth=AUTH) as driver:  # WRONG hot path        driver.verify_connectivity()                     # WRONG per request        return driver.execute_query(            "MATCH (p:Product {productId:$id}) RETURN p.name",            id=product_id, database_="neo4j")

Each request now creates/destroys a pool and may add connectivity handshakes. The repaired service injects one Driver into repositories and creates sessions/transactions only where the unit of work requires them.

Production judgment

Summary and next step

Pool settings bound resource acquisition; routing and retry policies decide where work goes and how failures are re-attempted. Lesson 4 combines those mechanisms with bookmarks and request correlation.

Authoritative references

• Current Neo4j versions — Current server and 5.26 LTS release snapshot.
• Neo4j Python Driver Manual — Official application-driver guide used by the mandatory lab.
• Python Driver 6.3 API — Current API, Bolt compatibility and lifecycle contract.
• Driver connection guide — Driver lifetime, connectivity checks and cluster routing.
• Advanced connection information — URI schemes, TLS, resolver and connection configuration.
• Transactions with the Python driver — Session/transaction lifecycle, managed retries and result streaming.
• Python driver performance recommendations — Lazy streaming, fetch size and read routing guidance.
• Bolt compatibility matrix — Neo4j DBMS and negotiated Bolt protocol versions.
• Python driver configuration API — Connection/pool defaults and semantics.
• Query metadata — Attach metadata visible in server logs/transactions.