Connection Strings, Topology Discovery, Connection Pools, Server Selection, Timeouts, and Cancellation

Learning objectives

1. From URI to discovered topology

A MongoDB connection string is both an address and a contract. A seed list tells the driver where discovery can begin; replicaSet=atlasmart-rs27 tells it which logical replica set is acceptable; read preference, retry settings, TLS/authentication, and timeout options describe client behavior. After the first handshake, the driver does not simply round-robin seed hosts. Server Discovery and Monitoring (SDAM) maintains a changing topology description from hello/heartbeat information and server selection chooses a suitable member for each operation.

2. Build a three-member driver lab

docker rm -f atlasmart-rs27-lab 2>/dev/null || trueIMAGE=mongodb/mongodb-community-server:8.3.8-ubuntu2204-slimdocker run -d --name atlasmart-rs27-lab \  -p 127.0.0.1:27209:27209 -p 127.0.0.1:27210:27210 -p 127.0.0.1:27211:27211 \  --entrypoint bash "$IMAGE" -lc 'set -emkdir -p /data/rs1 /data/rs2 /data/rs3mongod --dbpath /data/rs1 --port 27209 --replSet atlasmart-rs27 --bind_ip_all --fork --logpath /tmp/rs1.logmongod --dbpath /data/rs2 --port 27210 --replSet atlasmart-rs27 --bind_ip_all --fork --logpath /tmp/rs2.logmongod --dbpath /data/rs3 --port 27211 --replSet atlasmart-rs27 --bind_ip_all --fork --logpath /tmp/rs3.logtail -f /dev/null'sleep 4docker exec atlasmart-rs27-lab mongosh --quiet --port 27209 --eval 'rs.initiate({_id:"atlasmart-rs27",members:[ {_id:0,host:"localhost:27209"}, {_id:1,host:"localhost:27210"}, {_id:2,host:"localhost:27211"}]})'docker exec atlasmart-rs27-lab mongosh --quiet --port 27209 --eval 'while (rs.status().members.filter(m=>m.stateStr==="PRIMARY").length!==1 || rs.status().members.filter(m=>m.stateStr==="SECONDARY").length!==2) { sleep(1000) }printjson(rs.status().members.map(m=>({name:m.name,state:m.stateStr})))' 

python -m venv .venv. .venv/bin/activate  # Windows PowerShell: .\.venv\Scripts\Activate.ps1python -m pip install "pymongo==4.17.0"

3. Make topology, commands, and pool state observable

PyMongo emits command, SDAM, and connection-pool events. Production listeners should emit structured, bounded telemetry and avoid logging credentials or sensitive command bodies. The following listener records event type, address, and command name only.

from pymongo import MongoClient, monitoringfrom pymongo.errors import PyMongoErrorclass Commands(monitoring.CommandListener):    def started(self, event): print("COMMAND start", event.command_name, event.connection_id)    def succeeded(self, event): print("COMMAND ok", event.command_name, round(event.duration_micros/1000,2), "ms")    def failed(self, event): print("COMMAND fail", event.command_name, event.failure)class Servers(monitoring.ServerListener):    def opened(self, event): print("SERVER opened", event.server_address)    def description_changed(self, event): print("SERVER", event.server_address, event.new_description.server_type_name)    def closed(self, event): print("SERVER closed", event.server_address)class Pools(monitoring.ConnectionPoolListener):    def pool_created(self,e): print("POOL created",e.address)    def pool_ready(self,e): print("POOL ready",e.address)    def pool_cleared(self,e): print("POOL cleared",e.address)    def pool_closed(self,e): print("POOL closed",e.address)    def connection_created(self,e): print("CONN created",e.connection_id)    def connection_ready(self,e): print("CONN ready",e.connection_id)    def connection_closed(self,e): print("CONN closed",e.connection_id,e.reason)    def connection_check_out_started(self,e): print("CHECKOUT start",e.address)    def connection_check_out_failed(self,e): print("CHECKOUT fail",e.address,e.reason)    def connection_checked_out(self,e): print("CHECKOUT ok",e.connection_id)    def connection_checked_in(self,e): print("CHECKIN",e.connection_id)uri=("mongodb://localhost:27209,localhost:27210,localhost:27211/"     "?replicaSet=atlasmart-rs27&retryWrites=true&w=majority")client=MongoClient(uri, serverSelectionTimeoutMS=5000, connectTimeoutMS=2000,                   maxPoolSize=8, minPoolSize=0, waitQueueTimeoutMS=1000,                   timeoutMS=3000,                   event_listeners=[Commands(),Servers(),Pools()])try:    print(client.admin.command("ping"))    print(client.admin.command({"getParameter":1,"featureCompatibilityVersion":1}))    print(client.topology_description.topology_type_name)finally:    client.close()

