matrx-orm 3.1.20__tar.gz → 3.1.22__tar.gz

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.20
+Version: 3.1.22
 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
@@ -113,6 +113,17 @@ The migration system tracks which branch a migration originated on and refuses t
 
 ### Mount the admin router
 
+Rows with composite primary keys expose an opaque `__matrx_row_id` in list
+responses and a matching virtual primary-key column descriptor. Pass that value
+unchanged to row-detail, update, delete, and cache-eviction routes; the router
+decodes it into the complete composite key. This also gives generated read-only
+views collision-safe row navigation.
+
+Generated views default to `id` only when they project it. Every other view must
+declare bounded, unique columns in
+`generate[].output.view_primary_keys`; generation fails instead of guessing a
+first column or embedding an unbounded projected row in an identifier.
+
 ```python
 from fastapi import FastAPI
 from matrx_orm import admin_router

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/README.md

@@ -76,6 +76,17 @@ The migration system tracks which branch a migration originated on and refuses t
 
 ### Mount the admin router
 
+Rows with composite primary keys expose an opaque `__matrx_row_id` in list
+responses and a matching virtual primary-key column descriptor. Pass that value
+unchanged to row-detail, update, delete, and cache-eviction routes; the router
+decodes it into the complete composite key. This also gives generated read-only
+views collision-safe row navigation.
+
+Generated views default to `id` only when they project it. Every other view must
+declare bounded, unique columns in
+`generate[].output.view_primary_keys`; generation fails instead of guessing a
+first column or embedding an unbounded projected row in an identifier.
+
 ```python
 from fastapi import FastAPI
 from matrx_orm import admin_router

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/admin/router.py

@@ -24,6 +24,9 @@ Effective routes (relative to the mount prefix):
 
 from __future__ import annotations
 
+import base64
+import binascii
+import json
 import logging
 import math
 import re
@@ -44,6 +47,8 @@ log = logging.getLogger(__name__)
 
 # Must stay in sync with dashboard `ADMIN_LIST_MAX_PAGE_SIZE` (orm-proxy.ts).
 ADMIN_LIST_MAX_PAGE_SIZE = 2000
+COMPOSITE_ROW_ID_FIELD = "__matrx_row_id"
+_COMPOSITE_ROW_ID_PREFIX = "cmp1_"
 
 
 # ---------------------------------------------------------------------------
@@ -116,9 +121,59 @@ def _serialize(instance: Any) -> dict[str, Any]:
         if key in complete:
             continue
         complete[key] = serialize_value(value) if callable(serialize_value) else value
+    primary_keys = list(getattr(meta, "primary_keys", ()) or ())
+    if len(primary_keys) > 1:
+        values = [complete.get(primary_key) for primary_key in primary_keys]
+        payload = json.dumps(
+            values,
+            separators=(",", ":"),
+            sort_keys=True,
+            default=str,
+        ).encode("utf-8")
+        encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+        complete[COMPOSITE_ROW_ID_FIELD] = f"{_COMPOSITE_ROW_ID_PREFIX}{encoded}"
     return complete
 
 
+def _decode_row_id(model: type, row_id: str) -> str | dict[str, Any]:
+    primary_keys = list(model._meta.primary_keys or ())
+    if len(primary_keys) <= 1:
+        return row_id
+    if not row_id.startswith(_COMPOSITE_ROW_ID_PREFIX):
+        raise ValueError(
+            f"{model.__name__} has a composite primary key; use the opaque row identity "
+            f"{COMPOSITE_ROW_ID_FIELD} returned by the list endpoint"
+        )
+    encoded = row_id.removeprefix(_COMPOSITE_ROW_ID_PREFIX)
+    try:
+        payload = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))
+        values = json.loads(payload)
+    except (binascii.Error, ValueError, json.JSONDecodeError) as exc:
+        raise ValueError("Invalid composite row id") from exc
+    if not isinstance(values, list) or len(values) != len(primary_keys):
+        raise ValueError(
+            f"Invalid composite row id: expected {len(primary_keys)} key values"
+        )
+    return dict(zip(primary_keys, values))
+
+
+def _composite_row_id_descriptor() -> dict[str, Any]:
+    return {
+        "column_name": COMPOSITE_ROW_ID_FIELD,
+        "name": COMPOSITE_ROW_ID_FIELD,
+        "field_type": "TextField",
+        "data_type": "text",
+        "is_nullable": False,
+        "is_primary_key": True,
+        "is_unique": True,
+        "default": None,
+        "has_default": False,
+        "is_fk": False,
+        "is_array": False,
+        "description": "Opaque identity for a row with a composite primary key.",
+    }
+
+
 def _safe_scalar(value: Any) -> str | int | float | bool | None:
     """Return value only if it is a JSON-safe scalar; drop everything else."""
     if value is None or callable(value):
