matrx-orm 3.1.4__tar.gz → 3.1.6__tar.gz

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/PKG-INFO

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

@@ -1145,12 +1145,15 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
 
     @classmethod
     def _single_pk_name(cls) -> str:
+        """The one PK column name, for callers that structurally need a single
+        scalar key (e.g. ``{pk}__in`` filters). RAISES on composite-PK models —
+        use ``_build_pk_filter`` for by-id access instead."""
         pks = cls._meta.primary_keys
         if len(pks) != 1:
             raise ValueError(
-                f"{cls.__name__}.load_by_id requires a single-column primary key, "
+                f"{cls.__name__} requires a single-column primary key here, "
                 f"but the model has primary keys {pks!r}. Use get(...)/get_or_none(...) "
-                f"with explicit key columns instead."
+                f"with explicit key columns, or pass a dict/tuple to the by-id methods."
             )
         return pks[0]
 
@@ -1159,17 +1162,20 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         """Load a row by its primary key. Raises DoesNotExist if absent.
 
         Alias for ``get(**{pk: item_id})`` — mirrors ``BaseManager.load_by_id``.
+        Composite-PK models accept a dict ``{pk: val}`` or a PK-ordered
+        tuple/list (a bare scalar raises — see ``_build_pk_filter``).
         For a None-returning lookup use :meth:`load_by_id_or_none`.
         """
-        return await cls.get(**{cls._single_pk_name(): item_id})
+        return await cls.get(**cls._build_pk_filter(item_id))
 
     @classmethod
     async def load_by_id_or_none(cls, item_id: Any) -> Self | None:
         """Load a row by its primary key, or None if absent.
 
-        Alias for ``get_or_none(**{pk: item_id})``.
+        Alias for ``get_or_none(**{pk: item_id})``. Composite-PK models accept
+        a dict / PK-ordered tuple, same as :meth:`load_by_id`.
         """
-        return await cls.get_or_none(**{cls._single_pk_name(): item_id})
+        return await cls.get_or_none(**cls._build_pk_filter(item_id))
 
     @classmethod
     async def filter_items(cls, *args: Any, **kwargs: Any) -> list[Self]:
@@ -1189,7 +1195,7 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         returned instance isn't needed, prefer ``update_where({pk: id}, ...)``
         (a single statement).
         """
-        instance = await cls.get(**{cls._single_pk_name(): item_id})
+        instance = await cls.get(**cls._build_pk_filter(item_id))
         return await instance.update(**updates)
 
     @classmethod
@@ -1292,9 +1298,17 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             raise TypeError(error_message)
 
         try:
-            is_update = bool(self._meta.primary_keys) and all(
-                getattr(self, pk, None) is not None for pk in self._meta.primary_keys
-            )
+            pks = self._meta.primary_keys
+            if len(pks) > 1:
+                # Natural composite keys are fully known BEFORE the row exists
+                # (a join row is constructed with both ids in hand), so "all
+                # PKs set" cannot distinguish INSERT from UPDATE. Hydration is
+                # the truth: only a row that came from the DB is an update.
+                is_update = bool(self.__dict__.get("_from_db"))
+            else:
+                is_update = bool(pks) and all(
+                    getattr(self, pk, None) is not None for pk in pks
+                )
             if is_update:
                 # Write ONLY loaded/changed columns — never blindly re-write the
                 # whole row. A full-row write from a partially-loaded instance
@@ -1424,9 +1438,7 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             await delete.delete_instance(self)
             await StateManager.remove(self.__class__, self)
         except ORMException as e:
-            pk = (
-                getattr(self, self._meta.primary_keys[0], None) if self._meta.primary_keys else None
-            )
+            pk = {p: getattr(self, p, None) for p in self._meta.primary_keys} or None
             e.enrich(model=self.__class__, operation="delete", args={"pk": pk})
             raise
 

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/core/expressions.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+from datetime import date, datetime
+from decimal import Decimal
 from typing import Any, TYPE_CHECKING
+from uuid import UUID
 
 if TYPE_CHECKING:
     pass
@@ -533,6 +536,115 @@ def _render_func_arg(arg: Any, params: list[Any]) -> str:
     return f"${len(params)}"
 
 
+# ---------------------------------------------------------------------------
+# Type-anchoring for bound literals in a CASE branch
+# ---------------------------------------------------------------------------
+#
+# Postgres infers a bare `$N`'s type from its surrounding context. A CASE whose
+# THEN/ELSE branches are ALL bound params has NO anchor to infer from, so it
+# falls back to `text` — and asyncpg then refuses to encode a Python int/bool/
+# float into that text slot:
+#
+#     invalid input for query argument $5: 0 (expected str, got int)
+#
+# Verified live (project txzxabzwovsujtloxrus):
+#     PREPARE p AS SELECT 1 FROM t ORDER BY CASE WHEN lower(name) = $1
+#                                                THEN $2 ELSE $3 END;
+#     -> parameter_types = {text,text,text}      # $2/$3 silently become text
+#     ... THEN $2::bigint ELSE $3::bigint END
+#     -> parameter_types = {text,bigint,bigint}  # anchored
+#
+# So an UNANCHORED CASE-branch literal is bound WITH an explicit cast: the value
+# stays parameterized (zero injection surface) and Postgres gets its type anchor.
+#
+# 🚨 BUT THE CAST IS ONLY EMITTED WHEN THE CASE IS ACTUALLY UNANCHORED — i.e.
+# when EVERY branch is a bound literal. If ANY branch is a column or expression,
+# THAT branch already supplies the type and adding a cast can CHANGE the CASE's
+# resolved type. This is not hypothetical (live-verified type resolution):
+#
+#     CASE WHEN .. THEN bigint           ELSE numeric END  -> numeric           ✅
+#     CASE WHEN .. THEN double precision ELSE numeric END  -> double precision  ❌
+#
+# The auto-ingest cost UPSERT does exactly this:
+#     SET daily_auto_rag_cost_used_usd =              -- a NUMERIC (money) column
+#         CASE WHEN .. THEN $7 ELSE (col + $8) END    -- ELSE anchors it: numeric
+# Blindly casting `$7::double precision` there promotes the whole CASE to double
+# precision and pushes MONEY THROUGH A FLOAT. So: literal-only CASE -> cast;
+# any column/expression branch -> leave the params bare and let it anchor them.
+#
+# Order matters: bool before int (bool IS a subclass of int), datetime before
+# date (datetime IS a subclass of date).
+_PG_LITERAL_CASTS: tuple[tuple[type, str], ...] = (
+    (bool, "boolean"),
+    (int, "bigint"),
+    (float, "double precision"),
+    (Decimal, "numeric"),
+    (datetime, "timestamptz"),
+    (date, "date"),
+    (UUID, "uuid"),
+)
+
+
+def _pg_cast_for_literal(value: Any) -> str | None:
+    """The Postgres type to anchor a bound Python literal to, or None if unknown."""
+    for py_type, pg_type in _PG_LITERAL_CASTS:
+        if isinstance(value, py_type):
+            return pg_type
+    return None
+
+
+def _is_bound_literal_branch(arg: Any) -> bool:
+    """True when a CASE branch is a value we BIND as a param.
+
+    A bare string is a COLUMN NAME (the Func-arg convention), an ``F``/``Func``/
+    nested ``Case`` is an expression, and ``None`` renders as a literal ``NULL``
+    — none of those are bound. Everything else is a value we bind.
+    """
+    if arg is None or isinstance(arg, str) or isinstance(arg, F) or hasattr(arg, "as_sql"):
+        return False
+    return True
+
+
+def _branch_anchors_type(arg: Any) -> bool:
+    """True when a CASE branch SUPPLIES a type Postgres can resolve the CASE by.
+
+    A column reference or an expression does. A bound literal does not (it is the
+    thing that needs anchoring). ``None`` does not either — an untyped ``NULL``
+    resolves to whatever its siblings do, so it must NOT suppress the cast (a
+    `THEN NULL ELSE $1` CASE is still unanchored and still degrades to text).
+    """
+    return isinstance(arg, str) or isinstance(arg, F) or hasattr(arg, "as_sql")
+
+
+def case_is_unanchored(branches: list[Any]) -> bool:
+    """True when NO CASE branch supplies a type — only then may we cast literals.
+
+    If even one branch is a column or an expression, it anchors the CASE and a
+    cast could change the resolved type (bigint/numeric -> numeric, but double
+    precision/numeric -> double precision, which silently degrades a money
+    column). See the block comment above.
+    """
+    return not any(_branch_anchors_type(b) for b in branches)
+
+
+def _render_case_result(arg: Any, params: list[Any], *, cast_literals: bool) -> str:
+    """Render a CASE THEN/ELSE branch.
+
+    Identical to :func:`_render_func_arg` for columns/expressions. A bound
+    literal gets an explicit ``::type`` cast ONLY when ``cast_literals`` is set —
+    i.e. only when the CASE has no other branch to anchor its type.
+    """
+    if arg is None:
+        # An unadorned NULL is unknown-typed too, but it unifies with whatever
+        # the sibling branch resolves to — no cast needed, and none is possible.
+        return "NULL"
+    if not _is_bound_literal_branch(arg):
+        return _render_func_arg(arg, params)
+    params.append(arg)
+    cast = _pg_cast_for_literal(arg) if cast_literals else None
+    return f"${len(params)}::{cast}" if cast else f"${len(params)}"
+
+
 # ---------------------------------------------------------------------------
 # Case / When — conditional CASE WHEN ... THEN ... ELSE ... END expression
 # ---------------------------------------------------------------------------
@@ -552,8 +664,13 @@ class When:
 
     Usage::
 
-        When("lower(e.name) = $1", phrase, then=0)                    # -> WHEN lower(e.name) = $1 THEN $2
+        When("lower(e.name) = $1", phrase, then=0)                    # -> WHEN lower(e.name) = $1 THEN $2::bigint
         When("ed.src_id = ANY($1::uuid[])", ids, then="ed.dst_id")    # then = bare column, not bound
+
+    A bound ``then``/``default`` literal is rendered WITH an explicit ``::type``
+    cast — a CASE branch gives Postgres no type to infer from, so an unadorned
+    ``$N`` silently resolves to ``text`` and asyncpg then rejects a Python int
+    ("expected str, got int"). See :func:`_render_case_result`.
     """
 
     def __init__(self, condition: str, *condition_params: Any, then: Any) -> None:
@@ -561,7 +678,7 @@ class When:
         self.condition_params = condition_params
         self.then = then
 
-    def as_sql(self, params: list[Any]) -> str:
+    def as_sql(self, params: list[Any], *, cast_literals: bool = True) -> str:
         if self.condition_params:
             from matrx_orm.query.executor import _shift_param_refs
 
@@ -569,7 +686,7 @@ class When:
             params.extend(self.condition_params)
         else:
             cond_sql = self.condition
-        then_sql = _render_func_arg(self.then, params)
+        then_sql = _render_case_result(self.then, params, cast_literals=cast_literals)
         return f"WHEN {cond_sql} THEN {then_sql}"
 
     def __repr__(self) -> str:
@@ -611,11 +728,22 @@ class Case:
         self.default = default
 
     def as_sql(self, params: list[Any]) -> str:
+        # Cast the bound literals ONLY if nothing else in the CASE anchors its
+        # type. A column/expression branch (e.g. `ELSE col + $8` in the money
+        # UPSERT) is the anchor — casting alongside it can promote the whole
+        # CASE to a different type. See case_is_unanchored().
+        branches: list[Any] = [w.then for w in self.whens]
+        if self.default is not None:
+            branches.append(self.default)
+        cast_literals = case_is_unanchored(branches)
+
         parts = ["CASE"]
         for w in self.whens:
-            parts.append(w.as_sql(params))
+            parts.append(w.as_sql(params, cast_literals=cast_literals))
         if self.default is not None:
-            parts.append(f"ELSE {_render_func_arg(self.default, params)}")
+            parts.append(
+                f"ELSE {_render_case_result(self.default, params, cast_literals=cast_literals)}"
+            )
         parts.append("END")
         return " ".join(parts)
 

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/core/extended.py

@@ -196,7 +196,7 @@ class BaseManager(Generic[ModelT]):
     async def _initialize_item_runtime(self, item: ModelT | None) -> ModelT | None:
         if not item:
             return None
-        item_pk = getattr(item, self._pk_name, None)
+        item_pk = self._item_identity(item)
         if item_pk is not None and item_pk in self._skipped_item_ids:
             return None
         existing_dto = getattr(item, "dto", None)
