matrx-orm 3.1.78__tar.gz → 3.1.79__tar.gz

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.78
+Version: 3.1.79
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/matrx_orm/core/FEATURE.md

@@ -36,7 +36,12 @@ labels (`unique`, `foreign_key`, `not_null`, `check`, `exclusion`, and
 It is diagnostic and intentionally verbose, so a known PostgreSQL error must
 never reach that fallback.
 
-Verified against code: 2026-08-09.
+`QueryTimeoutError` diagnoses by SQL verb. A fresh `INSERT` points first to a
+relation/DDL lock convoy, FK parent lock, or trigger work—not same-row fan-out.
+`UPDATE`/`DELETE` retain the hot-row diagnosis while also naming a database-wide
+DDL convoy when unrelated relations fail in the same window.
+
+Verified against code: 2026-08-17.
 
 ## Pool recovery
 
@@ -68,10 +73,15 @@ as `releasing` until reset really finishes. If reset exceeds the bound, asyncpg
 discards the physical connection and the failure is logged loudly rather than
 leaving an invisible checkout forever.
 
+**Pool growth never blocks reuse.** Only physical connection setup is serialized.
+Waiters behind a slow TLS/database handshake continue checking for healthy holders
+released by normal traffic, so an available connection cannot sit idle until the
+outer acquire deadline expires.
+
 Pinned by `tests/level1/test_pool_holder_census.py` and
 `tests/level1/test_pool_maintenance.py`.
 
-Verified against code: 2026-08-15.
+Verified against code: 2026-08-18.
 
 ## Transaction-pooled role scope
 
@@ -107,6 +117,10 @@ Verified against code: 2026-08-17.
 
 ## Change log
 
+- 2026-08-18: Let waiters reuse healthy connections released behind a slow
+  serialized-growth handshake.
+- 2026-08-17: Corrected INSERT timeout guidance to identify relation/DDL lock
+  convoys before application row contention.
 - 2026-08-17: Required direct before/after role evidence before recording
   contamination; concurrent empty-to-nonempty reads reconcile without a false
   repair-queue row, and session-authorization contamination is reset too.

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/matrx_orm/core/async_db_manager.py

@@ -120,6 +120,7 @@ READ_TIMEOUT_RETRY_BACKOFF = 0.25  # seconds before the read retry
 POOL_MAINTENANCE_SWEEP_SECONDS = 45.0
 POOL_MAINTENANCE_MIN_INTERVAL = 0.25
 POOL_MAINTENANCE_MAX_BACKOFF = 30.0
+POOL_GROWTH_GATE_POLL_SECONDS = 0.05
 
 
 try:
@@ -708,21 +709,45 @@ class AsyncDatabaseManager:
         try:
             ready = await acquire_connected_holder(pool)
         except UnsupportedPoolInternalsError:
-            ready = None
+            lock = cls._growth_locks.setdefault(config_name, asyncio.Lock())
+            async with lock:
+                return await pool.acquire()
         if ready is not None:
             return ready
 
         lock = cls._growth_locks.setdefault(config_name, asyncio.Lock())
-        async with lock:
-            # Maintenance or the previous waiter may have established/released
-            # a ready holder while this caller waited for the growth gate.
+        while True:
+            try:
+                await asyncio.wait_for(
+                    lock.acquire(),
+                    timeout=POOL_GROWTH_GATE_POLL_SECONDS,
+                )
+            except TimeoutError:
+                # A slow TLS/database handshake owns the growth gate. Traffic
+                # must still consume healthy connections released meanwhile;
+                # otherwise those slots sit idle while every waiter times out
+                # behind work that has no bearing on them.
+                try:
+                    ready = await acquire_connected_holder(pool)
+                except UnsupportedPoolInternalsError:
+                    async with lock:
+                        return await pool.acquire()
+                if ready is not None:
+                    return ready
+                continue
+
             try:
-                ready = await acquire_connected_holder(pool)
-            except UnsupportedPoolInternalsError:
-                ready = None
-            if ready is not None:
-                return ready
-            return await pool.acquire()
+                # Maintenance or the previous waiter may have established or
+                # released a ready holder while this caller waited briefly.
+                try:
+                    ready = await acquire_connected_holder(pool)
+                except UnsupportedPoolInternalsError:
+                    return await pool.acquire()
+                if ready is not None:
+                    return ready
+                return await pool.acquire()
+            finally:
+                lock.release()
 
     @classmethod
     @asynccontextmanager
@@ -1102,8 +1127,9 @@ class AsyncDatabaseManager:
                 # asyncpg's command_timeout fired — query held a connection
                 # but didn't return in time. NOT a pool-acquire timeout
                 # (that's PoolAcquireTimeoutError, raised in get_connection
-                # before the connection is held). Most common cause:
-                # row-lock contention on a hot row.
+                # before the connection is held). Diagnose by query verb:
+                # INSERT commonly means relation/DDL/FK/trigger waits, while
+                # UPDATE/DELETE commonly means a hot-row lock.
                 raise QueryTimeoutError(
                     operation="execute_query",
                     query=query,
@@ -1225,8 +1251,8 @@ class AsyncDatabaseManager:
                         ) from None
                     except TimeoutError as e:
                         # asyncpg's command_timeout fired — query held a
-                        # connection but didn't return in time. See twin comment
-                        # in the tx_conn branch above for the full rationale.
+                        # connection but didn't return in time. See the twin
+                        # query-verb diagnosis in the tx_conn branch above.
                         # A READ is side-effect-free → retry once on a fresh
                         # connection before surfacing the timeout (self-heal for
                         # starvation blips). Writes fall straight through to raise.

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/matrx_orm/exceptions.py

@@ -1008,10 +1008,11 @@ class QueryTimeoutError(DatabaseError):
         timeout = self.details.get("timeout")
         query = self._str("query")
         args = self.details.get("args", [])
-        # First-token heuristic: SELECT timeouts and UPDATE/INSERT/DELETE
-        # timeouts have totally different root-cause distributions, so
-        # the hint changes accordingly. Reads almost never row-lock under
-        # MVCC; writes almost always do under fan-out concurrency.
+        # First-token heuristic: SELECT, INSERT, and UPDATE/DELETE timeouts
+        # have different root-cause distributions, so the hint changes
+        # accordingly. In particular, a fresh INSERT cannot be contending on
+        # the row it is creating; relation/DDL locks and FK/trigger work must
+        # be investigated before blaming application fan-out.
         query_kind = _classify_query_shape(query)
         lines = ["\n" + "-" * 80]
         lines.append("Matrx ORM  |  QueryTimeoutError")
@@ -1054,25 +1055,40 @@ class QueryTimeoutError(DatabaseError):
             lines.append("  - Safe to retry ONCE for cold-cache / transient cases. If it times out")
             lines.append("    twice in a row, fix the index — retrying won't help.")
         elif query_kind == "write":
-            # Writes are where row-lock contention actually bites.
-            lines.append(
-                "  - Write query ({op}). Most common cause: row-lock contention.".format(
-                    op=query_kind.upper()
-                    if query_kind != "write"
-                    else (query.lstrip().split(None, 1)[0].upper() if query else "WRITE")
+            write_verb = query.lstrip().split(None, 1)[0].upper() if query else "WRITE"
+            lines.append(f"  - Write query ({write_verb}).")
+            if write_verb == "INSERT":
+                lines.append(
+                    "  - A fresh INSERT is not waiting on the row it is creating. Check, in"
                 )
-            )
-            lines.append("    If N async tasks UPDATE the same row in a tight loop they serialize")
-            lines.append("    on the row lock and the late ones blow past command_timeout. Either")
-            lines.append("    (a) batch the writes, (b) replace read-modify-write with an atomic")
-            lines.append("    SQL UPDATE (e.g. ``col = col || jsonb_build_object(...)``),")
-            lines.append("    or (c) gate the fan-out via RequestLane ``db_write`` bucket caps.")
-            lines.append("  - Less common: missing index on a WHERE clause (forces a slow scan to")
-            lines.append("    locate the row to update), server-side overload, statement_timeout.")
+                lines.append(
+                    "    order: a queued live DDL/relation lock; FK parent-row locks; trigger"
+                )
+                lines.append(
+                    "    work; then database-wide overload. Correlate other unrelated query"
+                )
+                lines.append(
+                    "    timeouts in the same window before changing application concurrency."
+                )
+            else:
+                lines.append(
+                    "  - UPDATE/DELETE commonly wait on a hot row. If N tasks change the same"
+                )
+                lines.append(
+                    "    row, batch them, use one atomic SQL update, or gate that write lane."
+                )
+                lines.append(
+                    "  - Also check for a queued live DDL/relation lock when unrelated tables"
+                )
+                lines.append(
+                    "    time out in the same window; that is a database-wide lock convoy."
+                )
+            lines.append("  - A missing WHERE-clause index, trigger work, or sustained server load")
+            lines.append("    can also exceed command_timeout.")
             lines.append(
-                "  - NOT safe to retry blindly — if it's row-lock contention, a retry just"
+                "  - NOT safe to retry blindly — a write may have ambiguous completion, and"
             )
-            lines.append("    rejoins the back of the lock queue and times out again.")
+            lines.append("    an unchanged lock convoy will time out again.")
         else:
             # DDL / CALL / unknown — keep both hints concise.
             lines.append("  - Couldn't classify the query shape — see the Query line above. Common")
@@ -1204,11 +1220,15 @@ class IntegrityError(DatabaseError):
             lines.append('    `null value in column "<name>"` and the rest of the message.')
             lines.append("  - Pass the field explicitly (or set a default on the model).")
         elif constraint == "check":
-            lines.append("  - A CHECK constraint rejected values that violate a database invariant.")
+            lines.append(
+                "  - A CHECK constraint rejected values that violate a database invariant."
+            )
             lines.append("  - Read the DB error above for the invariant and offending row.")
             lines.append("  - This is not transient; correct the input or the write ordering.")
         elif constraint == "exclusion":
-            lines.append("  - This row conflicts with an existing row under an exclusion constraint.")
+            lines.append(
+                "  - This row conflicts with an existing row under an exclusion constraint."
+            )
             lines.append("  - Read the DB error above for the conflicting key or range.")
             lines.append("  - This is not safe to blindly retry with unchanged input.")
         elif constraint == "restrict":

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.78"
+version = "3.1.79"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/tests/level1/test_exceptions.py

@@ -15,6 +15,7 @@ from matrx_orm.exceptions import (
     ParameterError,
     PermissionDeniedError,
     QueryError,
+    QueryTimeoutError,
     RelationshipError,
     SchemaMismatchError,
     StateError,
@@ -200,6 +201,28 @@ class TestSubclasses:
         e = UnknownDatabaseError(operation="insert", original_error=Exception("unknown"))
         assert "Unexpected database error" in e.message
 
+    def test_insert_timeout_diagnoses_relation_lock_before_row_contention(self):
+        e = QueryTimeoutError(
+            operation="execute_query",
+            query="INSERT INTO chat.agent_run (id) VALUES ($1)",
+            args=["run-id"],
+            timeout=20,
+        )
+        banner = e.format_message()
+        assert "fresh INSERT is not waiting on the row it is creating" in banner
+        assert "queued live DDL/relation lock" in banner
+
+    def test_update_timeout_keeps_hot_row_and_ddl_diagnoses(self):
+        e = QueryTimeoutError(
+            operation="execute_query",
+            query="UPDATE public.counter SET value = value + 1 WHERE id = $1",
+            args=["counter-id"],
+            timeout=20,
+        )
+        banner = e.format_message()
+        assert "UPDATE/DELETE commonly wait on a hot row" in banner
+        assert "database-wide lock convoy" in banner
+
     def test_schema_mismatch_column_derives_kind_from_sqlstate(self):
         pg = _FakePgError(
             "42703",

{matrx_orm-3.1.78 → matrx_orm-3.1.79}/tests/level1/test_pool_maintenance.py

@@ -39,6 +39,8 @@ class FakeHolder:
                 self.pool.worst_connecting,
                 self.pool.connecting,
             )
+            if self.pool.connect_gate is not None:
+                await self.pool.connect_gate.wait()
             await asyncio.sleep(0.001)
             self.connects += 1
             self.connected = True
@@ -51,6 +53,7 @@ class FakeHolder:
 class FakePool:
     def __init__(self, connected: int, maximum: int) -> None:
         self._generation = 0
+        self.connect_gate: asyncio.Event | None = None
         self.connecting = 0
         self.worst_connecting = 0
         self._queue: asyncio.LifoQueue[FakeHolder] = asyncio.LifoQueue(maxsize=maximum)
@@ -204,6 +207,36 @@ async def test_idle_connection_does_not_let_burst_bypass_growth_gate() -> None:
     assert pool.worst_connecting == 1
 
 
+@pytest.mark.asyncio
+async def test_waiter_uses_connection_released_behind_slow_growth_gate() -> None:
+    pool = FakePool(connected=1, maximum=2)
+    pool.connect_gate = asyncio.Event()
+    AsyncDatabaseManager._growth_locks.clear()
+
+    held = await acquire_connected_holder(pool)
+    assert held is not None
+
+    growing = asyncio.create_task(
+        AsyncDatabaseManager._acquire_bounded_growth("slow-growth", pool)
+    )
+    await asyncio.sleep(0)
+    assert pool.connecting == 1
+
+    waiting = asyncio.create_task(
+        AsyncDatabaseManager._acquire_bounded_growth("slow-growth", pool)
+    )
+    await pool.release(held, timeout=1.0)
+
+    reused = await asyncio.wait_for(waiting, timeout=0.2)
+    assert reused.holder is held.holder
+    assert not growing.done()
+
+    pool.connect_gate.set()
+    grown = await growing
+    await pool.release(reused, timeout=1.0)
+    await pool.release(grown, timeout=1.0)
+
+
 @pytest.mark.asyncio
 async def test_zero_connection_pool_is_replaced_once_and_reacquired(monkeypatch) -> None:
     class DeadPool: