litedbmodel-runtime 2.2.9__tar.gz → 2.2.11__tar.gz

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: litedbmodel-runtime
-Version: 2.2.9
+Version: 2.2.11
 Summary: Thin multi-language runtime for litedbmodel v2 SCP makeSQL bundles (Python port). Executes the published static-makeSQL artifacts (a read ReadGraph = a bc surrogate ComponentGraphIR + per-node static statement templates, or a gate-first TransactionPlan) against a SQL driver — semantics-identical to the TS reference. Delegates the Expression-IR evaluation + map/Φ/wiring orchestration to behavior-contracts.
 Author: foo-ogawa
 License: MIT
 Keywords: orm,sql,ir,runtime,conformance,litedbmodel
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: behavior-contracts==0.11.17
+Requires-Dist: behavior-contracts==0.11.20
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: livedb

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/litedbmodel_runtime/__init__.py

@@ -104,7 +104,7 @@ from .connection_routing import (
 )
 from .leaves import make_handlers, render_placeholders
 
-__version__ = "2.2.9"
+__version__ = "2.2.11"
 
 __all__ = [
     "__version__",

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/litedbmodel_runtime/connection_routing.py

@@ -15,7 +15,8 @@ A statement's connection is resolved in THIS priority (first match wins):
      DIFFERENT database than the tx opened on is REJECTED there rather than routed (Phase A;
      resolved by :class:`ExecutionContext` BEFORE the routing steps, since only it holds the pin).
   2. **writer scope / writer-sticky** — inside :func:`with_writer`, or within ``writer_sticky_duration``
-     after a transaction (read-your-writes), a READ goes to the WRITER pool (Phase C — here).
+     after a transaction the same chain committed (read-your-writes), a READ goes to the WRITER pool
+     (Phase C — here).
   3. **read=reader / write=writer** — otherwise a read → the reader pool, a write → the writer pool
      (reader/writer separation; single-pool config ⇒ reader IS writer, Phase C).
   4. **named-DB routing** — the target pool is selected by ``intent.db`` (the connection NAME) against
@@ -49,6 +50,8 @@ import time
 from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
 
 from .driver import (
+    DEFAULT_ACQUIRE_TIMEOUT_SECONDS,
+    DEFAULT_IDLE_TIMEOUT_SECONDS,
     RunInfo,
     TxConnection,
     _conn_all,
@@ -70,6 +73,8 @@ _DEFAULT_KEEP_ALIVE = False
 _DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS = 10000
 _DEFAULT_MIN_POOL = 0
 _DEFAULT_MAX_POOL = 10
+_DEFAULT_CONNECT_TIMEOUT_MS = int(DEFAULT_ACQUIRE_TIMEOUT_SECONDS * 1000)
+_DEFAULT_IDLE_TIMEOUT_MS = int(DEFAULT_IDLE_TIMEOUT_SECONDS * 1000)
 
 
 class ConnectionConfig:
@@ -91,6 +96,10 @@ class ConnectionConfig:
       - ``keep_alive_initial_delay_millis``: ms before the first keepalive probe (@default 10000).
       - ``min_pool``: minimum pooled connections kept warm (@default 0).
       - ``max_pool``: maximum pooled connections (@default 10).
+      - ``connect_timeout_millis``: upper bound in ms on getting a connection — opening a new one, and
+        waiting for a free one when the pool is at ``max_pool``. ``0`` ⇒ no limit (@default 30000).
+      - ``idle_timeout_millis``: ms an unused pooled connection stays open before it is closed
+        (@default 10000).
       - ``search_path``: PG ``search_path`` set on each pooled connection at checkout (schema routing).
       - ``charset``: MySQL connection charset / PG ``client_encoding`` set on each pooled connection.
     """
@@ -107,6 +116,8 @@ class ConnectionConfig:
         "keep_alive_initial_delay_millis",
         "min_pool",
         "max_pool",
+        "connect_timeout_millis",
+        "idle_timeout_millis",
         "search_path",
         "charset",
     )
@@ -126,6 +137,8 @@ class ConnectionConfig:
         max_pool: Optional[int] = None,
         search_path: Optional[str] = None,
         charset: Optional[str] = None,
+        connect_timeout_millis: Optional[int] = None,
+        idle_timeout_millis: Optional[int] = None,
     ) -> None:
         self.driver = driver
         self.host = host
@@ -140,12 +153,14 @@ class ConnectionConfig:
         self.max_pool = max_pool
         self.search_path = search_path
         self.charset = charset
+        self.connect_timeout_millis = connect_timeout_millis
+        self.idle_timeout_millis = idle_timeout_millis
 
 
 class ResolvedConnectionConfig:
     """The resolved (defaults-applied) config the pool builder consumes — no ``None`` holes on the
     knobs (``query_timeout`` / ``keep_alive`` / ``keep_alive_initial_delay_millis`` / ``min_pool`` /
-    ``max_pool`` are always concrete). Connection-target fields (``host`` … ``password``) and the
+    ``max_pool`` / ``connect_timeout_millis`` / ``idle_timeout_millis`` are always concrete). Connection-target fields (``host`` … ``password``) and the
     optional session knobs (``search_path`` / ``charset``) stay ``None`` when unset (so a factory omits
     them). Mirrors the TS ``ResolvedConnectionConfig``.
     """
@@ -162,6 +177,8 @@ class ResolvedConnectionConfig:
         "keep_alive_initial_delay_millis",
         "min_pool",
         "max_pool",
+        "connect_timeout_millis",
+        "idle_timeout_millis",
         "search_path",
         "charset",
     )
@@ -174,6 +191,8 @@ class ResolvedConnectionConfig:
         keep_alive_initial_delay_millis: int,
         min_pool: int,
         max_pool: int,
+        connect_timeout_millis: int,
+        idle_timeout_millis: int,
         host: Optional[str] = None,
         port: Optional[int] = None,
         database: Optional[str] = None,
@@ -188,6 +207,8 @@ class ResolvedConnectionConfig:
         self.keep_alive_initial_delay_millis = keep_alive_initial_delay_millis
         self.min_pool = min_pool
         self.max_pool = max_pool
+        self.connect_timeout_millis = connect_timeout_millis
+        self.idle_timeout_millis = idle_timeout_millis
         self.host = host
         self.port = port
         self.database = database
@@ -199,7 +220,8 @@ class ResolvedConnectionConfig:
 
 def resolve_connection_config(config: Optional[ConnectionConfig] = None) -> ResolvedConnectionConfig:
     """Apply the C3 defaults (``query_timeout=0``, ``keep_alive=False``,
-    ``keep_alive_initial_delay_millis=10000``, ``min_pool=0``, ``max_pool=10``, ``driver='postgres'``).
+    ``keep_alive_initial_delay_millis=10000``, ``min_pool=0``, ``max_pool=10``,
+    ``connect_timeout_millis=30000``, ``idle_timeout_millis=10000``, ``driver='postgres'``).
     Mirrors the TS ``resolveConnectionConfig`` — identical field names + defaults."""
     c = config if config is not None else ConnectionConfig()
     return ResolvedConnectionConfig(
@@ -218,6 +240,10 @@ def resolve_connection_config(config: Optional[ConnectionConfig] = None) -> Reso
         ),
         min_pool=c.min_pool if c.min_pool is not None else _DEFAULT_MIN_POOL,
         max_pool=c.max_pool if c.max_pool is not None else _DEFAULT_MAX_POOL,
+        connect_timeout_millis=(
+            c.connect_timeout_millis if c.connect_timeout_millis is not None else _DEFAULT_CONNECT_TIMEOUT_MS
+        ),
+        idle_timeout_millis=c.idle_timeout_millis if c.idle_timeout_millis is not None else _DEFAULT_IDLE_TIMEOUT_MS,
         search_path=c.search_path,
         charset=c.charset,
     )
@@ -610,11 +636,16 @@ def with_writer(fn: Callable[[], Any]) -> Any:
 
 
 class WriterStickyClock:
-    """A writer-sticky CLOCK (C1, read-your-writes; v1 ``_shouldUseWriterSticky`` + ``_lastTransactionTime``).
-    After a transaction (or a bare write) COMMITs, reads within ``sticky_duration_ms`` route to the
-    WRITER pool so a just-committed row is visible despite reader-replica lag. The ctx owns ONE clock
-    instance; the tx runtime :meth:`mark` s it on every successful write/commit; :func:`resolve_pool`
-    reads :meth:`is_sticky`.
+    """A writer-sticky CLOCK (C1, read-your-writes). After a transaction COMMITs, the reads of the
+    execution chain that committed route to the WRITER pool for ``writer_sticky_duration`` ms, so the
+    just-committed row is visible despite reader-replica lag. Other chains — concurrent requests on other
+    threads — keep reading from the reader: they did not write, so they have no lag to hide.
+
+    The chain is the current :mod:`contextvars` Context: each thread has its own, and a transaction body
+    runs in its caller's Context, so the tx runtime's :meth:`mark` after COMMIT is seen by the caller's
+    later reads and by no other thread. The clock is per routing config (per connection setup); the time
+    it holds is per chain, in a ``ContextVar`` this instance owns. :func:`resolve_pool` reads
+    :meth:`is_sticky`.
 
     ``use_writer_after_transaction=False`` disables it entirely (:meth:`is_sticky` always False). A
     single-pool deployment (reader IS writer) is unaffected — the diverted pool is the same object.
@@ -630,30 +661,32 @@ class WriterStickyClock:
         writer_sticky_duration: int = 5000,
         now: Optional[Callable[[], int]] = None,
     ) -> None:
-        # ``None`` until the first ``mark()`` — absence, NOT a value sentinel. The injectable clock
-        # legitimately returns 0 (rust's SystemClock does right after process start), so encoding
-        # "never marked" as the value 0 would mis-classify a ``mark()`` at clock t=0 as unmarked and
-        # leak the read-your-writes read to the reader replica. Absence must be distinct from value 0.
-        self._last_write_at: Optional[int] = None
+        # The current chain's last commit time: ``None`` until that chain's first ``mark()`` — absence,
+        # NOT a value sentinel. The injectable clock legitimately returns 0 (rust's SystemClock does right
+        # after process start), so encoding "never marked" as the value 0 would mis-classify a ``mark()``
+        # at clock t=0 as unmarked and leak the read-your-writes read to the reader replica.
+        self._last_write_at: "contextvars.ContextVar[Optional[int]]" = contextvars.ContextVar(
+            "litedbmodel_writer_sticky_last_write_at", default=None
+        )
         self._enabled = use_writer_after_transaction
         self._sticky_duration_ms = writer_sticky_duration
         # Default clock: monotonic ms (Date.now analogue). An injectable clock makes expiry deterministic.
         self._now: Callable[[], int] = now if now is not None else (lambda: int(time.monotonic() * 1000))
 
     def mark(self) -> None:
-        """Record that a write/commit just happened (the tx runtime calls this on success)."""
+        """Record that the current chain just committed (the tx runtime calls this on success)."""
         if self._enabled:
-            self._last_write_at = self._now()
+            self._last_write_at.set(self._now())
 
     def is_sticky(self) -> bool:
-        """Is a read currently sticky-to-writer (within ``writer_sticky_duration`` of the last write)?"""
-        if not self._enabled or self._last_write_at is None:
+        """Is a read in the current chain sticky-to-writer (within ``writer_sticky_duration`` of its
+        last commit)?"""
+        if not self._enabled:
             return False
-        return (self._now() - self._last_write_at) < self._sticky_duration_ms
-
-    def reset(self) -> None:
-        """Reset the clock (e.g. between tests / on :func:`close_all_pools`)."""
-        self._last_write_at = None
+        last = self._last_write_at.get()
+        if last is None:
+            return False
+        return (self._now() - last) < self._sticky_duration_ms
 
 
 # ── The routing config a ctx carries (C1+C2+C3) ────────────────────────────────
@@ -680,7 +713,8 @@ def resolve_pool(intent: StatementIntent, routing: RoutingConfig) -> ConnectionP
 
       1. **named-DB** (``intent.db``) selects the :class:`ReaderWriterPools` pair (loud on unknown name).
       2. within that pair: a WRITE ⇒ the writer pool.
-      3. a READ in a :func:`with_writer` scope OR within writer-sticky ⇒ the writer pool (read-your-writes).
+      3. a READ in a :func:`with_writer` scope OR within the current chain's writer-sticky window ⇒ the
+         writer pool (read-your-writes).
       4. otherwise a READ ⇒ the reader pool.
 
     Single-pool (reader IS writer) ⇒ every branch returns the same pool (backward-compat). Mirrors the
@@ -887,6 +921,31 @@ def close_all_pools(closers: Sequence[PoolCloser]) -> None:
 #   - min_pool: the dependency-free `_ConnectionPool` opens connections LAZILY up to `max_pool`; it has
 #     no warm-idle floor, so `min_pool` is a documented NO-OP for both drivers (same as mysql2's absent
 #     `min`). The SIZING CAP that matters — `max_pool` → the pool ceiling — IS honored at construction.
+#
+# ── connect_timeout_millis / idle_timeout_millis (both drivers) ──
+#   - The wait for a free connection at `max_pool` and the idle close are the `_ConnectionPool`'s own
+#     (`acquire_timeout` / `idle_timeout`), so both are millisecond-exact on PG and MySQL alike.
+#   - The connect itself is bounded by the driver's `connect_timeout`. PyMySQL takes fractional seconds.
+#     psycopg takes WHOLE seconds and raises anything under 2 to 2 (libpq's rule, which psycopg
+#     enforces in `conninfo.timeout_from_conninfo`), so on PG the connect bound is
+#     `max(2, ceil(connect_timeout_millis / 1000))` seconds.
+#   - `connect_timeout_millis = 0` is "no limit". The pool's wait honors it exactly. Neither driver can
+#     connect without a limit: psycopg reads a `connect_timeout` of 0 as its own 130s bound
+#     (`conninfo._DEFAULT_CONNECT_TIMEOUT`), and PyMySQL accepts only `0 < connect_timeout <= 31536000`,
+#     so 0 is passed to it as that maximum (one year).
+_PYMYSQL_MAX_CONNECT_TIMEOUT_SECONDS = 31536000
+
+
+def _pool(conn_factory: Callable[[], Any], config: ResolvedConnectionConfig) -> _ConnectionPool:
+    """The `_ConnectionPool` a factory builds: sized to ``max_pool`` (the SOLE cap source), waiting at
+    most ``connect_timeout_millis`` for a free connection (``0`` ⇒ no limit) and closing one unused for
+    ``idle_timeout_millis``."""
+    return _ConnectionPool(
+        conn_factory,
+        config.max_pool,
+        acquire_timeout=config.connect_timeout_millis / 1000.0 or None,
+        idle_timeout=config.idle_timeout_millis / 1000.0,
+    )
 
 
 def _pg_connect_kwargs(config: ResolvedConnectionConfig) -> Dict[str, Any]:
@@ -903,6 +962,9 @@ def _pg_connect_kwargs(config: ResolvedConnectionConfig) -> Dict[str, Any]:
         kwargs["user"] = config.user
     if config.password is not None:
         kwargs["password"] = config.password
+    # Whole seconds, rounded UP so the bound is never shorter than configured (psycopg raises < 2 to 2;
+    # 0 stays 0, which psycopg reads as its 130s default).
+    kwargs["connect_timeout"] = -(-config.connect_timeout_millis // 1000)
     if config.keep_alive:
         # libpq TCP keepalive (SECONDS for the idle delay; convert the ms knob, min 1s).
         kwargs["keepalives"] = 1
@@ -929,7 +991,7 @@ def pg_pool_factory() -> PoolFactory:
         def conn_factory() -> Any:
             return psycopg.connect(**kwargs)
 
-        raw = _ConnectionPool(conn_factory, config.max_pool)  # SIZING at construction: max_pool = the cap
+        raw = _pool(conn_factory, config)
         pool = RawConnectionPool(raw, _dollar_to_pyformat, emulate_returning=False)
         return pool, raw.close
 
@@ -948,6 +1010,7 @@ def _mysql_connect_kwargs(config: ResolvedConnectionConfig) -> Dict[str, Any]:
         kwargs["user"] = config.user
     if config.password is not None:
         kwargs["password"] = config.password
+    kwargs["connect_timeout"] = config.connect_timeout_millis / 1000.0 or _PYMYSQL_MAX_CONNECT_TIMEOUT_SECONDS
     # NB: PyMySQL exposes no TCP-keepalive connect option ⇒ keep_alive is a documented NO-OP on MySQL
     # (mirror the TS mysqlPoolFactory's "mysql2 has no min idle floor" per-driver deviation note).
     return kwargs
@@ -972,7 +1035,7 @@ def mysql_pool_factory() -> PoolFactory:
         def conn_factory() -> Any:
             return pymysql.connect(**kwargs)
 
-        raw = _ConnectionPool(conn_factory, config.max_pool)  # SIZING at construction: max_pool = the cap
+        raw = _pool(conn_factory, config)
         pool = RawConnectionPool(raw, _qmark_to_pyformat, emulate_returning=True)
         return pool, raw.close
 

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/litedbmodel_runtime/driver.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 import re
 import sqlite3
-from typing import Any, Callable, Dict, List, Protocol, Sequence, Tuple
+from typing import Any, Callable, Dict, List, Optional, Protocol, Sequence, Tuple
 
 
 # ── Row materialization: per-column-set dict builder (read-path hot loop, #63 §② perf) ──────────
@@ -248,119 +248,156 @@ class _SqliteTxConnection:
 # relations can each hold a live connection without starving.
 DEFAULT_POOL_SIZE = 16
 
-# Bound EVERY acquire so an UNREACHABLE / non-responding DB fails in FINITE time instead of hanging
-# (#225). `acquire` has two sub-waits, both bounded to this budget: the factory's TCP connect
-# (`connect_timeout`, set in the pg/mysql factories) and the wait for a released connection when the
-# pool is at capacity (`_free.get(timeout=…)`). 30s matches the established codebase default — the v1
-# pg/mysql drivers' `config.timeout || 30` (src/drivers/postgres.ts, src/drivers/mysql.ts) — and the
-# other runtimes' pool-library connect/acquire timeouts (rust sqlx ~30s / deadpool wait, go database/sql
-# Ping, TS pg `connectionTimeoutMillis`). Only Python hand-rolls its pool, so it must supply the bound
-# those libraries give the other four legs for free.
+# Bound EVERY acquire so an UNREACHABLE / non-responding DB fails in FINITE time instead of hanging.
+# `acquire` has two sub-waits, each bounded to this budget: the factory's connect (`connect_timeout`,
+# set in the pg/mysql factories) and the wait for a released connection when the pool is at capacity.
+# 30s is the codebase default (the v1 pg/mysql drivers' `config.timeout || 30`) and the
+# `connectTimeoutMillis` default of the connection config. Only Python hand-rolls its pool, so it supplies
+# the bound the other runtimes take from their pool libraries.
 DEFAULT_ACQUIRE_TIMEOUT_SECONDS = 30.0
 
+# How long a released connection may sit unused in the pool before the pool closes it — the
+# `idleTimeoutMillis` default of the connection config (and of the v1 pg/mysql drivers).
+DEFAULT_IDLE_TIMEOUT_SECONDS = 10.0
+
 
 class _ConnectionPool:
     """A minimal thread-safe, bounded pool of DB-API connections (dependency-free).
 
