matrx-orm 3.1.40__tar.gz → 3.1.41__tar.gz

{matrx_orm-3.1.40 → matrx_orm-3.1.41}/CLAUDE.md

@@ -32,6 +32,9 @@ Every table that becomes a Model needs row identity: a single-column primary key
   subqueries. SQL-shaped strings fail closed: plain strings name validated
   columns only; compose casts, JSON paths, functions, ordering, joins, partial
   conflict targets, and filtered aggregates with the exported typed objects.
+  Large reconciliation/export scans call `.all(use_cache=False)` so returned
+  models do not quadratically populate the process identity cache. Contract:
+  [`matrx_orm/query/FEATURE.md`](matrx_orm/query/FEATURE.md).
 - **Migrations**: `MigrationDB`, `MigrationLoader`, `MigrationExecutor`, `makemigrations`, `migrate` — migrations declare explicit `dependencies` and apply in topological order (no multi-head/merge support yet).
 - **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model.
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.

{matrx_orm-3.1.40 → matrx_orm-3.1.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.40
+Version: 3.1.41
 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.40 → matrx_orm-3.1.41}/matrx_orm/core/base.py

@@ -1292,17 +1292,17 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         return run_sync(cls.delete_where(**filters))
 
     @classmethod
-    async def all(cls) -> list[Self]:
+    async def all(cls, *, use_cache: bool = True) -> list[Self]:
+        """Fetch every row, optionally bypassing identity-cache population."""
+
         try:
-            results: list[Self] = await QueryBuilder(model_cls=cls).all()
-            await StateManager.cache_bulk(model_class=cls, records=results)
-            return results
+            return await QueryBuilder(model_cls=cls).all(use_cache=use_cache)
         except ORMException as e:
             e.enrich(model=cls, operation="all")
             raise
 
     @classmethod
-    def all_sync(cls) -> list[Self]:
+    def all_sync(cls, *, use_cache: bool = True) -> list[Self]:
         """
         Synchronous wrapper for all().
         Use this in synchronous contexts to fetch all results without async/await.
@@ -1316,7 +1316,7 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             if "no running event loop" not in str(e):
                 raise
 
-        return run_sync(cls.all())
+        return run_sync(cls.all(use_cache=use_cache))
 
     async def save(self, **kwargs: Any) -> Self:
         """Save the current state of the model instance."""

matrx_orm-3.1.41/matrx_orm/query/FEATURE.md

@@ -0,0 +1,17 @@
+# Query execution
+
+`QueryBuilder` is the typed terminal-read and write layer behind every model.
+Application packages compose queries here; they never bypass it with SQL.
+
+## Large scans and the identity cache
+
+`.all()` populates `StateManager` by default so ordinary repeated identity reads
+remain fast. A large reconciliation, export, or historical scan must call
+`.all(use_cache=False)`. This still returns fully hydrated models and still
+merges pending session state, but it does not insert every result into the
+process identity cache.
+
+`Model.all(use_cache=False)` exposes the same behavior. The default remains
+`True` for compatibility. The cache bypass controls only cache population; it
+does not weaken database authorization, filters, hydration, or transaction
+semantics.

{matrx_orm-3.1.40 → matrx_orm-3.1.41}/matrx_orm/query/builder.py

@@ -778,7 +778,7 @@ class QueryBuilder(Generic[ModelT]):
         if len(pks) == 1 and not self.excludes and set(combined) <= {pks[0], f"{pks[0]}__in"}:
             values = combined.get(pks[0])
             in_values = combined.get(f"{pks[0]}__in")
-            targets = list(in_values) if isinstance(in_values, (list, tuple, set)) else []
+            targets = list(in_values) if isinstance(in_values, list | tuple | set) else []
             if values is not None:
                 targets.append(values)
             if targets and StateManager.is_registered(self.model):
@@ -802,9 +802,12 @@ class QueryBuilder(Generic[ModelT]):
     # Terminal async methods
     # ------------------------------------------------------------------
 
-    async def all(self) -> list[ModelT]:
+    async def all(self, *, use_cache: bool = True) -> list[ModelT]:
         """Fetch all matching records.
 
+        Pass ``use_cache=False`` for large scans that must not populate the
+        process identity cache.
+
         Session-aware: if an active Session has pending writes for this
         Model, the result merges pending state with DB rows. Pending
         INSERTs matching the filter appear in the result; pending UPDATEs
@@ -814,10 +817,12 @@ class QueryBuilder(Generic[ModelT]):
         try:
             executor = self._get_executor()
             results = await executor.all()
-            await StateManager.cache_bulk(self.model, results)
+            if use_cache:
+                await StateManager.cache_bulk(self.model, results)
             if debug:
                 vcprint(
-                    f"[BUILDER] all() cached {len(results)} records for {self.model.__name__}",
+                    f"[BUILDER] all() fetched {len(results)} records for "
+                    f"{self.model.__name__} (cache={use_cache})",
                     color="bright_gold",
                 )
             return _merge_pending_into_models(

{matrx_orm-3.1.40 → matrx_orm-3.1.41}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.40"
+version = "3.1.41"
 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.40 → matrx_orm-3.1.41}/tests/level1/test_query_builder.py

@@ -1,11 +1,15 @@
 """Level 1: QueryBuilder — filter, exclude, order_by, limit, offset, select, _build_query."""
 
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
 import pytest
 from matrx_orm.core.base import Model, ModelMeta
 from matrx_orm.core.fields import CharField, IntegerField, UUIDField
 from matrx_orm.core.registry import ModelRegistry
 from matrx_orm.exceptions import DoesNotExist, PermissionDeniedError
 from matrx_orm.query.builder import QueryBuilder
+from matrx_orm.state import StateManager
 
 
 @pytest.fixture(autouse=True)
@@ -85,6 +89,20 @@ class TestQueryBuilderChaining:
         qb = QueryBuilder(M).filter()
         assert qb.filters == []
 
+    @pytest.mark.asyncio
+    async def test_all_can_skip_identity_cache_for_large_scans(self, monkeypatch):
+        M = _make_model()
+        rows = [M(id="00000000-0000-0000-0000-000000000001", name="Alice")]
+        executor = SimpleNamespace(all=AsyncMock(return_value=rows))
+        cache_bulk = AsyncMock()
+        monkeypatch.setattr(QueryBuilder, "_get_executor", lambda _self: executor)
+        monkeypatch.setattr(StateManager, "cache_bulk", cache_bulk)
+
+        result = await QueryBuilder(M).all(use_cache=False)
+
+        assert result == rows
+        cache_bulk.assert_not_awaited()
+
 
 class TestBuildQuery:
     def test_build_query_basic(self):