@@ -274,7 +274,7 @@ class BaseManager(Generic[ModelT]):
     async def _process_item(self, item: ModelT | None) -> ModelT | None:
         if item:
             await self._initialize_item_runtime(item)
-            self._add_to_active(item_id=getattr(item, self._pk_name))
+            self._add_to_active(item_id=item)
         return item
 
     @handle_errors
@@ -404,7 +404,12 @@ class BaseManager(Generic[ModelT]):
 
     @property
     def _pk_name(self) -> str:
-        """The primary key field name for this manager's model."""
+        """The primary key field name for this manager's model.
+
+        ⚠️ Returns the FIRST PK column only — never use it to identify a row
+        on a composite-PK model. Use ``_pk_filter`` (by-id filters) or
+        ``_item_identity`` (row identity) instead.
+        """
         pks = self.model._meta.primary_keys
         return pks[0] if pks else "id"
 
@@ -434,12 +439,30 @@ class BaseManager(Generic[ModelT]):
 
         return governed_write(self.model)
 
+    def _item_identity(self, item: Any) -> Any:
+        """Full-primary-key identity of a model instance.
+
+        Single-PK: the scalar PK value. Composite-PK: a PK-ordered tuple.
+        Returns None when any PK component is unset — first-column-only
+        identity conflated distinct composite-PK rows.
+        """
+        pks = self.model._meta.primary_keys or ["id"]
+        if len(pks) == 1:
+            return getattr(item, pks[0], None)
+        values = tuple(getattr(item, pk, None) for pk in pks)
+        return None if any(v is None for v in values) else values
+
     def _active_item_key(self, item_or_id: Any) -> Any:
-        """Normalize an active-set entry to a primary-key value."""
-        pk = self._pk_name
-        if hasattr(item_or_id, pk):
-            return getattr(item_or_id, pk)
-        return item_or_id
+        """Normalize an active-set entry to a full-primary-key value."""
+        pks = self.model._meta.primary_keys or ["id"]
+        if all(hasattr(item_or_id, pk) for pk in pks):
+            return self._item_identity(item_or_id)
+        if len(pks) == 1:
+            return item_or_id
+        # Composite raw id (dict / PK-ordered tuple) → normalized PK-ordered
+        # tuple. A bare scalar raises via _build_pk_filter.
+        pk_filter = self.model._build_pk_filter(item_or_id)
+        return tuple(pk_filter[pk] for pk in pks)
 
     def _add_to_active(self, item_id: Any) -> Any:
         """Add an item ID to the active set."""
@@ -517,7 +540,14 @@ class BaseManager(Generic[ModelT]):
         return await self.load_item_with_retry(**self._pk_filter(item_id))
 
     async def load_items_by_ids(self, item_ids: list[Any]) -> list[ModelT]:
-        """Load multiple items by their primary keys."""
+        """Load multiple items by their primary keys.
+
+        Composite-PK models: each id is a dict / PK-ordered tuple (no
+        single-column ``__in`` exists for a composite key).
+        """
+        if len(self.model._meta.primary_keys or ["id"]) > 1:
+            items = await asyncio.gather(*(self.load_by_id(item_id) for item_id in item_ids))
+            return [item for item in items if item]
         return await self.load_items(**{f"{self._pk_name}__in": item_ids})
 
     async def add_active_by_id(self, item_id: Any) -> ModelT:
@@ -548,10 +578,9 @@ class BaseManager(Generic[ModelT]):
     @handle_errors
     async def get_active_items(self) -> list[ModelT]:
         """Get all active items, initialized."""
-        pk = self._pk_name
         item_ids = [self._active_item_key(item_id) for item_id in self._active_items]
         items: list[ModelT] = await asyncio.gather(
-            *(self._get_item_or_raise(**{pk: item_id}) for item_id in item_ids)
+            *(self._get_item_or_raise(**self._pk_filter(item_id)) for item_id in item_ids)
         )
         return list(items)
 
@@ -671,7 +700,14 @@ class BaseManager(Generic[ModelT]):
 
         config_name = self.model.get_database_name()
         table = self.model._meta.qualified_table_name