Expected shape: one replica-set topology, one primary, two secondaries, pool creation/checkout events, and command start/success events. Addresses and event interleaving are runtime evidence; do not hard-code an assumed primary.

4. Timeouts are a stack; client-side timeout is a budget

serverSelectionTimeoutMS bounds how long the driver looks for an eligible server. connectTimeoutMS bounds establishing an individual network connection. waitQueueTimeoutMS bounds waiting for a pool checkout. PyMongo client-side operation timeout (timeoutMS or pymongo.timeout()) applies a broader budget across selection, checkout, serialization, and server execution. Hidden stacks of long defaults can make a request violate an application deadline even when every individual subsystem is technically functioning.

from time import perf_counterfrom pymongo import MongoClientfrom pymongo.errors import ServerSelectionTimeoutErrorbad=MongoClient("mongodb://127.0.0.1:27999/?directConnection=true",                serverSelectionTimeoutMS=800, connectTimeoutMS=300, timeoutMS=1000)t0=perf_counter()try:    bad.admin.command("ping")except ServerSelectionTimeoutError as exc:    print(type(exc).__name__, round((perf_counter()-t0)*1000), "ms")finally:    bad.close()

5. Deliberately wrong: one MongoClient per web request

A MongoClient owns topology monitors and connection pools. Constructing one for every request multiplies handshakes, monitoring threads, sockets, TLS/auth work, and server load. The repair is a process-scoped client (or a deliberately bounded number of clients), application-level concurrency limits, and a pool sized from measured concurrency rather than “number of users.”

from concurrent.futures import ThreadPoolExecutorfrom threading import BoundedSemaphorefrom time import sleep, perf_counterslots=BoundedSemaphore(4)def request(i):    t0=perf_counter()    if not slots.acquire(timeout=.25): return i,"backpressured",perf_counter()-t0    try:        sleep(.08)  # stand-in for bounded DB work        return i,"done",perf_counter()-t0    finally: slots.release()with ThreadPoolExecutor(max_workers=20) as ex:    rows=list(ex.map(request,range(40)))print({s:sum(r[1]==s for r in rows) for s in {r[1] for r in rows}})

The semaphore is not the MongoDB pool; it is an application admission-control layer that prevents request concurrency from turning a full driver pool into an unbounded queue.

6. Production judgment

Use a small number of long-lived clients, explicit time budgets derived from request SLOs, bounded pools, observable checkout/selection events, and topology-aware URIs. Do not paper over overload by making every timeout and pool larger. Lesson 2 moves from resource acquisition to the harder question: what a driver may safely retry and what the application must deduplicate itself.

Authoritative references

Driver defaults and deployment behavior evolve. Re-check the exact server patch, PyMongo release, topology, and managed-service tier before freezing production assumptions.

• PyMongo driver documentation
• Connect to MongoDB with PyMongo
• PyMongo connection pools
• PyMongo client-side operation timeout
• PyMongo monitoring
• PyMongo CRUD configuration / retries
• PyMongo transactions
• PyMongo bulk writes
• PyMongo release notes
• MongoDB connection strings
• Connection string options
• Retryable writes
• Retryable reads
• Transactions
• Change streams
• cursor.skip() and range pagination
• Explain results
• Read concern
• Write concern
• Read preference
• Replica sets
• Sharding
• Choose a shard key
• Security checklist
• Backup methods
• serverStatus
• MongoDB 8.3 release notes
• mongosh changelog