-    A bounded ``queue`` of live connections created lazily up to ``max_size``. ``acquire`` blocks
-    for a free connection (or opens a new one below the ceiling); ``release`` returns it. This keeps
-    the parallel-read seam dependency-free (no psycopg_pool / DBUtils needed) while giving each
-    concurrent sibling its own connection.
+    Connections are opened lazily up to ``max_size``. ``acquire`` hands out the most recently released
+    free connection, opens a new one below the ceiling, or waits — at most ``acquire_timeout`` seconds,
+    without limit when it is ``None`` — for a release or a freed slot. ``release`` returns a connection; one left unused for
+    ``idle_timeout`` seconds is closed by a timer (a daemon ``threading.Timer`` armed while free
+    connections exist), so a quiet application does not hold server sessions open. This keeps the
+    parallel-read seam dependency-free while giving each concurrent sibling its own connection.
     """
 
-    __slots__ = ("_factory", "_max", "_free", "_opened", "_lock", "_closed", "_acquire_timeout")
+    __slots__ = ("_factory", "_max", "_free", "_opened", "_cond", "_closed", "_acquire_timeout", "_idle_timeout", "_reaper")
 
-    def __init__(self, factory, max_size: int, acquire_timeout: float = DEFAULT_ACQUIRE_TIMEOUT_SECONDS) -> None:
-        import queue as _queue
+    def __init__(
+        self,
+        factory,
+        max_size: int,
+        acquire_timeout: Optional[float] = DEFAULT_ACQUIRE_TIMEOUT_SECONDS,
+        idle_timeout: float = DEFAULT_IDLE_TIMEOUT_SECONDS,
+    ) -> None:
         import threading as _threading
 
         self._factory = factory
         self._max = max_size
-        self._free: "Any" = _queue.LifoQueue()
+        # Free connections with the monotonic time each was released, oldest first: ``acquire`` takes
+        # from the end (most recently used), the idle timer closes from the front.
+        self._free: List[Tuple[Any, float]] = []
         self._opened = 0
-        self._lock = _threading.Lock()
-        # The bound on the at-capacity wait for a released connection (see acquire). Finite so an
-        # exhausted pool that will never be replenished (e.g. every open failed) raises instead of
-        # blocking forever (#225).
+        self._cond = _threading.Condition()
         self._acquire_timeout = acquire_timeout
-        # Fail-fast after close(): a post-close acquire must RAISE, not block forever on `_free.get()`
-        # (the pool is drained and nothing will be released). Additive — the Phase A/B paths never
-        # acquire after close, so behavior there is unchanged; Phase C's close_all_pools relies on it so
-        # a query on a closed pool fails loudly (mirror the TS pool.end() → query rejects).
+        self._idle_timeout = idle_timeout
+        self._reaper: Any = None
+        # Fail-fast after close(): a post-close acquire RAISES instead of waiting on a drained pool
+        # (close_all_pools relies on it so a query on a closed pool fails loudly).
         self._closed = False
 
     def acquire(self) -> Any:
-        import queue as _queue
-
-        if self._closed:
-            raise RuntimeError("scp connection pool: acquire after close (the pool has been closed)")
-        # Fast path: reuse a free connection.
-        try:
-            return self._free.get_nowait()
-        except _queue.Empty:
-            pass
-        # Reserve a slot if below the ceiling, then open OUTSIDE the lock (a slow/blocked connect must
-        # not serialize every other acquire/release on this pool).
-        reserved = False
-        with self._lock:
-            if self._closed:
-                raise RuntimeError("scp connection pool: acquire after close (the pool has been closed)")
-            if self._opened < self._max:
-                self._opened += 1
-                reserved = True
-        if reserved:
-            try:
-                return self._factory()
-            except BaseException:
-                # The open FAILED — RELEASE the reserved slot (mirror `discard`'s decrement). Without
-                # this a failed connect permanently consumes capacity; once `_opened` hits the ceiling
-                # every later acquire falls through to the wait below with no connection ever coming, so
-                # an unreachable DB turns each fast connect-refused into an unbounded hang (#225).
-                with self._lock:
-                    self._opened -= 1
-                raise
-        # Pool at capacity: wait for a released connection, but BOUND the wait. An unbounded get() hangs
-        # forever when nothing will ever be released; on timeout raise a clear error instead (#225 — the
-        # parity target: the other runtimes' pool libraries bound this acquire wait).
+        import time as _time
+
+        deadline = None if self._acquire_timeout is None else _time.monotonic() + self._acquire_timeout
+        with self._cond:
+            while True:
+                if self._closed:
+                    raise RuntimeError("scp connection pool: acquire after close (the pool has been closed)")
+                if self._free:
+                    return self._free.pop()[0]
+                if self._opened < self._max:
+                    # Reserve the slot, then open OUTSIDE the lock (a slow connect must not serialize
+                    # every other acquire/release on this pool).
+                    self._opened += 1
+                    break
+                # At capacity: wait for a release (or a discarded/closed slot), bounded by the deadline
+                # when there is one.
+                remaining = None if deadline is None else deadline - _time.monotonic()
+                if remaining is not None and remaining <= 0:
+                    raise TimeoutError(
+                        f"scp connection pool: acquire timed out after {self._acquire_timeout}s "
+                        f"(pool at capacity {self._max}, no connection released)"
+                    )
+                self._cond.wait(remaining)
         try:
-            return self._free.get(timeout=self._acquire_timeout)
-        except _queue.Empty:
-            raise TimeoutError(
-                f"scp connection pool: acquire timed out after {self._acquire_timeout}s "
-                f"(pool at capacity {self._max}, no connection released)"
-            ) from None
+            return self._factory()
+        except BaseException:
+            # The open FAILED — give the reserved slot back. Without this a failed connect permanently
+            # consumes capacity, and once every slot is consumed each later acquire waits for a
+            # connection that never comes.
+            self._free_slots(1)
+            raise
 
     def release(self, conn: Any) -> None:
-        self._free.put(conn)
+        import time as _time
+
+        with self._cond:
+            if not self._closed:
+                self._free.append((conn, _time.monotonic()))
+                self._cond.notify()
+                self._arm_reaper()
+                return
+        _close_quietly(conn)  # released after close(): nothing will hand it out again
 
     def discard(self, conn: Any) -> None:
         """Permanently drop a POISONED connection (a tx whose COMMIT/ROLLBACK itself raised): close it
