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

{matrx_orm-3.1.78 → matrx_orm-3.1.80}/CLAUDE.md

@@ -29,6 +29,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Read-only models** (`_read_only = True`): a model that can be queried but NEVER written through the ORM — every write path raises `ReadOnlyModelError` (enforced at `QueryExecutor.insert/bulk_insert/upsert/update/delete`, so it covers all of `create`/`save`/`update`/`delete`/`update_where`/`delete_where`/`upsert`/`bulk_*`). Used for DB-managed tables the app must not mutate. The canonical **`auth.users`** model is baked into the schema generator (`get_string_user_model`) as the full, curated Supabase auth schema (safe columns only — no password/token fields), `_read_only`, bound per-database. Read a user's profile/metadata there; mutate users only through Supabase Auth (GoTrue).
 - **Connection-level type codecs** (`async_db_manager._init_connection_default`): every pooled connection decodes **uuid → `str`**, **vector → `list[float]`**, and **json/jsonb → `dict`/`list`** at the driver boundary — the TYPE decides the decode, never the call path. So `call_function` scalar/rows, raw fetches, and field hydration all agree; a caller must **never `json.loads` a fetched json/jsonb value** (it's already decoded; the 2026-07-13 `build_agent_context` crash was a jsonb RPC fetched pre-codec as a raw string). Encoding: a pre-serialised JSON `str` passes through untouched; a native dict/list is dumped (`_encode_json`). Pinned by `tests/level1/test_connection_codecs.py`.
 - **Connection pools are event-loop-owned.** `AsyncDatabaseManager.get_pool()` recreates a pool when a caller arrives on a different loop. If the former owner loop is already closed, stale-pool termination and cleanup discard that pool without trying to schedule callbacks onto the dead loop; unrelated runtime errors still raise. Pinned by `tests/level1/test_pool_loop_recreation.py`.
+- **Exception diagnostics never read source files.** `ORMException` captures compact caller metadata by walking live frames; `traceback.extract_stack()` is forbidden because its `linecache` filesystem checks can stall an async server. Contract: [`matrx_orm/FEATURE.md`](matrx_orm/FEATURE.md).
 - **A zero-connection pool is dead, not busy.** After bounded SQL-safe acquire retries, `AsyncDatabaseManager.get_connection()` atomically replaces a pool whose physical size is still zero, then tries once against the replacement. It never replaces a busy `size > 0` pool. Contract: [`matrx_orm/core/FEATURE.md`](matrx_orm/core/FEATURE.md).
 - **Query layer**: `QueryBuilder`, typed predicates/projections (`F`, `Q`,
   `Predicate`, `Projection`), window functions, QueryBuilder-backed CTEs, and

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.78
+Version: 3.1.80
 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.80/matrx_orm/FEATURE.md

@@ -0,0 +1,19 @@
+# Matrx ORM runtime contracts
+
+## Exception diagnostics stay event-loop safe
+
+- **Caller capture is metadata-only.** `_capture_caller_frames()` walks live Python frames and reads only code filename, function name, and line number.
+- **Source-file reads are forbidden during exception construction.** Never use `traceback.extract_stack()` here: it enters `linecache.checkcache()` and synchronously stats source files, which can freeze every request in an async server.
+- **Diagnostic value is preserved.** `ORMException._caller_frames` retains up to three external application frames in oldest-to-newest order while excluding ORM, site-package, frozen-import, and runpy frames.
+- **The regression guard is direct.** `tests/level1/test_exceptions.py::TestORMExceptionBase::test_caller_capture_never_reads_source_files` makes traceback extraction fail and proves exception construction still captures the application call site.
+
+## Entry points
+
+- Runtime hierarchy and formatting: `exceptions.py`
+- Focused unit coverage: `tests/level1/test_exceptions.py`
+
+## Change Log
+
+- 2026-08-18 — Replaced traceback extraction with live-frame metadata walking so ordinary ORM exceptions cannot synchronously stat source files on the event loop.
+
+Verified against `exceptions.py` and `tests/level1/test_exceptions.py` on 2026-08-18.

{matrx_orm-3.1.78 → matrx_orm-3.1.80}/matrx_orm/__init__.py

@@ -43,7 +43,7 @@ from .platform_db import (
     platform_connection_url,
     register_platform_db,
 )
-from .local_sqlite import SQLiteValue, read_local_sqlite_rows
+from .local_sqlite import SQLiteValue, check_local_sqlite_integrity, read_local_sqlite_rows
 from .core.diagnostics import collect_pool_diagnostics, log_pool_diagnostics
 from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
 from .core.one_database import OneDatabaseReport, PoolIdentity, audit_one_database
@@ -639,6 +639,7 @@ __all__ = [
     "open_listener_connection",
     # ── Read-only local SQLite artifacts ──────────────────────────────────────
     "SQLiteValue",
+    "check_local_sqlite_integrity",
     "read_local_sqlite_rows",
     # ── Cache ──────────────────────────────────────────────────────────────────
     "CachePolicy",

{matrx_orm-3.1.78 → matrx_orm-3.1.80}/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
 
@@ -66,12 +71,19 @@ census, so retry/persistence casualties preserve the diagnosis.
 shielded task with a 10-second asyncpg release timeout. A holder remains visible
 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.
+leaving an invisible checkout forever. **A release timeout never replaces an
+already-completed query result** with a request failure; the discarded connection
+is the isolation boundary.
+
+**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 +119,12 @@ Verified against code: 2026-08-17.
 
 ## Change log
 
+- 2026-08-18: Preserved successful query results when asyncpg times out while
+  resetting and discarding the released connection.
+- 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.80}/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:
-                ready = await acquire_connected_holder(pool)
-            except UnsupportedPoolInternalsError:
-                ready = None
-            if ready is not None:
-                return ready
-            return await pool.acquire()
+                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:
+                # 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
@@ -1019,13 +1044,30 @@ class AsyncDatabaseManager:
                 except Exception:
                     pass
 
-            release_task.add_done_callback(_release_done)
             try:
                 await asyncio.shield(release_task)
             except asyncio.CancelledError:
                 # The dedicated release task keeps running to completion and its
                 # body/callback own census cleanup and recovery-latch reset.
+                release_task.add_done_callback(_release_done)
                 raise
+            except TimeoutError as release_exc:
+                # asyncpg terminates a connection whose reset exceeds the
+                # release timeout. The query already completed successfully, so
+                # this cleanup failure must not replace its result with a false
+                # request crash. Keep the pool-health signal loud.
+                logger.error(
+                    "[matrx_orm] Connection release timed out for '%s'; "
+                    "asyncpg discarded the connection: %s",
+                    config_name,
+                    release_exc,
+                )
+            else:
+                try:
+                    if pool.get_idle_size() > 0:
+                        note_pool_recovered(config_name)
+                except Exception:
+                    pass
 
     @classmethod
     async def execute_query(
@@ -1102,8 +1144,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 +1268,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.80}/matrx_orm/exceptions.py

@@ -2,6 +2,7 @@ import asyncio
 import re
 import socket
 import ssl
+import sys
 import traceback as _tb
 from collections.abc import Mapping
 from dataclasses import dataclass
@@ -304,12 +305,17 @@ def _capture_caller_frames() -> list[str]:
     section only contains application code written by the user.
     """
     frames: list[str] = []
-    for fi in reversed(_tb.extract_stack()[:-1]):
-        if any(marker in fi.filename for marker in _EXCLUDED_FRAME_MARKERS):
-            continue
-        frames.append(f'  File "{fi.filename}", line {fi.lineno}, in {fi.name}')
-        if len(frames) >= 3:
-            break
+    frame = sys._getframe(1)
+    try:
+        while frame is not None and len(frames) < 3:
+            filename = frame.f_code.co_filename
+            if not any(marker in filename for marker in _EXCLUDED_FRAME_MARKERS):
+                frames.append(
+                    f'  File "{filename}", line {frame.f_lineno}, in {frame.f_code.co_name}'
+                )
+            frame = frame.f_back
+    finally:
+        del frame
     frames.reverse()
     return frames
 
@@ -1008,10 +1014,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 +1061,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 +1226,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.80/matrx_orm/local_sqlite.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import re
+import sqlite3
+from collections.abc import Sequence
+from pathlib import Path
+from collections.abc import Mapping
+
+type SQLiteValue = str | int | float | bytes | None
+
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+def _identifier(value: str) -> str:
+    if not _IDENTIFIER.fullmatch(value):
+        raise ValueError(f"invalid SQLite identifier: {value!r}")
+    return f'"{value}"'
+
+
+def read_local_sqlite_rows(
+    database: str | Path,
+    *,
+    table: str,
+    columns: Sequence[str],
+    order_by: Sequence[str] = (),
+    where_not_null: Sequence[str] = (),
+    min_lengths: Mapping[str, int] | None = None,
+    limit: int | None = None,
+) -> list[tuple[SQLiteValue, ...]]:
+    """Read a projected table from a local SQLite artifact in read-only mode."""
+    if not columns:
+        raise ValueError("columns must contain at least one identifier")
+
+    projection = ", ".join(_identifier(column) for column in columns)
+    statement = f"SELECT {projection} FROM {_identifier(table)}"
+    predicates: list[str] = []
+    parameters: list[int] = []
+    for column in where_not_null:
+        predicates.append(f"{_identifier(column)} IS NOT NULL")
+    for column, minimum in (min_lengths or {}).items():
+        if minimum < 0:
+            raise ValueError("minimum lengths must be non-negative")
+        predicates.append(f"length({_identifier(column)}) >= ?")
+        parameters.append(minimum)
+    if predicates:
+        statement += " WHERE " + " AND ".join(predicates)
+    if order_by:
+        statement += " ORDER BY " + ", ".join(_identifier(column) for column in order_by)
+    if limit is not None:
+        if limit <= 0:
+            raise ValueError("limit must be positive")
+        statement += " LIMIT ?"
+        parameters.append(limit)
+
+    path = Path(database).expanduser().resolve()
+    connection = sqlite3.connect(f"{path.as_uri()}?mode=ro", uri=True)
+    try:
+        return [tuple(row) for row in connection.execute(statement, parameters)]
+    finally:
+        connection.close()
+
+
+def check_local_sqlite_integrity(database: str | Path) -> str:
+    """Return SQLite's read-only quick-check result for a local artifact."""
+    path = Path(database).expanduser().resolve()
+    connection = sqlite3.connect(f"{path.as_uri()}?mode=ro", uri=True)
+    try:
+        row = connection.execute("PRAGMA quick_check").fetchone()
+        return str(row[0]) if row else ""
+    finally:
+        connection.close()

{matrx_orm-3.1.78 → matrx_orm-3.1.80}/matrx_orm/query/FEATURE.md

@@ -3,6 +3,18 @@
 `QueryBuilder` is the typed terminal-read and write layer behind every model.
 Application packages compose queries here; they never bypass it with SQL.
 
+## Async query compilation
+
+**Every async terminal compiles SQL in a worker thread.** `all`, `first`,
+`get`, `update`, `delete`, `count`, `exists`, `aggregate`, `values`,
+`values_list`, `fetch_via`, and async iteration must reach their first database
+await without running `QueryBuilder._build_query` or `QueryExecutor._build_query`
+on the event-loop thread. Query shapes are usually small, but concurrent or
+expression-heavy builders are synchronous Python work and cannot freeze every
+request in the process.
+
+`compile()` remains deliberately synchronous for synchronous callers.
+
 ## Large scans and the identity cache
 
 `.all()` populates `StateManager` by default so ordinary repeated identity reads
@@ -34,5 +46,6 @@ without forcing callers to add a redundant projection.
 
 ## Change log
 
+- 2026-08-18 — Moved async terminal SQL compilation off the event loop.
 - 2026-08-15 — Moved bulk hydration off the event loop, made complete-primary-key
   misses constant-time, and documented cache bypass for request-local scans.

{matrx_orm-3.1.78 → matrx_orm-3.1.80}/matrx_orm/query/builder.py

@@ -805,6 +805,9 @@ class QueryBuilder(Generic[ModelT]):
     def _get_executor(self) -> QueryExecutor:
         return QueryExecutor(self._build_query())
 
+    async def _get_executor_async(self) -> QueryExecutor:
+        return await asyncio.to_thread(self._get_executor)
+
     # ------------------------------------------------------------------
     # Terminal async methods
     # ------------------------------------------------------------------
@@ -822,7 +825,7 @@ class QueryBuilder(Generic[ModelT]):
         See matrx_orm.session.reads.merge_pending_with_db.
         """
         try:
-            executor = self._get_executor()
+            executor = await self._get_executor_async()
             results = await executor.all()
             if use_cache:
                 await StateManager.cache_bulk(self.model, results)
@@ -851,7 +854,7 @@ class QueryBuilder(Generic[ModelT]):
 
         Session-aware via the same merge pathway as :meth:`all`."""
         try:
-            executor = self._get_executor()
+            executor = await self._get_executor_async()
             results = await executor.all()
             merged = _merge_pending_into_models(
                 self.model,
@@ -878,7 +881,7 @@ class QueryBuilder(Generic[ModelT]):
         """
         filters = self._merge_filters_excludes()
         try:
-            executor = self._get_executor()
+            executor = await self._get_executor_async()
             results = await executor.all()
             results = _merge_pending_into_models(self.model, results, filters)
             if not results:
@@ -908,7 +911,8 @@ class QueryBuilder(Generic[ModelT]):
         try:
             if not kwargs:
                 raise ValidationError(model=self.model, reason="No update data provided")
-            result = await self._get_executor().update(**kwargs)
+            executor = await self._get_executor_async()
+            result = await executor.update(**kwargs)
             await StateManager.refresh_from_rows(self.model, result.updated_rows)
             return result
         except ValidationError:
@@ -927,7 +931,8 @@ class QueryBuilder(Generic[ModelT]):
         free, serving a deleted row for 10 minutes is not.
         """
         try:
-            deleted = await self._get_executor().delete()
+            executor = await self._get_executor_async()
+            deleted = await executor.delete()
             if deleted:
                 self._invalidate_cache_for_filters()
             return deleted
@@ -958,7 +963,8 @@ class QueryBuilder(Generic[ModelT]):
         try:
             if self._stack_has_pending():
                 return len(await self.all())
-            return await self._get_executor().count()
+            executor = await self._get_executor_async()
+            return await executor.count()
         except ORMException as e:
             e.enrich(model=self.model, operation="count", filters=self._merge_filters_excludes())
             raise
@@ -970,7 +976,8 @@ class QueryBuilder(Generic[ModelT]):
         try:
             if self._stack_has_pending():
                 return len(await self.all()) > 0
-            return await self._get_executor().exists()
+            executor = await self._get_executor_async()
+            return await executor.exists()
         except ORMException as e:
             e.enrich(model=self.model, operation="exists", filters=self._merge_filters_excludes())
             raise
@@ -991,7 +998,8 @@ class QueryBuilder(Generic[ModelT]):
         for key, value in kwargs.items():
             target.aggregations.append({"name": key, "function": value})
         try:
-            return await target._get_executor().aggregate()
+            executor = await target._get_executor_async()
+            return await executor.aggregate()
         except ORMException as e:
             e.enrich(
                 model=self.model, operation="aggregate", filters=self._merge_filters_excludes()
@@ -1002,7 +1010,8 @@ class QueryBuilder(Generic[ModelT]):
         target = self._clone() if fields else self
         if fields:
             target.select_fields = list(fields)
-        return await target._get_executor().values()
+        executor = await target._get_executor_async()
+        return await executor.values()
 
     def compile(self, *fields: str) -> tuple[str, list[Any]]:
         """Build the SELECT SQL + bound-parameter list WITHOUT executing.
@@ -1057,7 +1066,7 @@ class QueryBuilder(Generic[ModelT]):
                 .fetch_via(conn, "id", set_local={"hnsw.iterative_scan": "relaxed_order"})
             )
         """
-        sql, params = self.compile(*fields)
+        sql, params = await asyncio.to_thread(self.compile, *fields)
         if set_local:
             async with conn.transaction():
                 for guc_name, guc_value in set_local.items():
@@ -1075,7 +1084,8 @@ class QueryBuilder(Generic[ModelT]):
         target = self._clone() if fields else self
         if fields:
             target.select_fields = list(fields)
-        return await target._get_executor().values_list(flat=flat)
+        executor = await target._get_executor_async()
+        return await executor.values_list(flat=flat)
 
     # ------------------------------------------------------------------
     # Synchronous wrappers
@@ -1144,7 +1154,7 @@ class QueryBuilder(Generic[ModelT]):
     # ------------------------------------------------------------------
 
     async def __aiter__(self) -> Any:
-        executor = self._get_executor()
+        executor = await self._get_executor_async()
         async for item in executor:
             yield item
 

{matrx_orm-3.1.78 → matrx_orm-3.1.80}/matrx_orm/query/executor.py

@@ -1540,7 +1540,7 @@ class QueryExecutor:
     async def first(self) -> Any:
         """Fetch the first matching row as a model instance."""
         self._full_query_dict["limit"] = 1
-        self.query, self.params = self._build_query()
+        self.query, self.params = await asyncio.to_thread(self._build_query)
         results = await self._execute()
         if not results:
             return None
@@ -1578,7 +1578,7 @@ class QueryExecutor:
     async def exists(self) -> bool:
         """EXISTS check for the current WHERE clause."""
         self._full_query_dict["limit"] = 1
-        self.query, self.params = self._build_query()
+        self.query, self.params = await asyncio.to_thread(self._build_query)
         results = await self._execute()
         return len(results) > 0
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.78"
+version = "3.1.80"
 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.80}/tests/level1/test_connection_poison_guard.py

@@ -33,6 +33,16 @@ class _FakeConn:
             self._in_tx = False
         return "OK"
 
+    async def fetch(
+        self,
+        sql: str,
+        *args: object,
+        timeout: float | None = None,  # noqa: ASYNC109 - mirrors asyncpg
+    ) -> list[dict[str, int]]:
+        del args, timeout
+        self.calls.append(sql)
+        return [{"value": 1}]
+
     def terminate(self) -> None:
         self.calls.append("TERMINATE")
         self._in_tx = False
@@ -73,6 +83,16 @@ class _FakePool:
         return 1
 
 
+class _ReleaseTimeoutPool(_FakePool):
+    async def release(
+        self,
+        conn: _FakeConn,
+        timeout: float | None = None,  # noqa: ASYNC109 - mirrors asyncpg
+    ) -> None:
+        del conn, timeout
+        raise TimeoutError("reset exceeded release budget")
+
+
 def _patch_pool(monkeypatch, pool: _FakePool) -> None:
     async def fake_get_pool(cls, config_name):  # noqa: ANN001
         return pool
@@ -116,3 +136,14 @@ async def test_unhealable_connection_is_terminated_not_reused(monkeypatch):
             pass
     assert "TERMINATE" in conn.calls
     assert pool.released == [conn]  # slot freed, conn discarded
+
+
+async def test_release_timeout_does_not_replace_successful_query_result(monkeypatch, caplog):
+    conn = _FakeConn(in_tx=False)
+    pool = _ReleaseTimeoutPool(conn)
+    _patch_pool(monkeypatch, pool)
+
+    result = await AsyncDatabaseManager.execute_query("x", "SELECT 1 AS value")
+
+    assert result == [{"value": 1}]
+    assert "Connection release timed out for 'x'" in caplog.text