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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.41
+Version: 3.1.43
 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.43/matrx_orm/core/FEATURE.md

@@ -0,0 +1,10 @@
+# Database execution error contract
+
+`AsyncDatabaseManager.execute_query` must classify every PostgreSQL integrity
+constraint violation as `IntegrityError`. Known categories retain their useful
+labels (`unique`, `foreign_key`, `not_null`, `check`, `exclusion`, and
+`restrict`); an unrecognized SQLSTATE class-23 subtype uses `constraint`.
+
+`UnknownDatabaseError` is reserved for genuinely unrecognized driver failures.
+It is diagnostic and intentionally verbose, so a known PostgreSQL error must
+never reach that fallback.

{matrx_orm-3.1.41 → matrx_orm-3.1.43}/matrx_orm/core/async_db_manager.py

@@ -67,6 +67,16 @@ _SCHEMA_MISMATCH_EXC = (
 )
 
 
+def _integrity_constraint_kind(exc: asyncpg.exceptions.IntegrityConstraintViolationError) -> str:
+    if isinstance(exc, asyncpg.exceptions.CheckViolationError):
+        return "check"
+    if isinstance(exc, asyncpg.exceptions.ExclusionViolationError):
+        return "exclusion"
+    if isinstance(exc, asyncpg.exceptions.RestrictViolationError):
+        return "restrict"
+    return "constraint"
+
+
 # ── pool-acquire retry (warmup-lag survival) ──────────────────────────────────
 # A ``pool.acquire()`` timeout fires BEFORE any SQL is sent to the server (the
 # connection was never handed out), so retrying is provably side-effect-free —
@@ -834,6 +844,12 @@ class AsyncDatabaseManager:
                 ) from None
             except asyncpg.exceptions.NotNullViolationError as e:
                 raise IntegrityError(model=None, constraint="not_null", original_error=e) from None
+            except asyncpg.exceptions.IntegrityConstraintViolationError as e:
+                raise IntegrityError(
+                    model=None,
+                    constraint=_integrity_constraint_kind(e),
+                    original_error=e,
+                ) from None
             except asyncpg.exceptions.DataError as e:
                 raise ParameterError(model=None, query=query, args=args, reason=str(e)) from None
             except _SCHEMA_MISMATCH_EXC as e:
@@ -930,6 +946,12 @@ class AsyncDatabaseManager:
                             constraint="not_null",
                             original_error=e,
                         ) from None
+                    except asyncpg.exceptions.IntegrityConstraintViolationError as e:
+                        raise IntegrityError(
+                            model=None,
+                            constraint=_integrity_constraint_kind(e),
+                            original_error=e,
+                        ) from None
                     except asyncpg.exceptions.ConnectionDoesNotExistError as e:
                         raise ConnectionError(
                             model=None,

{matrx_orm-3.1.41 → matrx_orm-3.1.43}/matrx_orm/exceptions.py

@@ -1200,6 +1200,17 @@ class IntegrityError(DatabaseError):
             lines.append("  - Read the DB error above: the column name is between")
             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("  - 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("  - 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":
+            lines.append("  - A dependent row prevents this operation under a RESTRICT constraint.")
+            lines.append("  - Remove or reassign the dependency before retrying.")
         else:
             lines.append("  - The database rejected the write due to a constraint violation.")
             lines.append(

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

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

@@ -7,10 +7,12 @@ connection (no live DB needed), mirroring ``test_call_function.py``.
 
 from __future__ import annotations
 
+from datetime import UTC, datetime
+
 import pytest
 from matrx_orm import Now
 from matrx_orm.core.base import Model, ModelMeta
-from matrx_orm.core.fields import CharField, IntegerField, UUIDField
+from matrx_orm.core.fields import CharField, DateTimeField, IntegerField, UUIDField
 from matrx_orm.core.registry import ModelRegistry
 from matrx_orm.operations.bulk_update_values import bulk_update_by_pk
 
@@ -32,6 +34,7 @@ def _make_model():
             "id": UUIDField(primary_key=True),
             "chunk_index": IntegerField(),
             "source_hash": CharField(max_length=64),
+            "last_seen": DateTimeField(),
             "_database": "test_db",
             "_table_name": "kg_chunks",
             "_db_schema": "rag",
@@ -121,6 +124,21 @@ class TestBulkUpdateByPk:
         assert "DROP TABLE" not in conn.captured_sql
         assert conn.captured_params[-1] == "now(); DROP TABLE users"
 
+    async def test_timestamptz_cast_is_rendered_for_datetime_values(self):
+        Chunk = _make_model()
+        conn = _FakeConn(fetch_return=[{"?column?": 1}])
+        observed_at = datetime(2026, 7, 28, tzinfo=UTC)
+
+        await bulk_update_by_pk(
+            Chunk,
+            [{"id": "a-id", "last_seen": observed_at}],
+            casts={"id": "uuid", "last_seen": "timestamptz"},
+            connection=conn,
+        )
+
+        assert "::timestamptz" in conn.captured_sql
+        assert observed_at in conn.captured_params
+
     async def test_unsafe_cast_type_is_rejected(self):
         Chunk = _make_model()
         with pytest.raises(ValueError, match="invalid cast declaration"):

matrx_orm-3.1.43/tests/level1/test_execute_query_integrity_mapping.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+import asyncpg
+import pytest
+
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.transaction import _active_connection
+from matrx_orm.exceptions import IntegrityError
+
+
+class _RejectingConnection:
+    def __init__(self, error: Exception) -> None:
+        self.error = error
+
+    async def fetch(self, *_args, **_kwargs):
+        raise self.error
+
+
+@pytest.mark.asyncio
+async def test_check_violation_is_integrity_error_inside_transaction() -> None:
+    connection = _RejectingConnection(
+        asyncpg.exceptions.CheckViolationError("invalid canonical crawl artifact file")
+    )
+    token = _active_connection.set(connection)
+    try:
+        with pytest.raises(IntegrityError) as exc_info:
+            await AsyncDatabaseManager.execute_query("main", "INSERT INTO web.screenshot ...")
+    finally:
+        _active_connection.reset(token)
+
+    assert exc_info.value.details["constraint"] == "check"
+    assert "invalid canonical crawl artifact file" in exc_info.value.message
+
+
+@pytest.mark.asyncio
+async def test_check_violation_is_integrity_error_with_pooled_connection(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    connection = _RejectingConnection(
+        asyncpg.exceptions.CheckViolationError("invalid canonical crawl artifact file")
+    )
+
+    @asynccontextmanager
+    async def fake_get_connection(cls, config_name: str, acquire_timeout: float):
+        del cls, config_name, acquire_timeout
+        yield connection
+
+    monkeypatch.setattr(
+        AsyncDatabaseManager,
+        "get_connection",
+        classmethod(fake_get_connection),
+    )
+
+    with pytest.raises(IntegrityError) as exc_info:
+        await AsyncDatabaseManager.execute_query("main", "INSERT INTO web.screenshot ...")
+
+    assert exc_info.value.details["constraint"] == "check"
+
+
+@pytest.mark.parametrize(
+    ("error", "expected"),
+    [
+        (asyncpg.exceptions.ExclusionViolationError("overlapping range"), "exclusion"),
+        (asyncpg.exceptions.RestrictViolationError("dependent rows exist"), "restrict"),
+    ],
+)
+def test_other_integrity_constraint_kinds_are_classified(
+    error: asyncpg.exceptions.IntegrityConstraintViolationError,
+    expected: str,
+) -> None:
+    from matrx_orm.core.async_db_manager import _integrity_constraint_kind
+
+    assert _integrity_constraint_kind(error) == expected