-        pk = self._pk_name
+        pks = self.model._meta.primary_keys or ["id"]
+        if len(pks) > 1:
+            raise ValueError(
+                f"{self.model.__name__} has a composite primary key {tuple(pks)}; "
+                f"patch_jsonb_path supports single-column primary keys only. "
+                f"Use update_item_fields with an explicit pk dict/tuple instead."
+            )
+        pk = pks[0]
 
         from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 
@@ -801,8 +837,8 @@ class BaseManager(Generic[ModelT]):
                 rows_affected = await self.model.bulk_delete(objects)
 
                 for item in objects:
-                    pk_val = getattr(item, self._pk_name, None)
-                    if pk_val:
+                    pk_val = self._item_identity(item)
+                    if pk_val is not None:
                         self._remove_from_active(pk_val)
 
                 vcprint(
@@ -822,8 +858,8 @@ class BaseManager(Generic[ModelT]):
                 for item in objects:
                     try:
                         success = await self._delete_item(item)
-                        pk_val = getattr(item, self._pk_name, None)
-                        if success and pk_val:
+                        pk_val = self._item_identity(item)
+                        if success and pk_val is not None:
                             self._remove_from_active(pk_val)
                             success_count += 1
                     except Exception as individual_error:

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/core/relations.py

@@ -365,12 +365,26 @@ class ManyToManyReference:
             "target_model": self.target_model if isinstance(self.target_model, str) else getattr(self.target_model, '__name__', str(self.target_model)),
         }
 
+    @staticmethod
+    def _single_pk(model_cls: type[Model], side: str) -> str:
+        """M2M traversal keys each side by ONE column. A composite-PK endpoint
+        must raise — silently using the first PK column would join/mutate the
+        wrong junction rows."""
+        pks = model_cls._meta.primary_keys
+        if len(pks) != 1:
+            raise ValueError(
+                f"ManyToMany {side} model {model_cls.__name__} has a composite "
+                f"primary key {tuple(pks)}; M2M traversal supports single-column "
+                f"primary keys only. Query the junction table's model directly."
+            )
+        return pks[0]
+
     async def fetch_related(self, instance: Model) -> list[Model]:
         """Single-query JOIN: junction table + target model in one round-trip."""
         from matrx_orm.adapters import AdapterRegistry
         from matrx_orm.exceptions import ORMException
 
-        pk_field = instance._meta.primary_keys[0]
+        pk_field = self._single_pk(instance.__class__, "source")
         source_value = getattr(instance, pk_field)
         if source_value is None:
             return []
@@ -383,7 +397,7 @@ class ManyToManyReference:
             target_table = target_model._meta.qualified_table_name
 
             # Determine the target PK column name (nearly always "id")