@@ -307,8 +362,17 @@ async def _admin_column_descriptors(model: type) -> list[dict[str, Any]]:
     db_rows = await _fetch_db_columns(model)
     orm_fields = model._meta.fields
     if not db_rows:
-        return [_field_descriptor(name, field) for name, field in orm_fields.items()]
-    return [_db_row_to_descriptor(row, orm_fields.get(str(row["column_name"]))) for row in db_rows]
+        columns = [_field_descriptor(name, field) for name, field in orm_fields.items()]
+    else:
+        columns = [
+            _db_row_to_descriptor(row, orm_fields.get(str(row["column_name"])))
+            for row in db_rows
+        ]
+    if len(model._meta.primary_keys or ()) > 1:
+        # Put the opaque composite identity first so clients that select the
+        # first primary-key descriptor cannot accidentally use one component.
+        columns.insert(0, _composite_row_id_descriptor())
+    return columns
 
 
 # Regex to extract values from CHECK constraint definitions like:
@@ -666,7 +730,7 @@ async def get_row(
     log.info("get_row: table=%s id=%s", table_name, row_id)
 
     try:
-        instance = await model.get_by_id(row_id, use_cache=False)
+        instance = await model.get_by_id(_decode_row_id(model, row_id), use_cache=False)
         return JSONResponse(content=_serialize(instance))
     except Exception as exc:
         log.error("get_row: %s/%s failed: %s", table_name, row_id, exc)
@@ -704,7 +768,7 @@ async def update_row(
     log.info("update_row: table=%s id=%s fields=%s", table_name, row_id, list(body.keys()))
 
     try:
-        instance = await model.get_by_id(row_id, use_cache=False)
+        instance = await model.get_by_id(_decode_row_id(model, row_id), use_cache=False)
         await instance.update(**body)
         log.info("update_row: %s/%s updated", table_name, row_id)
         return JSONResponse(content=_serialize(instance))
@@ -723,7 +787,7 @@ async def delete_row(
     log.info("delete_row: table=%s id=%s", table_name, row_id)
 
     try:
-        instance = await model.get_by_id(row_id, use_cache=False)
+        instance = await model.get_by_id(_decode_row_id(model, row_id), use_cache=False)
         await instance.delete()
         log.info("delete_row: %s/%s deleted", table_name, row_id)
         return JSONResponse(status_code=200, content={"deleted": True, "id": row_id})
@@ -760,7 +824,7 @@ async def bulk_delete_rows(
     for raw_id in ids:
         row_id = str(raw_id)
         try:
-            instance = await model.get_by_id(row_id, use_cache=False)
+            instance = await model.get_by_id(_decode_row_id(model, row_id), use_cache=False)
             await instance.delete()
             deleted.append(row_id)
         except Exception as exc:
@@ -819,7 +883,7 @@ async def bulk_update_rows(
     for raw_id in ids:
         row_id = str(raw_id)
         try:
-            instance = await model.get_by_id(row_id, use_cache=False)
+            instance = await model.get_by_id(_decode_row_id(model, row_id), use_cache=False)
             await instance.update(**data)
             updated.append(row_id)
         except Exception as exc:
@@ -892,7 +956,7 @@ async def evict_row_cache(
     log.info("evict_row_cache: %s/%s", table_name, row_id)
 
     try:
-        instance = await model.get_by_id(row_id, use_cache=False)
+        instance = await model.get_by_id(_decode_row_id(model, row_id), use_cache=False)
         await StateManager.remove(model, instance)
         return JSONResponse(content={"evicted": True, "table_name": table_name, "id": row_id})
     except Exception as exc:

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/core/config.py

@@ -34,7 +34,7 @@ class DatabaseProjectConfig:
     field_overrides: dict[str, Any] = field(default_factory=dict)
 
     # Extra PostgreSQL schemas to introspect and include in schema builder output.
-    # For Supabase projects this typically includes ["auth", "storage"].
+    # Hosted projects may add private platform schemas as needed.
     # These schemas live in the same database but outside the default "public" schema.
     additional_schemas: list = field(default_factory=list)
 

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/schema_builder/columns.py

@@ -588,6 +588,16 @@ class Column:
         elif self.full_type in [
             "tsvector",
             "tsquery",
+            "regclass",
+            "regproc",
+            "regprocedure",
+            "regoper",
+            "regoperator",
+            "regtype",
+            "regrole",
+            "regnamespace",
+            "regconfig",
+            "regdictionary",
             "geometry",
             "geography",
             "box",

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/schema_builder/common.py

@@ -78,6 +78,10 @@ class GenerationOutputOverrides:
       exclude_views          names of individual views to skip even when
                              include_views is True (e.g. a view with a column shape
                              the codegen can't represent). Default: none excluded.
+      view_primary_keys      mapping of view name to bounded, unique projected
+                             columns used as the read-only model identity. Views
+                             projecting ``id`` default to ``[id]``; every other
+                             generated view must declare this explicitly.
 
     All fields default to current behavior; an absent yaml block is a no-op.
     """
@@ -90,6 +94,7 @@ class GenerationOutputOverrides:
     emit_managers: bool = True
     include_views: bool = True
     exclude_views: list[str] | None = None
+    view_primary_keys: dict[str, list[str]] | None = None
 
     @classmethod
     def from_dict(cls, d: dict | None) -> GenerationOutputOverrides:
@@ -103,6 +108,11 @@ class GenerationOutputOverrides:
             emit_managers=bool(d.get("emit_managers", True)),
             include_views=bool(d.get("include_views", True)),
             exclude_views=list(d.get("exclude_views") or []) or None,
+            view_primary_keys={
+                str(view_name): [str(column) for column in columns]
+                for view_name, columns in (d.get("view_primary_keys") or {}).items()
+            }
+            or None,
         )
 
 

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/schema_builder/generator.py

@@ -239,4 +239,4 @@ class {name_camel}Manager(BaseManager):
 
     async def _initialize_runtime_data(self, item: {name_camel}) -> None:
         pass
-    """
+"""

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/schema_builder/schema.py

@@ -65,6 +65,7 @@ class Schema:
         self._emit_managers = self.output_overrides.emit_managers
         self._include_views = self.output_overrides.include_views
         self._exclude_views = set(self.output_overrides.exclude_views or [])
+        self._view_primary_keys = self.output_overrides.view_primary_keys or {}
         self.tables = {}
         self.views = {}
         self.model_export_names: list[str] = []
@@ -1054,7 +1055,12 @@ class Schema:
                 try:
                     view_src, view_model_name, view_field_types = view.to_python_model(
                         model_database_name=self._model_database_name,
+                        primary_keys=self._view_primary_keys.get(view_name),
                     )
+                except ValueError:
+                    # Missing/invalid view identity is a generation contract
+                    # failure, never a relation to silently omit.
+                    raise
                 except Exception as e:  # noqa: BLE001 — one bad view must not kill the run
                     vcprint(
                         f"[MATRX ORM] Skipping view '{self.name}.{view_name}' — "

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/matrx_orm/schema_builder/views.py

@@ -90,9 +90,14 @@ class View:
             except (IndexError, ValueError):
                 return "TextField()"
 
-        try:
-            field_class = self.utils.to_python_models_field(base_type)
-        except ValueError:
+        # pg_catalog identifier/reference types and enum-typed view columns are
+        # read as strings. Views are read-only, so generating writable EnumField
+        # metadata would add complexity without preserving any extra behavior.
+        if base_type == "name" or col.get("enum_labels"):
+            return "TextField()"
+
+        field_class = self.utils.sql_to_python_models_field.get(base_type)
+        if field_class is None:
             vcprint(
                 f"[MATRX ORM] View {self.schema}.{self.name}: column "
                 f"'{col.get('name')}' has unmapped type {base_type!r} "
@@ -107,13 +112,16 @@ class View:
         self,
         *,
         model_database_name: str | None = None,
+        primary_keys: list[str] | None = None,
     ) -> tuple[str, str, set[str]]:
         """Return (class_source, model_class_name, field_type_names) for a
         read-only Model bound to this view.
 
-        Views have no Postgres PK; Models need row identity, so we synthesize
-        ``_primary_keys`` from ``id`` when present, else the first column (cache /
-        ``load_by_id`` only). No ForeignKey — views carry no FK metadata.
+        Views have no Postgres PK, so their identity must come from a bounded,
+        unique projection. ``id`` is the safe default when projected; otherwise
+        the generation config must explicitly name the grouping/identity columns.
+        This prevents first-column collisions and avoids embedding arbitrary row
+        payloads in dashboard URLs. No ForeignKey — views carry no FK metadata.
         """
         columns = self.column_data or []
         py_fields: list[str] = []
@@ -140,14 +148,33 @@ class View:
         if not column_names:
             raise ValueError(f"View {self.schema}.{self.name} has no columns to model.")
 
-        pk = "id" if "id" in column_names else column_names[0]
+        resolved_primary_keys = list(primary_keys or (["id"] if "id" in column_names else []))
+        if not resolved_primary_keys:
+            raise ValueError(
+                f"View {self.schema}.{self.name} has no projected id; declare "
+                "output.view_primary_keys for a bounded unique identity."
+            )
+        if len(set(resolved_primary_keys)) != len(resolved_primary_keys):
+            raise ValueError(
+                f"View {self.schema}.{self.name} declares duplicate identity columns: "
+                f"{resolved_primary_keys}"
+            )
+        missing_primary_keys = [
+            column for column in resolved_primary_keys if column not in column_names
+        ]
+        if missing_primary_keys:
+            raise ValueError(
+                f"View {self.schema}.{self.name} identity columns are not projected: "
+                f"{missing_primary_keys}"
+            )
 
         from matrx_orm.schema_builder.common import safe_model_class_name
 
         model_class_name = safe_model_class_name(self.name, self.schema, self.utils.to_pascal_case)
         db_name = model_database_name or self.database
 
-        py_fields.append(f'_primary_keys = ["{pk}"]')
+        py_fields.append("_read_only = True")
+        py_fields.append(f"_primary_keys = {resolved_primary_keys!r}")
         py_fields.append(f'_table_name = "{self.name}"')
         py_fields.append(f'_db_schema = "{self.schema}"')
         py_fields.append(f'_database = "{db_name}"')

{matrx_orm-3.1.20 → matrx_orm-3.1.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.20"
+version = "3.1.22"
 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.20 → matrx_orm-3.1.22}/tests/level1/test_admin_db_columns.py

@@ -5,8 +5,10 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from matrx_orm.admin.router import (
+    COMPOSITE_ROW_ID_FIELD,
     _admin_column_descriptors,
     _db_row_to_descriptor,
+    _decode_row_id,
     _serialize,
 )
 
@@ -25,6 +27,69 @@ def test_serialize_includes_extra_data() -> None:
     assert out["role"] == "authenticated"
 
 
+def test_composite_row_identity_round_trips() -> None:
+    meta = SimpleNamespace(
+        fields={"site_id": object(), "page_id": object()},
+        primary_keys=["site_id", "page_id"],
+    )
+    instance = SimpleNamespace(
+        to_dict=lambda: {"site_id": "site-1", "page_id": "page/2"},
+        _meta=meta,
+        _extra_data={},
+    )
+    model = SimpleNamespace(__name__="CostByPage", _meta=meta)
+
+    out = _serialize(instance)
+
+    assert out[COMPOSITE_ROW_ID_FIELD].startswith("cmp1_")
+    assert _decode_row_id(model, out[COMPOSITE_ROW_ID_FIELD]) == {
+        "site_id": "site-1",
+        "page_id": "page/2",
+    }
+
+
+def test_composite_row_identity_rejects_scalar() -> None:
+    model = SimpleNamespace(
+        __name__="CostByPage",
+        _meta=SimpleNamespace(primary_keys=["site_id", "page_id"]),
+    )
+
+    with pytest.raises(ValueError, match="opaque row identity"):
+        _decode_row_id(model, "site-1")
+
+
+def test_composite_row_identity_contains_only_declared_key_values() -> None:
+    metadata = {"private": "x" * 10_000}
+    meta = SimpleNamespace(
+        fields={"site_id": object(), "page_id": object(), "metadata": object()},
+        primary_keys=["site_id", "page_id"],
+    )
+    instance = SimpleNamespace(
+        to_dict=lambda: {"site_id": "site-1", "page_id": "page-2", "metadata": metadata},
+        _meta=meta,
+        _extra_data={},
+    )
+
+    encoded = _serialize(instance)[COMPOSITE_ROW_ID_FIELD]
+
+    assert len(encoded) < 100
+    assert _decode_row_id(SimpleNamespace(__name__="View", _meta=meta), encoded) == {
+        "site_id": "site-1",
+        "page_id": "page-2",
+    }
+
+
+@pytest.mark.parametrize("row_id", ["cmp1_not-base64!", "cmp1_WzFd"])
+def test_composite_row_identity_rejects_malformed_payload(row_id: str) -> None:
+    model = SimpleNamespace(
+        __name__="CostByPage",
+        _meta=SimpleNamespace(primary_keys=["site_id", "page_id"]),
+    )
+
+    with pytest.raises(ValueError, match="Invalid composite row id"):
+        _decode_row_id(model, row_id)
+
+
 def test_db_row_to_descriptor_without_orm_field() -> None:
     row = {
         "column_name": "last_sign_in_at",
@@ -84,3 +149,17 @@ async def test_admin_column_descriptors_prefers_live_db() -> None:
             cols = await _admin_column_descriptors(model)
     assert [c["column_name"] for c in cols] == ["id", "email", "created_at"]
     assert cols[2]["field_type"] == "DateTimeField"
+
+
+@pytest.mark.asyncio
+async def test_admin_columns_expose_composite_row_identity_first() -> None:
+    model = MagicMock()
+    model._meta.fields = {"site_id": MagicMock(), "page_id": MagicMock()}
+    model._meta.primary_keys = ["site_id", "page_id"]
+    model._meta.table_name = "v_cost_by_page"
+    model.raw_sql = AsyncMock(return_value=[])
+
+    columns = await _admin_column_descriptors(model)
+
+    assert columns[0]["column_name"] == COMPOSITE_ROW_ID_FIELD
+    assert columns[0]["is_primary_key"] is True

matrx_orm-3.1.22/tests/schema/test_view_generation.py

@@ -0,0 +1,72 @@
+from matrx_orm.schema_builder.views import View
+
+
+def _view(*, base_type: str = "text", multiple_columns: bool = False) -> View:
+    columns = [
+        {
+            "name": "id",
+            "base_type": base_type,
+            "full_type": base_type,
+            "nullable": False,
+        }
+    ]
+    if multiple_columns:
+        columns.append(
+            {
+                "name": "item_id",
+                "base_type": "uuid",
+                "full_type": "uuid",
+                "nullable": False,
+            }
+        )
+    return View(
+        oid=1,
+        name="current_items",
+        type_="view",
+        schema="example",
+        database="test_database",
+        owner="postgres",
+        size_bytes=0,
+        description=None,
+        view_definition="select id from example.items",
+        column_data=columns,
+    )
+
+
+def test_generated_view_model_is_structurally_read_only() -> None:
+    source, _, _ = _view().to_python_model()
+
+    assert "_read_only = True" in source
+
+
+def test_generated_view_uses_declared_composite_identity() -> None:
+    source, _, _ = _view(multiple_columns=True).to_python_model(
+        primary_keys=["id", "item_id"]
+    )
+
+    assert "_primary_keys = ['id', 'item_id']" in source
+
+
+def test_generated_view_defaults_to_projected_id() -> None:
+    source, _, _ = _view(multiple_columns=True).to_python_model()
+
+    assert "_primary_keys = ['id']" in source
+
+
+def test_generated_view_without_id_requires_declared_identity() -> None:
+    view = _view()
+    view.column_data[0]["name"] = "group_name"
+
+    try:
+        view.to_python_model()
+    except ValueError as exc:
+        assert "view_primary_keys" in str(exc)
+    else:
+        raise AssertionError("missing view identity must fail generation")
+
+
+def test_catalog_name_view_column_maps_to_text_without_error() -> None:
+    source, _, field_types = _view(base_type="name").to_python_model()
+
+    assert "id = TextField(null=False)" in source
+    assert field_types == {"TextField"}