-        and DECREMENT the opened count so a fresh connection can be opened in its place. Without the
-        decrement the pool's ``_opened < _max`` ceiling would count the dead connection forever and
-        capacity would shrink by one per discard — eventual exhaustion under repeated commit failures
-        (the deeper half of the #78 leak: releasing wasn't enough; the destroy path must re-open a slot).
-        """
-        try:
-            conn.close()
-        except Exception:
-            pass
-        with self._lock:
-            if self._opened > 0:
-                self._opened -= 1
+        and free its slot so a fresh connection can be opened in its place — otherwise capacity would
+        shrink by one per discard until the pool is exhausted."""
+        _close_quietly(conn)
+        self._free_slots(1)
 
     def close(self) -> None:
-        import queue as _queue
-
-        self._closed = True  # fail-fast: a subsequent acquire raises instead of blocking on a drained pool
-        while True:
-            try:
-                conn = self._free.get_nowait()
-            except _queue.Empty:
-                break
-            try:
-                conn.close()
-            except Exception:
-                pass
+        with self._cond:
+            self._closed = True
+            free, self._free = self._free, []
+            if self._reaper is not None:
+                self._reaper.cancel()
+                self._reaper = None
+            self._cond.notify_all()  # waiters raise "acquire after close" instead of timing out
+        for conn, _ in free:
+            _close_quietly(conn)
+
+    def _free_slots(self, n: int) -> None:
+        with self._cond:
+            self._opened = max(0, self._opened - n)
+            self._cond.notify(n)  # a waiter may now open a connection in a freed slot
+
+    def _arm_reaper(self) -> None:
+        """(Under the lock.) Arm the idle timer for the oldest free connection, unless it is armed."""
+        import threading as _threading
+        import time as _time
+
+        if self._reaper is not None or not self._free or self._closed:
+            return
+        delay = max(0.0, self._free[0][1] + self._idle_timeout - _time.monotonic())
+        self._reaper = _threading.Timer(delay, self._reap)
+        self._reaper.daemon = True
+        self._reaper.start()
+
+    def _reap(self) -> None:
+        """Close every free connection that has been unused for ``idle_timeout``, then re-arm."""
+        import time as _time
+
+        with self._cond:
+            self._reaper = None
+            cutoff = _time.monotonic() - self._idle_timeout
+            expired = [c for c, at in self._free if at <= cutoff]
+            self._free = [(c, at) for c, at in self._free if at > cutoff]
+            self._opened = max(0, self._opened - len(expired))
+            self._cond.notify(len(expired))
+            self._arm_reaper()
+        for conn in expired:
+            _close_quietly(conn)
+
+
+def _close_quietly(conn: Any) -> None:
+    try:
+        conn.close()
+    except Exception:
+        pass
+
 
 # `$1`, `$2`, … (Postgres render output).
 _DOLLAR_RE = re.compile(r"\$\d+")

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/litedbmodel_runtime/exec_context.py

@@ -413,7 +413,8 @@ class ExecutionContext:
 
     def mark_sticky(self) -> None:
         """Mark the writer-sticky clock (Phase C-1, read-your-writes): the tx runtime calls this on a
-        successful COMMIT so subsequent reads within ``writer_sticky_duration`` route to the writer pool.
+        successful COMMIT so the current chain's (this Context's) subsequent reads within
+        ``writer_sticky_duration`` route to the writer pool; other threads keep reading from the reader.
         A no-op on the single-driver path (no routing ⇒ no sticky clock)."""
         if self._routing is not None:
             self._routing.sticky.mark()

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/litedbmodel_runtime.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: litedbmodel-runtime
-Version: 2.2.9
+Version: 2.2.11
 Summary: Thin multi-language runtime for litedbmodel v2 SCP makeSQL bundles (Python port). Executes the published static-makeSQL artifacts (a read ReadGraph = a bc surrogate ComponentGraphIR + per-node static statement templates, or a gate-first TransactionPlan) against a SQL driver — semantics-identical to the TS reference. Delegates the Expression-IR evaluation + map/Φ/wiring orchestration to behavior-contracts.
 Author: foo-ogawa
 License: MIT
 Keywords: orm,sql,ir,runtime,conformance,litedbmodel
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: behavior-contracts==0.11.17
+Requires-Dist: behavior-contracts==0.11.20
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: livedb

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/litedbmodel_runtime.egg-info/requires.txt

@@ -1,4 +1,4 @@
-behavior-contracts==0.11.17
+behavior-contracts==0.11.20
 
 [livedb]
 psycopg[binary]>=3.1

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "litedbmodel-runtime"
-version = "2.2.9"
+version = "2.2.11"
 description = "Thin multi-language runtime for litedbmodel v2 SCP makeSQL bundles (Python port). Executes the published static-makeSQL artifacts (a read ReadGraph = a bc surrogate ComponentGraphIR + per-node static statement templates, or a gate-first TransactionPlan) against a SQL driver — semantics-identical to the TS reference. Delegates the Expression-IR evaluation + map/Φ/wiring orchestration to behavior-contracts."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -16,7 +16,7 @@ keywords = ["orm", "sql", "ir", "runtime", "conformance", "litedbmodel"]
 # evaluation (ref/refOpt/coalesce/eq/… — the SKIP guards + param slots) to the shared common
 # core, exactly as the TS reference imports `behavior-contracts` from npm. HARD dependency,
 # consumed from the published PyPI registry (NO local path — the no-local-deps gate forbids it).
-dependencies = ["behavior-contracts==0.11.17"]
+dependencies = ["behavior-contracts==0.11.20"]
 
 [project.optional-dependencies]
 test = ["pytest>=7.0"]

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/tests/test_connection_routing.py

@@ -77,7 +77,11 @@ def test_resolve_connection_config_defaults():
     assert r.keep_alive_initial_delay_millis == 10000
     assert r.min_pool == 0
     assert r.max_pool == 10
+    assert r.connect_timeout_millis == 30000
+    assert r.idle_timeout_millis == 10000
     assert r.search_path is None and r.charset is None
+    r3 = resolve_connection_config(ConnectionConfig(connect_timeout_millis=250, idle_timeout_millis=400))
+    assert (r3.connect_timeout_millis, r3.idle_timeout_millis) == (250, 400)
     # Overrides pass through with the same field names.
     r2 = resolve_connection_config(
         ConnectionConfig(driver="mysql", max_pool=2, min_pool=1, query_timeout=250, keep_alive=True, search_path="app", charset="utf8mb4")
@@ -219,9 +223,6 @@ def test_writer_sticky_clock_expiry_deterministic():
     assert c.is_sticky() is True  # 400ms < 1000ms window
     clock["t"] = 1600
     assert c.is_sticky() is False  # 1100ms ≥ window
-    c.reset()
-    clock["t"] = 1700
-    assert c.is_sticky() is False
 
 
 def test_writer_sticky_armed_at_clock_zero():
@@ -240,6 +241,60 @@ def test_writer_sticky_armed_at_clock_zero():
     assert resolve_pool(StatementIntent(write=False), routing) is writer  # read-your-writes → writer
 
 
+def test_writer_sticky_is_per_thread():
+    # Two threads alive at the same time on ONE routing config: A commits (marks), B does not. A's reads
+    # go to the writer; B's reads — before AND after A's mark, while A is still in its window — stay on
+    # the reader. A second clock on another routing config is not armed by A's mark.
+    import threading
+
+    reader, writer = _FakePool("reader"), _FakePool("writer")
+    sticky = WriterStickyClock(use_writer_after_transaction=True, writer_sticky_duration=5000, now=lambda: 1_000_000)
+    other = WriterStickyClock(use_writer_after_transaction=True, writer_sticky_duration=5000, now=lambda: 1_000_000)
+    routing = _routing(reader, writer, sticky=sticky)
+    b_first, a_marked, b_checked = (threading.Barrier(2, timeout=10) for _ in range(3))
+    seen, errors = {}, []
+
+    def read():
+        return resolve_pool(StatementIntent(write=False), routing).label
+
+    def thread_a():
+        b_first.wait()  # B has read once, before this mark
+        sticky.mark()
+        seen["a_after_mark"] = read()
+        seen["other_armed"] = other.is_sticky()
+        a_marked.wait()
+        b_checked.wait()
+        seen["a_later"] = read()
+
+    def thread_b():
+        seen["b_before"] = read()
+        b_first.wait()
+        a_marked.wait()
+        seen["b_after"] = read()
+        b_checked.wait()
+
+    def guarded(fn):
+        def body():
+            try:
+                fn()
+            except BaseException as e:  # surfaced below: a thread's exception never fails pytest itself
+                errors.append(e)
+
+        return body
+
+    threads = [threading.Thread(target=guarded(f)) for f in (thread_a, thread_b)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(10)
+    assert not any(t.is_alive() for t in threads) and errors == []
+    assert seen["a_after_mark"] == "writer"  # the committing thread reads its own write from the writer
+    assert seen["other_armed"] is False  # a mark on one clock does not arm another clock
+    assert seen["a_later"] == "writer"  # still within the window on the committing thread
+    assert (seen["b_before"], seen["b_after"]) == ("reader", "reader")  # the concurrent thread did not commit
+    assert sticky.is_sticky() is False  # the test thread never committed
+
+
 # ── C3: configured_pool session apply/reset (no session leak) — fake conn ────────
 
 
@@ -479,3 +534,46 @@ def test_acquire_wait_succeeds_when_a_connection_is_released_in_time():
     releaser.join()
     assert got is held  # the SAME connection came back through the wait
     assert time.monotonic() - t0 < 5.0
+
+
+def test_connect_timeout_reaches_both_drivers_connect():
+    """``connect_timeout_millis`` bounds the driver's own connect: PyMySQL takes fractional seconds,
+    psycopg whole seconds (rounded UP, so the bound is never shorter than configured); 0 is no limit."""
+    from litedbmodel_runtime.connection_routing import _mysql_connect_kwargs, _pg_connect_kwargs
+
+    pg = resolve_connection_config(ConnectionConfig(driver="postgres", connect_timeout_millis=2500))
+    my = resolve_connection_config(ConnectionConfig(driver="mysql", connect_timeout_millis=2500))
+    assert _pg_connect_kwargs(pg)["connect_timeout"] == 3
+    assert _mysql_connect_kwargs(my)["connect_timeout"] == 2.5
+    # 0 ⇒ no limit: psycopg's own reading of 0, and PyMySQL's largest accepted value.
+    pg0 = resolve_connection_config(ConnectionConfig(driver="postgres", connect_timeout_millis=0))
+    my0 = resolve_connection_config(ConnectionConfig(driver="mysql", connect_timeout_millis=0))
+    assert _pg_connect_kwargs(pg0)["connect_timeout"] == 0
+    assert _mysql_connect_kwargs(my0)["connect_timeout"] == 31536000
+
+
+def test_idle_connection_is_closed_by_the_pool():
+    """A released connection left unused for ``idle_timeout`` is closed and its slot freed, with no
+    acquire needed to notice; a connection that is still checked out is not touched."""
+    import time
+
+    from litedbmodel_runtime.driver import _ConnectionPool
+
+    class _Conn:
+        closed = False
+
+        def close(self):
+            self.closed = True
+
+    pool = _ConnectionPool(_Conn, max_size=2, idle_timeout=0.2)
+    idle, held = pool.acquire(), pool.acquire()
+    pool.release(idle)
+    deadline = time.monotonic() + 5.0
+    while not idle.closed and time.monotonic() < deadline:
+        time.sleep(0.02)
+    assert idle.closed and not held.closed
+    assert pool._opened == 1 and pool._free == []  # the idle one's slot is free again
+    pool.release(held)
+    assert pool.acquire() is held  # reused before its idle time ran out ⇒ still open
+    assert not held.closed
+    pool.close()

{litedbmodel_runtime-2.2.9 → litedbmodel_runtime-2.2.11}/tests/test_connection_routing_livedb.py

@@ -323,6 +323,228 @@ def test_c1_with_writer_scope():
         raw.close()
 
 
+# ════════════════════════════════════════════════════════════════════════════════
+# C1 — the same routing under REAL concurrent threads (PG + MySQL)
+# ════════════════════════════════════════════════════════════════════════════════
+
+# Per dialect: the table, the placeholder style, the server-side session id, a server-side sleep, and the
+# tx dialect name. Each test runs the SAME scenario on both servers.
+_DIALECTS = {
+    "postgres": dict(
+        setup=_setup_pg,
+        raw=_pg_raw_pool,
+        factory=pg_pool_factory,
+        config=_pg_conn_config,
+        session_alive="SELECT count(*) FROM pg_stat_activity WHERE pid = %s",
+        pool=_pg_pool,
+        insert="INSERT INTO %s (id, val) VALUES ($1, $2)" % TBL,
+        select_ids="SELECT id FROM %s WHERE id >= $1 AND id < $2 ORDER BY id" % TBL,
+        select_val="SELECT val FROM %s WHERE id = $1" % TBL,
+        session_id="SELECT pg_backend_pid() AS sid",
+        sleep="SELECT pg_sleep(0.05) AS d",
+    ),
+    "mysql": dict(
+        setup=_setup_my,
+        raw=_my_raw_pool,
+        factory=mysql_pool_factory,
+        config=_my_conn_config,
+        session_alive="SELECT COUNT(*) FROM information_schema.PROCESSLIST WHERE ID = %s",
+        pool=_my_pool,
+        insert="INSERT INTO %s (id, val) VALUES (?, ?)" % MY_TBL,
+        select_ids="SELECT id FROM %s WHERE id >= ? AND id < ? ORDER BY id" % MY_TBL,
+        select_val="SELECT val FROM %s WHERE id = ?" % MY_TBL,
+        session_id="SELECT CONNECTION_ID() AS sid",
+        sleep="SELECT SLEEP(0.05) AS d",
+    ),
+}
+
+_READ = StatementIntent(write=False)
+_WRITE = StatementIntent(write=True)
+
+
+class _ThreadLog:
+    """A ``_RecordingPool`` log that files each acquire under the thread that made it, so a test can
+    say WHICH thread's statement was served by which pool."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self.by_thread = {}
+
+    def append(self, label):
+        with self._lock:
+            self.by_thread.setdefault(threading.current_thread().name, []).append(label)
+
+    def last(self, name):
+        with self._lock:
+            return self.by_thread[name][-1]
+
+
+def _run_threads(targets, timeout=60):
+    """Start one named thread per ``(name, fn)``, all at once, and join them. A thread that is still
+    alive after ``timeout`` is a hang (deadlock / lost wake-up); an exception in any thread fails the
+    test (a bare ``threading.Thread`` would only print it). Returns ``{name: fn's return value}``."""
+    results, errors = {}, []
+
+    def wrap(name, fn):
+        def body():
+            try:
+                results[name] = fn()
+            except BaseException as e:
+                errors.append((name, e))
+
+        return body
+
+    threads = [threading.Thread(target=wrap(n, f), name=n) for n, f in targets]
+    for t in threads:
+        t.start()
+    deadline = time.monotonic() + timeout
+    for t in threads:
+        t.join(max(0.0, deadline - time.monotonic()))
+    hung = [t.name for t in threads if t.is_alive()]
+    assert hung == [], "threads still running after %ss (hang): %r" % (timeout, hung)
+    assert errors == [], "thread failures: %r" % errors
+    return results
+
+
+def test_c1_writer_sticky_is_per_thread_live():
+    """Writer-sticky is read-your-writes for the thread that committed. One thread commits and then reads
+    (→ WRITER, and it sees its row); five other threads, alive at the same time, read inside that same
+    sticky window (→ READER, each of them). On PG and on MySQL, with two distinct pools."""
+    for name, d in _DIALECTS.items():
+        raw = d["setup"]()
+        try:
+            tlog = _ThreadLog()
+            reader = _RecordingPool(d["pool"](raw), "reader", tlog)
+            writer = _RecordingPool(d["pool"](raw), "writer", tlog)
+            # A 60s window: every read below happens inside it, however slow the machine.
+            sticky = WriterStickyClock(use_writer_after_transaction=True, writer_sticky_duration=60_000)
+            ctx = _ctx(RoutingConfig(ConnectionRegistry.from_default(reader_writer_pair(reader, writer)).build(), sticky))
+            readers = ["reader-%d" % i for i in range(5)]
+            started = threading.Barrier(1 + len(readers), timeout=30)
+            committed = threading.Event()
+            read_done = threading.Barrier(1 + len(readers), timeout=30)
+
+            def committer():
+                started.wait()
+                transaction(ctx, lambda: run_guarded(current_context(), d["insert"], [100, "mine"], "INSERT"), TransactionOptions(), name)
+                committed.set()
+                first = execute(ctx, d["select_val"], [100], _READ)
+                first_pool = tlog.last("committer")
+                read_done.wait()  # the other threads have read inside the window
+                later = execute(ctx, d["select_val"], [100], _READ)
+                return first, first_pool, later, tlog.last("committer")
+
+            def other(me):
+                def body():
+                    started.wait()
+                    assert committed.wait(30)
+                    execute(ctx, "SELECT 1 AS one", [], _READ)
+                    pool = tlog.last(me)
+                    read_done.wait()
+                    return pool
+
+                return body
+
+            res = _run_threads([("committer", committer)] + [(r, other(r)) for r in readers])
+            first, first_pool, later, later_pool = res["committer"]
+            assert (first_pool, later_pool) == ("writer", "writer"), name
+            assert first[0]["val"] == "mine" and later[0]["val"] == "mine", name
+            assert {r: res[r] for r in readers} == {r: "reader" for r in readers}, name
+            assert sticky.is_sticky() is False, name  # the test's own thread never committed
+        finally:
+            raw.close()
+
+
+def test_c1_concurrent_transactions_each_own_a_connection():
+    """Four threads hold a transaction open at the same time while a fifth runs plain statements. Each
+    transaction is on its own server session and sees only its own uncommitted row; the fifth thread's
+    statements run on none of those sessions and see none of those rows. After COMMIT every row is
+    there. On PG and on MySQL."""
+    for name, d in _DIALECTS.items():
+        raw = d["setup"]()
+        try:
+            ctx = _ctx(RoutingConfig(ConnectionRegistry.single_default(d["pool"](raw)), WriterStickyClock(use_writer_after_transaction=False)))
+            ids = [200, 201, 202, 203]
+            all_open = threading.Barrier(len(ids) + 1, timeout=30)
+            checked = threading.Barrier(len(ids) + 1, timeout=30)
+
+            def tx_thread(my_id):
+                def body():
+                    tx_ctx = current_context()
+                    run_guarded(tx_ctx, d["insert"], [my_id, "tx"], "INSERT")
+                    sid = execute(tx_ctx, d["session_id"], [], _READ)[0]["sid"]
+                    all_open.wait()  # every transaction is open and has written, none committed
+                    seen = [int(r["id"]) for r in execute(tx_ctx, d["select_ids"], [200, 300], _READ)]
+                    checked.wait()
+                    return sid, seen
+
+                return lambda: transaction(ctx, body, TransactionOptions(), name)
+
+            def outside():
+                assert current_context() is None  # another thread's tx pin is not visible here
+                all_open.wait()
+                sid = execute(ctx, d["session_id"], [], _READ)[0]["sid"]
+                seen = [int(r["id"]) for r in execute(ctx, d["select_ids"], [200, 300], _READ)]
+                checked.wait()
+                return sid, seen
+
+            res = _run_threads([("tx-%d" % i, tx_thread(i)) for i in ids] + [("outside", outside)])
+            tx_sids = [res["tx-%d" % i][0] for i in ids]
+            assert len(set(tx_sids)) == len(ids), "%s: concurrent transactions shared a session: %r" % (name, tx_sids)
+            for i in ids:
+                assert res["tx-%d" % i][1] == [i], "%s: tx %d saw %r" % (name, i, res["tx-%d" % i][1])
+            out_sid, out_seen = res["outside"]
+            assert out_sid not in tx_sids, "%s: a non-tx statement ran on a transaction's connection" % name
+            assert out_seen == [], "%s: a non-tx read saw uncommitted rows %r" % (name, out_seen)
+            committed = [int(r["id"]) for r in execute(ctx, d["select_ids"], [200, 300], _READ)]
+            assert committed == ids, name
+        finally:
+            raw.close()
+
+
+def test_c1_pool_contention_waits_then_succeeds():
+    """More threads than connections: twelve threads (six transactions, six plain reads) on a pool of
+    TWO. Every acquire past the second waits for a release and then succeeds — no hang, no lost result,
+    never more than two connections open. On PG and on MySQL."""
+    for name, d in _DIALECTS.items():
+        d["setup"]().close()  # a fresh table
+        raw = d["raw"](size=2)
+        try:
+            ctx = _ctx(RoutingConfig(ConnectionRegistry.single_default(d["pool"](raw)), WriterStickyClock(use_writer_after_transaction=False)))
+            peak = {"v": 0}
+            lock = threading.Lock()
+
+            def observe():
+                with lock:
+                    peak["v"] = max(peak["v"], raw._opened)
+
+            def tx_thread(my_id):
+                def body():
+                    tx_ctx = current_context()
+                    run_guarded(tx_ctx, d["insert"], [my_id, "c%d" % my_id], "INSERT")
+                    execute(tx_ctx, d["sleep"], [], _READ)  # hold the connection so others must wait
+                    observe()
+                    return execute(tx_ctx, d["select_val"], [my_id], _READ)[0]["val"]
+
+                return lambda: transaction(ctx, body, TransactionOptions(), name)
+
+            def reader_thread():
+                execute(ctx, d["sleep"], [], _READ)
+                observe()
+                return int(execute(ctx, "SELECT 1 AS one", [], _READ)[0]["one"])
+
+            tx_ids = list(range(300, 306))
+            targets = [("tx-%d" % i, tx_thread(i)) for i in tx_ids] + [("read-%d" % i, reader_thread) for i in range(6)]
+            res = _run_threads(targets, timeout=60)
+            assert {i: res["tx-%d" % i] for i in tx_ids} == {i: "c%d" % i for i in tx_ids}, name
+            assert [res["read-%d" % i] for i in range(6)] == [1] * 6, name
+            assert peak["v"] <= 2 and raw._opened <= 2, "%s: pool of 2 opened %d" % (name, peak["v"])
+            committed = [int(r["id"]) for r in execute(ctx, d["select_ids"], [300, 400], _READ)]
+            assert committed == tx_ids, name
+        finally:
+            raw.close()
+
+
 # ════════════════════════════════════════════════════════════════════════════════
 # C2 — multi-DB name routing (PG = A, MySQL = B) + tx-pin precedence
 # ════════════════════════════════════════════════════════════════════════════════
@@ -603,3 +825,99 @@ def test_c3_pg_and_mysql_factories_end_to_end():
     mr = execute(mctx, "SELECT 13 AS n", [], StatementIntent(write=False))
     assert int(mr[0]["n"]) == 13
     my_close()
+
+
+def _built(d, **knobs):
+    """Build a routing config through the dialect's SHIPPED factory with ``knobs`` set on its
+    connection config, and capture the ``_ConnectionPool`` the factory constructed."""
+    captured = {}
+    base = d["factory"]()
+
+    def factory(config, role):
+        pool, close = base(config, role)
+        captured["raw"] = pool._pool
+        return pool, close
+
+    config = d["config"]()
+    for k, v in knobs.items():
+        setattr(config, k, v)
+    routing, close = build_routing_config([ConnectionSetup(pool_factory=factory, config=config)])
+    return _ctx(routing), captured["raw"], close
+
+
+def test_c3_connect_timeout_bounds_the_wait_for_a_free_connection():
+    """With the pool at ``max_pool`` and nothing released, getting a connection fails after
+    ``connect_timeout_millis`` — not sooner, and not never. Once a connection is released the same
+    statement succeeds. On PG and on MySQL, through the shipped factories."""
+    for name, d in _DIALECTS.items():
+        ctx, raw, close = _built(d, max_pool=1, connect_timeout_millis=400)
+        try:
+            held = raw.acquire()  # the only connection is checked out
+            t0 = time.monotonic()
+            with pytest.raises(TimeoutError, match="acquire timed out after 0.4s"):
+                execute(ctx, "SELECT 1 AS one", [], _READ)
+            elapsed = time.monotonic() - t0
+            assert 0.4 <= elapsed < 3.0, "%s: waited %.2fs for a 400ms bound" % (name, elapsed)
+            raw.release(held)
+            assert int(execute(ctx, "SELECT 1 AS one", [], _READ)[0]["one"]) == 1, name
+        finally:
+            close()
+
+
+
+def test_c3_connect_timeout_zero_waits_without_limit():
+    """``connect_timeout_millis=0`` is no limit: with the pool exhausted, a statement keeps waiting —
+    well past any short bound — and completes once the connection is released. On PG and on MySQL,
+    through the shipped factories."""
+    for name, d in _DIALECTS.items():
+        ctx, raw, close = _built(d, max_pool=1, connect_timeout_millis=0)
+        try:
+            held = raw.acquire()
+            got = {}
+
+            def waiter():
+                got["one"] = int(execute(ctx, "SELECT 1 AS one", [], _READ)[0]["one"])
+
+            t = threading.Thread(target=waiter)
+            t.start()
+            t.join(1.5)
+            assert t.is_alive() and got == {}, "%s: the waiter gave up with no limit configured" % name
+            raw.release(held)
+            t.join(30)
+            assert not t.is_alive() and got == {"one": 1}, name
+        finally:
+            close()
+
+
+def test_c3_idle_connection_is_closed_on_the_server():
+    """A pooled connection unused for ``idle_timeout_millis`` is closed — its server session is gone
+    (checked from a separate connection), with no further query needed — and the next statement opens
+    a new session. On PG and on MySQL, through the shipped factories."""
+    for name, d in _DIALECTS.items():
+        ctx, raw, close = _built(d, idle_timeout_millis=300)
+        probe = d["raw"](size=1)
+        try:
+
+            def alive(sid):
+                conn = probe.acquire()
+                try:
+                    cur = conn.cursor()
+                    cur.execute(d["session_alive"], [sid])
+                    n = cur.fetchone()[0]
+                    cur.close()
+                    return int(n)
+                finally:
+                    probe.release(conn)
+
+            sid = execute(ctx, d["session_id"], [], _READ)[0]["sid"]
+            assert raw._opened == 1 and alive(sid) == 1, name
+            deadline = time.monotonic() + 5.0
+            while alive(sid) and time.monotonic() < deadline:
+                time.sleep(0.05)
+            assert alive(sid) == 0, "%s: the idle session %s is still open on the server" % (name, sid)
+            assert raw._opened == 0, name
+            again = execute(ctx, d["session_id"], [], _READ)[0]["sid"]
+            assert again != sid, name
+        finally:
+            probe.close()
+            close()