-            target_pk = target_model._meta.primary_keys[0]
+            target_pk = self._single_pk(target_model, "target")
 
             sql = (
                 f"SELECT t.* FROM {target_table} t "
@@ -408,7 +422,7 @@ class ManyToManyReference:
         from matrx_orm.adapters import AdapterRegistry
         from matrx_orm.exceptions import ORMException
 
-        pk_field = instance._meta.primary_keys[0]
+        pk_field = self._single_pk(instance.__class__, "source")
         source_value = getattr(instance, pk_field)
 
         try:
@@ -443,7 +457,7 @@ class ManyToManyReference:
         from matrx_orm.adapters import AdapterRegistry
         from matrx_orm.exceptions import ORMException
 
-        pk_field = instance._meta.primary_keys[0]
+        pk_field = self._single_pk(instance.__class__, "source")
         source_value = getattr(instance, pk_field)
 
         try:
@@ -473,7 +487,7 @@ class ManyToManyReference:
         from matrx_orm.adapters import AdapterRegistry
         from matrx_orm.exceptions import ORMException
 
-        pk_field = instance._meta.primary_keys[0]
+        pk_field = self._single_pk(instance.__class__, "source")
         source_value = getattr(instance, pk_field)
 
         try:

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/operations/delete.py

@@ -25,7 +25,24 @@ async def bulk_delete(model_cls: type[Model], objects: Sequence[Model]) -> int:
     if not objects:
         return 0
 
-    pk_name = model_cls._meta.primary_keys[0] if model_cls._meta.primary_keys else "id"
+    pk_list = model_cls._meta.primary_keys or ["id"]
+
+    if len(pk_list) > 1:
+        # Composite PK: no single-column `__in` exists. Delete per-row on the
+        # FULL key — filtering on the first column alone would wipe every row
+        # sharing that value.
+        rows_affected = 0
+        for obj in objects:
+            pk_filter = {pk: getattr(obj, pk, None) for pk in pk_list}
+            if any(v is None for v in pk_filter.values()):
+                continue
+            deleted = await delete(model_cls, **pk_filter)
+            if deleted:
+                rows_affected += deleted
+                await StateManager.remove(model_cls, obj)
+        return rows_affected
+
+    pk_name = pk_list[0]
     ids = [
         getattr(obj, pk_name)
         for obj in objects
@@ -66,11 +83,15 @@ async def delete_instance(instance: Model) -> None:
     pk_list = model_cls._meta.primary_keys
     if not pk_list:
         raise ValueError(f"Cannot delete {model_cls.__name__} with no primary key.")
-    pk_name = pk_list[0]
-    pk_value = getattr(instance, pk_name, None)
-    if pk_value is None:
-        raise ValueError(f"Cannot delete {model_cls.__name__}, {pk_name} is None")
+    # WHERE must carry EVERY primary-key column — first-column-only deletes
+    # every row sharing that value on a composite-PK table.
+    pk_filter: dict[str, Any] = {}
+    for pk in pk_list:
+        value = getattr(instance, pk, None)
+        if value is None:
+            raise ValueError(f"Cannot delete {model_cls.__name__}, primary key {pk} is None")
+        pk_filter[pk] = value
 
     await pre_delete.send(model_cls, instance=instance)
-    await delete(model_cls, **{pk_name: pk_value})
+    await delete(model_cls, **pk_filter)
     await post_delete.send(model_cls, instance=instance)

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/operations/read.py

@@ -43,7 +43,13 @@ async def values_list(model_cls, *fields, flat=False, **kwargs):
 
 async def in_bulk(model_cls, id_list, field=None):
     if field is None:
-        field = model_cls._meta.primary_keys[0] if model_cls._meta.primary_keys else "id"
+        pks = model_cls._meta.primary_keys
+        if len(pks) > 1:
+            raise ValueError(
+                f"{model_cls.__name__} has a composite primary key {tuple(pks)} — "
+                f"in_bulk() needs an explicit single `field` to key results on."
+            )
+        field = pks[0] if pks else "id"
     objects = await QueryBuilder(model_cls).filter(**{f"{field}__in": id_list}).all()
     return {getattr(obj, field): obj for obj in objects}
 

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/operations/update.py

@@ -34,9 +34,9 @@ async def bulk_update(model_cls: type[Model], objects: Sequence[Model], fields:
         vcprint(model_cls._fields, "Model Fields", color="yellow")
         raise ValueError(f"Invalid fields for {model_cls.__name__}: {invalid_fields}")
 
-    pk_name = model_cls._meta.primary_keys[0] if model_cls._meta.primary_keys else "id"
+    pk_list = model_cls._meta.primary_keys or ["id"]
     valid_objects = [
-        obj for obj in objects if getattr(obj, pk_name, None) is not None
+        obj for obj in objects if all(getattr(obj, pk, None) is not None for pk in pk_list)
     ]
     if not valid_objects:
         return 0
@@ -47,7 +47,8 @@ async def bulk_update(model_cls: type[Model], objects: Sequence[Model], fields:
     failed_updates: list[dict[str, Any]] = []
 
     for i, obj in enumerate(valid_objects):
-        pk_value = getattr(obj, pk_name)
+        pk_filter = {pk: getattr(obj, pk) for pk in pk_list}
+        pk_value = pk_filter if len(pk_list) > 1 else next(iter(pk_filter.values()))
         try:
             update_data: dict[str, Any] = {}
             for field_name in fields:
@@ -59,7 +60,7 @@ async def bulk_update(model_cls: type[Model], objects: Sequence[Model], fields:
 
             if update_data:
                 result = (
-                    await QueryBuilder(model_cls).filter(**{pk_name: pk_value}).update(**update_data)
+                    await QueryBuilder(model_cls).filter(**pk_filter).update(**update_data)
                 )
                 if result.rows_affected > 0:
                     rows_affected += 1
@@ -140,10 +141,14 @@ async def update_instance(instance: Model, fields: Iterable[str] | None = None)
     pk_list = model_cls._meta.primary_keys
     if not pk_list:
         raise ValueError(f"Cannot update {model_cls.__name__} with no primary key.")
-    pk_name = pk_list[0]
-    pk_value = getattr(instance, pk_name, None)
-    if pk_value is None:
-        raise ValueError(f"Cannot update {model_cls.__name__}, {pk_name} is None")
+    # WHERE must carry EVERY primary-key column. Filtering on pk_list[0] alone
+    # updated every row sharing the first key value on a composite-PK table.
+    pk_filter: dict[str, Any] = {}
+    for pk in pk_list:
+        value = getattr(instance, pk, None)
+        if value is None:
+            raise ValueError(f"Cannot update {model_cls.__name__}, primary key {pk} is None")
+        pk_filter[pk] = value
 
     version_field_name: str | None = None
     current_version: int | None = None
@@ -157,10 +162,10 @@ async def update_instance(instance: Model, fields: Iterable[str] | None = None)
     field_names: Iterable[str] = (
         fields
         if fields is not None
-        else [f for f in model_cls._fields if f != pk_name]
+        else [f for f in model_cls._fields if f not in pk_filter]
     )
     for field_name in field_names:
-        if field_name == pk_name:
+        if field_name in pk_filter:
             continue
         if field_name not in model_cls._fields:
             continue
@@ -182,7 +187,7 @@ async def update_instance(instance: Model, fields: Iterable[str] | None = None)
     if version_field_name is not None and update_data:
         update_data[version_field_name] = (current_version or 1) + 1
 
-    filters: dict[str, Any] = {pk_name: pk_value}
+    filters: dict[str, Any] = dict(pk_filter)
     if version_field_name is not None and current_version is not None:
         filters[version_field_name] = current_version
 
@@ -198,11 +203,11 @@ async def update_instance(instance: Model, fields: Iterable[str] | None = None)
         if version_field_name is not None:
             raise OptimisticLockError(
                 model=model_cls,
-                pk=pk_value,
+                pk=pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values())),
                 expected_version=current_version,
             )
         raise ValueError(
-            f"No rows were updated for {model_cls.__name__} with {pk_name}={pk_value}"
+            f"No rows were updated for {model_cls.__name__} with {pk_filter}"
         )
 
     if result.updated_rows:

{matrx_orm-3.1.4 → matrx_orm-3.1.6}/matrx_orm/query/builder.py

@@ -80,12 +80,18 @@ def _merge_pending_into_models(model_cls: type, db_models: list, filters: dict[s
         filters,
     )
 
-    # Telemetry: count rows that came from Session state.
-    db_pks = {d.get(model_cls._meta.primary_keys[0]) for d in db_dicts if isinstance(d, dict)}
+    # Telemetry: count rows that came from Session state. Row identity is the
+    # FULL primary key — first-column-only would conflate composite-PK rows.
+    _pk_names = model_cls._meta.primary_keys or ["id"]
+
+    def _row_key(d: dict) -> tuple:
+        return tuple(d.get(pk) for pk in _pk_names)
+
+    db_pks = {_row_key(d) for d in db_dicts if isinstance(d, dict)}
     merged_extra = sum(
         1
         for d in merged_dicts
-        if isinstance(d, dict) and d.get(model_cls._meta.primary_keys[0]) not in db_pks
+        if isinstance(d, dict) and _row_key(d) not in db_pks
     )
     if merged_extra:
         try:
@@ -805,9 +811,10 @@ class QueryBuilder(Generic[ModelT]):
             raise
 
     async def last(self) -> ModelT | None:
-        """Order by primary key descending and fetch the first record."""
-        pk_name = self.model._meta.primary_keys[0] if self.model._meta.primary_keys else "id"
-        self.order_by(f"-{pk_name}")
+        """Order by primary key (all columns, for composite PKs) descending
+        and fetch the first record."""
+        pk_names = self.model._meta.primary_keys or ["id"]
+        self.order_by(*(f"-{pk}" for pk in pk_names))
         return await self.first()
 
     async def get(self) -> ModelT: