Pooling

deep_db_agents.pooling

Client-side reuse of drivers that are already thread-safe connection pools.

The MongoDB (MongoClient), Neo4j (Driver), and Elasticsearch/OpenSearch drivers internally manage a connection pool and expose a thread-safe client object: recreating it on every tool call would pay an unnecessary TCP/TLS/auth handshake. LazyClient keeps a single instance per dialect (i.e. per agent), initialized lazily and in a thread-safe way.

DB-API 2.0 SQL drivers (pymysql, psycopg), on the other hand, remain connection-per-call: the connection is not thread-safe and tool calls may run in parallel.

LazyClient

LazyClient()

Thread-safe container for a reusable driver client, initialized on first use.

Initialize an empty, not-yet-built client container.

Source code in src/deep_db_agents/pooling.py

def __init__(self) -> None:
    """Initialize an empty, not-yet-built client container."""
    self._client: Any = None
    self._lock = threading.Lock()

close

close() -> None

Close and forget the client, if present (idempotent).

Returns:

Type	Description
None	None.

Source code in src/deep_db_agents/pooling.py

def close(self) -> None:
    """Close and forget the client, if present (idempotent).

    Returns:
        None.
    """
    with self._lock:
        client, self._client = self._client, None
    if client is not None and hasattr(client, "close"):
        client.close()

get

get(factory: Callable[[], Any]) -> Any

Return the cached client, building it with factory on the first call.

Parameters:

Name	Type	Description	Default
factory	Callable[[], Any]	Zero-argument callable that constructs the client. Only invoked once, on the first call to this method.	required

Returns:

Name	Type	Description
Any	Any	The cached (or newly built) client instance.

Source code in src/deep_db_agents/pooling.py

def get(self, factory: Callable[[], Any]) -> Any:
    """Return the cached client, building it with ``factory`` on the first call.

    Args:
        factory: Zero-argument callable that constructs the client. Only invoked
            once, on the first call to this method.

    Returns:
        Any: The cached (or newly built) client instance.
    """
    if self._client is None:
        with self._lock:
            if self._client is None:  # double-checked: build only once
                self._client = factory()
    return self._client