matrx-orm 3.1.28__tar.gz → 3.1.30__tar.gz

{matrx_orm-3.1.28 → matrx_orm-3.1.30}/BASE_CLASS_METHODS.md

@@ -2,7 +2,7 @@
 
 > **`QueryBuilder` chaining is clone-on-chain (copy-on-write), like Django's
 > `QuerySet`.** Every chain method (`.filter()`, `.exclude()`, `.order_by()`,
-> `.join()`, `.annotate()`, `.filter_raw()`, ...) returns a NEW `QueryBuilder`
+> `.join()`, `.annotate()`, ...) returns a NEW `QueryBuilder`
 > and never mutates the one it was called on. It is safe to save a base
 > queryset and branch off it multiple times — each branch is independent:
 >
@@ -62,6 +62,38 @@ The following methods are available directly from all manager classes:
 - `update_where(filters, **updates)`
 - `delete_where(**filters)`
 
+### Atomic queue claims
+
+`Model.claim_batch(set_fields=..., filters=..., order_by=..., limit=...,
+returning=...)` atomically selects and updates a bounded queue batch with
+`FOR UPDATE SKIP LOCKED`, so concurrent workers neither block nor double-claim.
+`filters` accepts either an equality dict or a compound `Q` tree with
+`eq`/`ne`/`gt`/`gte`/`lt`/`lte`/`in`/`isnull` lookups. Database expressions
+such as `Now()` are valid in both filters and `set_fields`.
+
+```python
+from datetime import timedelta
+from matrx_orm import Now, Q
+
+rows = await ToolCall.claim_batch(
+    set_fields={
+        "claimed_by_instance_id": instance_id,
+        "claimed_at": Now(),
+        "claim_expires_at": Now() + timedelta(hours=6),
+    },
+    filters=(
+        Q(status="delegated", tool_name__in=desktop_tool_names)
+        & (
+            Q(claimed_by_instance_id__isnull=True)
+            | Q(claim_expires_at__lt=Now())
+        )
+    ),
+    order_by="created_at",
+    limit=100,
+    returning=["id", "call_id", "tool_name"],
+)
+```
+
 ### Load / Query
 - `load_item(use_cache=True, **kwargs)`
 - `load_item_or_none(use_cache=True, **kwargs)`
@@ -258,41 +290,13 @@ rows = await (
 )
 ```
 
-### `Filter` / `JsonbObjectAgg` / `ArrayIndex` — FILTER clause, jsonb rollups, array subscript
-
-Three composable primitives (all in `matrx_orm.core.expressions`, exported from `matrx_orm`) for
-per-group rollup dashboards — grown converting a per-source-kind admin summary off raw SQL:
+### Typed aggregate expressions
 
-- `Filter(agg, condition, *params)` → `<agg SQL> FILTER (WHERE <condition>)`. `agg` is any
-  expression with `.as_sql()` (`Count`, `Sum`, `JsonbObjectAgg`, `ArrayIndex(ArrayAgg(...), n)`,
-  ...). `condition` is a raw SQL boolean fragment — same convention as `filter_raw`: write
-  `$1, $2, ...` and pass the matching values as `*params`; no params needed for a static
-  condition like `"parent_chunk_id IS NULL"`.
-- `JsonbObjectAgg(key, value)` → `jsonb_object_agg(key, value)`. `key`/`value` are usually raw
-  SQL expression strings (`"COALESCE(metadata->>'k', 'unknown')"`, `"count(*)"`) — a bare string
-  is embedded verbatim, same convention as every other raw column/expression string in this ORM
-  (`order_by`, `select`, `group_by`).
-- `ArrayIndex(expr, index)` → `(expr)[index]` — the "pick one arbitrary value from the group"
-  pattern paired with `ArrayAgg`.
-
-```python
-from matrx_orm import ArrayAgg, ArrayIndex, Coalesce, Count, Filter, JsonbObjectAgg, Sum, Cast
-
-rows = await (
-    KgChunks.filter(valid_to__isnull=True)
-    .annotate(
-        owner_id=ArrayIndex(ArrayAgg("owner_id::text"), 1),
-        parent_count=Filter(Count("*"), "parent_chunk_id IS NULL"),
-        total_tokens=Cast(Coalesce(Sum("token_count"), 0), "bigint"),
-        section_histogram=Filter(
-            JsonbObjectAgg("COALESCE(metadata->>'section_kind', 'unknown')", "count(*)"),
-            "parent_chunk_id IS NULL",
-        ),
-    )
-    .group_by("source_kind", "source_id")
-    .values("owner_id", "parent_count", "total_tokens", "section_histogram")
-)
-```
+`ArrayAgg`, `ArrayIndex`, `Count`, `Sum`, `Coalesce`, and `Cast` compose
+typed per-group rollups. Application callers pass field references (`F`) and
+typed expression objects. Legacy string-condition aggregate constructors are
+internal compatibility surfaces, not application APIs; add a typed expression
+primitive when a rollup shape is missing.
 
 ### `.having()` resolves an `.annotate()` alias to its aggregate expression
 
@@ -316,18 +320,14 @@ rows = await (
 )
 ```
 
-A `.having()` key that does **not** match any `.annotate()` alias is left untouched — rendered
-verbatim as a raw column/expression, exactly as before this fix. That's still a valid escape
-hatch (e.g. `.having(**{"COUNT(*)__gte": 5})`), but referencing the alias directly is preferred:
-one definition of the aggregate (in `.annotate()`), not two that must be kept in sync by hand.
+A `.having()` key should reference an `.annotate()` alias. Missing HAVING
+shapes belong in the typed expression layer.
 
-### `Subquery` / `Exists` now honor an inner `.filter_raw()`
+### Typed `Subquery` / `Exists`
 
-A correlated `Subquery(Model.filter(...).filter_raw(...))` used to silently DROP the
-`filter_raw` fragment (only structured `filters` were translated). Fixed — the fragment's own
-`$N` placeholders are shifted/bound exactly like the top-level case. The fragment can reference
-the outer table directly by its qualified name (no `OuterRef` needed for a raw fragment — write
-the qualified reference yourself, e.g. `f"{outer_table}.id::text = ..."`).
+Correlated subqueries compose `Compare`, `Is`, `OuterRef`, and nested
+`Exists` predicates. Parameter numbering is shifted safely at every nesting
+level; application callers never write a fragment or placeholder.
 
 ### `JsonbMerge` — atomic shallow merge under a runtime key
 
@@ -351,6 +351,31 @@ await Files.update_where(
 )
 ```
 
+### `JsonbConcat` — jsonb concat of two EXPRESSIONS (columns, `F()`, `Excluded()`)
+
+`JsonbConcat(left, right)` (in `matrx_orm.core.expressions`, exported from `matrx_orm`) renders
+`(<left> || <right>)`. Unlike `JsonbMerge`, **neither operand is a Python literal** — both sides
+are themselves renderable expressions. This is the primitive an `ON CONFLICT DO UPDATE SET`
+"union the old and new jsonb, new keys winning" merge needs, where the RHS is the proposed
+insert row's own column:
+
+```python
+from matrx_orm import Excluded, F, JsonbConcat
+from matrx_orm.operations.conflict_writes import bulk_upsert_increment
+
+table = ProviderCall._meta.qualified_table_name
+await bulk_upsert_increment(
+    ProviderCall, rows, on_conflict=["run_id", "provider_call_key"],
+    set_fields={"metadata": JsonbConcat(F(f"{table}.metadata"), Excluded("metadata"))},
+)
+# -> metadata = (seo.provider_call.metadata || EXCLUDED.metadata)
+```
+
+Grown 2026-07-23 converting `matrx-seo`'s retried-provider-call evidence merge off a raw SQL
+string (`f"{table}.metadata || EXCLUDED.metadata"`) — `bulk_upsert_increment`'s `set_fields`
+values must be `Excluded(...)` or an object exposing `.as_sql(params)`; a bare f-string is
+rejected loudly by `_render_set_field_value`.
+
 ### Atomic correlated-subquery UPDATE — `update(col=Subquery(...))`
 
 `QueryBuilder.update(**kwargs)` (and `Model.update_where(filters, **updates)`, which
@@ -384,7 +409,7 @@ Tests: `packages/matrx-orm/tests/level1/test_update_subquery.py`.
 
 ### Bulk UPDATE with heterogeneous per-row values — `bulk_update_by_pk`
 
-`Model.bulk_update_by_pk(objects_data, *, pk_field="id", casts=None, extra_set=None,
+`Model.bulk_update_by_pk(objects_data, *, pk_field="id", casts=None, set_expressions=None,
 connection=None)` (also `matrx_orm.bulk_update_by_pk(model_cls, ...)`) — a set-based
 `UPDATE t SET col = v.col, ... FROM (VALUES (...), ...) AS v(pk, col, ...) WHERE t.pk =
 v.pk`, ONE round trip regardless of row count. Unlike `Model.bulk_update` (a loop of N
@@ -424,34 +449,29 @@ await KgChunks.bulk_update_by_pk(
         "page_numbers": "int[]",
         "page_spans": "jsonb",
     },
-    extra_set={"updated_at": "now()"},
+    set_expressions={"updated_at": Now()},
     connection=conn,  # the advisory-lock-holding connection
 )
 ```
 
 `casts` — `{column: pg_type}` for a column asyncpg can't infer unambiguously (an
-all-NULL column across the batch, jsonb, uuid, a typed array — the same reason the raw
-SQL this replaces cast every placeholder explicitly). `extra_set` — `{column:
-trusted_sql_fragment}` for a column every row gets the SAME value for (code-supplied,
-never user input — same trust model as `ConflictTarget`). Returns the count of rows
+all-NULL column across the batch, jsonb, uuid, or a typed array).
+`set_expressions` — `{column: typed_expression}` for a column every row gets the
+same value (`Now()`, `Value(None)`, and other expression objects). Returns the count of rows
 actually matched-and-updated. Implementation:
 `packages/matrx-orm/matrx_orm/operations/bulk_update_values.py`.
 
 ### `Case` / `When` — conditional `CASE WHEN ... THEN ... ELSE ... END`
 
-`Case(When(condition, *condition_params, then=...), ..., default=...)` (both in
+`Case(When(predicate, then=...), ..., default=...)` (both in
 `matrx_orm.core.expressions`, exported from `matrx_orm`) — the Django-standard
 conditional expression. Grown to unblock two matrx-rag sites that were kept raw solely
 for want of this (`packages/matrx-rag/matrx_rag/search.py::_entity_recall` /
 `_build_entity_map`).
 
-- `When.condition` — a raw SQL boolean fragment, same convention as `filter_raw` /
-  `Filter`'s `condition`: write `$1, $2, ...` densely from `$1` (reuse OK) and pass the
-  matching values as `*condition_params`; `Case` shifts/binds them into the query's
-  running param sequence.
-- `then=` / `default=` — a literal (bound as a param), a bare column-name **string**
-  (embedded verbatim — same convention as every other `Func` argument / `order_by` /
-  `select`, NOT bound), or any expression object with `.as_sql(params)` (`F`, another
+- `When.condition` — a composable typed `Predicate` (`Compare`, `Is`,
+  `ArrayAny`, `Exists`, or an `&` / `|` / `~` composition).
+- `then=` / `default=` — a bound literal or typed expression (`F`, another
   `Func`, a nested `Case`, ...). `default=None` omits the `ELSE` clause entirely
   (Postgres already evaluates an unmatched `CASE` to `NULL` — behaviourally identical to
   an explicit `ELSE NULL`, so there's no ambiguity with "no default supplied").
@@ -459,43 +479,20 @@ for want of this (`packages/matrx-rag/matrx_rag/search.py::_entity_recall` /
 Composable anywhere an expression with `.as_sql(params)` is accepted:
 
 ```python
-from matrx_orm import Case, OrderBy, When
+from matrx_orm import Case, Compare, F, Lower, OrderBy, When
 
 # ORDER BY exact-match-first tiebreak, then confidence DESC NULLS LAST
 qb.order_by(
-    OrderBy(Case(When("lower(e.name) = $1", phrase, then=0), default=1)),
+    OrderBy(Case(When(Compare(Lower(F("name")), "=", phrase), then=0), default=1)),
     OrderBy("confidence_avg", descending=True, nulls="last"),
 )
 
 # .annotate(x=Case(...)) works the same way — any aggregation-block expression.
 ```
 
-**Inside a `join(on=..., on_params=...)` ON-clause** — `join()`'s `on` is a plain string
-built by the caller (not threaded through a shared params list), so use `Case.render()`
-to get a **fresh, `$1`-numbered** fragment (same convention as `filter_raw`) to splice in:
-
-```python
-from matrx_orm import Case, When
-
-# Direction-agnostic partner: whichever endpoint is NOT in top_entity_ids.
-partner = Case(When("ed.src_id = ANY($1::uuid[])", top_entity_ids, then="ed.dst_id"), default="ed.src_id")
-on_sql, on_params = partner.render()
-
-rows = await (
-    KgEdges.filter(kind="co_occurs_with")
-    .from_alias("ed")
-    .join(KgEntities, on=f"e2.id = {on_sql}", on_params=on_params, alias="e2")
-    .filter_raw("(ed.src_id = ANY($1::uuid[]) OR ed.dst_id = ANY($1::uuid[]))", top_entity_ids)
-    .annotate(total_weight=Sum("ed.weight"))
-    .group_by("ed.src_id", "ed.dst_id", "e2.id", "e2.name", "e2.kind")
-    .fetch_via(conn, "ed.src_id", "ed.dst_id", "e2.id AS partner_id", "e2.name AS partner_name", "e2.kind AS partner_kind", "total_weight")
-)
-```
-
-`join()` grew an `on_params: list[Any] | None = None` kwarg for this — `on`'s own
-`$1, $2, ...` placeholders (dense from `$1`) are shifted into the query's running param
-sequence at the point the JOIN clause is rendered (before WHERE), exactly like
-`filter_raw`. Omit `on_params` for the existing plain-string-`on` usage — unchanged.
+Join conditions and CASE branches must be built from typed field references
+and predicates. If a join shape cannot yet accept the expression directly,
+grow the join API instead of assembling SQL in application code.
 
 Tests: `packages/matrx-orm/tests/level1/test_case_when.py`.
 
@@ -510,12 +507,15 @@ bind the `Case` OBJECT as a query parameter. The executor now has a generic
 expression class gets `.update()` support for free, no new `isinstance` branch needed.
 
 ```python
-from matrx_orm import Case, F, When
+from matrx_orm import Case, Compare, F, Interval, Now, When
 
 await OrganizationPreferences.update_where(
     {"organization_id": org_id},
     cost_used_usd=Case(
-        When(f"{table}.window_start < now() - interval '24 hours'", then=cost_usd),
+        When(
+            Compare(F(f"{table}.window_start"), "<", Now() - Interval(hours=24)),
+            then=cost_usd,
+        ),
         default=F(f"{table}.cost_used_usd") + cost_usd,
     ),
 )
@@ -630,7 +630,6 @@ alone drives the whole conflict-time SET (at least one of the two is required).
 `set_fields` — `{column: value}` where `value` is one of:
 
 * `Excluded(column)` → `col = EXCLUDED.col`;
-* a trusted raw SQL fragment string with NO placeholders (e.g. `"now()"`);
 * **any expression object exposing `.as_sql(params)`** — `Case`, `Coalesce`, `F`
   arithmetic, or a nested combination — for a conflict-time SET that needs to branch on
   or reference the row's OLD (pre-conflict) value. Reference the old value via
@@ -645,18 +644,21 @@ This is the primitive behind the atomic 24h window-roll cost counter (an
 whether the stored window has gone stale — previously only expressible as hand-written SQL):
 
 ```python
-from matrx_orm import Case, F, Now, When
+from matrx_orm import Case, Compare, F, Interval, Is, Now, When
 
 table = OrganizationPreferences._meta.qualified_table_name
-stale = f"{table}.window_start IS NULL OR {table}.window_start < now() - interval '24 hours'"
+stale = (
+    Is(F(f"{table}.window_start"), None)
+    | Compare(F(f"{table}.window_start"), "<", Now() - Interval(hours=24))
+)
 
 await OrganizationPreferences.bulk_upsert_increment(
     [{"organization_id": org_id, "cost_used_usd": cost, "window_start": now, "updated_at": now}],
     on_conflict=["organization_id"],
     set_fields={
-        "window_start": Case(When(stale, then=Now()), default=f"{table}.window_start"),
+        "window_start": Case(When(stale, then=Now()), default=F(f"{table}.window_start")),
         "cost_used_usd": Case(When(stale, then=cost), default=F(f"{table}.cost_used_usd") + cost),
-        "updated_at": "now()",
+        "updated_at": Now(),
     },
 )
 ```
@@ -678,14 +680,13 @@ preserve an omitted field instead of clobbering it with NULL on every write).
 
 `on_conflict` — a plain `list[str]` of columns, or a `ConflictTarget` (see
 above) for an expression/partial-index target. `set_fields` — `{column:
-Excluded(column) | trusted_sql_fragment | <expression with .as_sql(params)>}`
-(same three-way contract as `bulk_upsert_increment`'s `set_fields` above); any
+Excluded(column) | <typed expression with .as_sql(params)>}`
+(same contract as `bulk_upsert_increment`'s `set_fields` above); any
 column in `data` not given an explicit entry defaults to `Excluded(col)` (plain
-replace). Same trust model as `ConflictTarget` — fragments are code-supplied,
-never user input.
+replace).
 
 ```python
-from matrx_orm import ConflictTarget, Excluded
+from matrx_orm import Excluded, Now
 from matrx_orm.operations.conflict_writes import upsert_with_conflict
 
 row = await upsert_with_conflict(
@@ -696,64 +697,25 @@ row = await upsert_with_conflict(
         "description": description, "category": category,
         "is_active": True, "inject_into_sandbox": True,
     },
-    on_conflict=ConflictTarget(expressions=["user_id", "key"], where="deleted_at IS NULL"),
+    on_conflict=["user_id", "key"],
     set_fields={
         "value_encrypted": Excluded("value_encrypted"),
         "value_hint": Excluded("value_hint"),
-        "description": "COALESCE(EXCLUDED.description, users.user_secrets.description)",
-        "category": "COALESCE(EXCLUDED.category, users.user_secrets.category)",
+        "description": Excluded("description"),
+        "category": Excluded("category"),
         "is_active": Excluded("is_active"),
         "inject_into_sandbox": Excluded("inject_into_sandbox"),
-        "updated_at": "now()",
+        "updated_at": Now(),
     },
 )  # row: dict — the resulting row (RETURNING *)
 ```
 
 Tests: `packages/matrx-orm/tests/level1/test_upsert_with_conflict.py`.
 
-### `execute_insert_select` — set-based `INSERT ... SELECT` between two real tables
-
-`execute_insert_select(config_name, insert_select_sql, *params, connection=None,
-pool=None)` (in `matrx_orm.operations.staging_load`) — runs a caller-built, code-
-supplied `INSERT INTO <target> SELECT ... FROM <source> [WHERE ...] [ON CONFLICT
-... DO UPDATE]` statement in ONE atomic round-trip and returns the affected-row
-count (parsed from the `INSERT 0 N` tag). The set-based sibling of
-`execute_values_upsert` (that one's row source is a caller-supplied `VALUES`
-list; this one's is a caller-supplied `SELECT`) — for "derive N new/updated rows
-from an existing table without the rows ever leaving Postgres" (a
-`DISTINCT ON` + size-filtered fan-in into a denormalised slot table, an
-upsert-from-aggregate refresh, ...). Same trust model as `execute_values_upsert`
-/ `StagingLoad.insert_select` / `ConflictTarget.expressions` / `filter_raw`:
-`insert_select_sql` is TRUSTED, code-supplied SQL text (never built from user
-input), `$1, $2, ...` bound to `*params`.
-
-```python
-from matrx_orm.operations.staging_load import execute_insert_select
-
-n = await execute_insert_select(
-    Model._database,
-    """
-    INSERT INTO workflow.node_data_slot (
-        definition_id, node_id, slot, value, emissions,
-        output_kind, source, captured_at, captured_by, user_id
-    )
-    SELECT $2, o.node_id, 'last_live_output', o.output, o.emissions,
-           o.output_kind, 'live_run', now(), $3, $3
-    FROM (
-        SELECT DISTINCT ON (node_id) *
-        FROM workflow.node_outcome
-        WHERE run_id = $1 AND error IS NULL AND source = 'executor'
-        ORDER BY node_id, step DESC, attempt DESC
-    ) o
-    WHERE pg_column_size(o.output) <= $4
-    ON CONFLICT (definition_id, node_id, slot) DO UPDATE SET
-        value = EXCLUDED.value, emissions = EXCLUDED.emissions,
-        output_kind = EXCLUDED.output_kind, source = EXCLUDED.source,
-        captured_at = EXCLUDED.captured_at, captured_by = EXCLUDED.captured_by,
-        user_id = EXCLUDED.user_id
-    """,
-    run_id, definition_id, user_id, MAX_SLOT_VALUE_BYTES,
-)
-```
+### Typed set-based operations
 
-Tests: `packages/matrx-orm/tests/level1/test_insert_ignore_and_admin_primitives.py::test_execute_insert_select_parses_tag_and_rejects_non_insert`.
+Application callers use named plans such as `LatestPerGroupUpsertPlan`,
+`StageUpsertPlan`, and `ValuesUpsertPlan`. These plans accept model classes,
+validated field names, typed predicates, and bound values. A missing set-based
+shape is added as another named operation in `matrx_orm.operations`; callers do
+not supply statement text.

{matrx_orm-3.1.28 → matrx_orm-3.1.30}/CLAUDE.md

@@ -25,7 +25,11 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Change tracking** — every instance records which columns were **loaded** (a SELECTed row, or the caller's kwargs) and which were **changed**. `save()` writes only those, so `.only("id","email")` + `save()` can never NULL the columns it never fetched (it used to — silent data loss). Mutable containers (jsonb/arrays) are always rewritten when loaded, because `obj.metadata["k"]=1` cannot be seen by `__setattr__`; **reassigning** (`obj.metadata = {...}`) is tracked precisely and is the sanctioned way. `Model._hydrate()` is the ONE row→model entry point.
 - **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`.
-- **Query layer**: `QueryBuilder`, expressions (`F`, `Q`), window functions, CTEs, subqueries.
+- **Query layer**: `QueryBuilder`, typed predicates/projections (`F`, `Q`,
+  `Predicate`, `Projection`), window functions, QueryBuilder-backed CTEs, and
+  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.
 - **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.28 → matrx_orm-3.1.30}/MODEL_API.md

@@ -87,15 +87,6 @@ Reference for `matrx_orm.core.base.Model` (`QueryBuilder` included where `Model.
 
 ---
 
-## Class methods — raw SQL (direct DB adapter)
-
-| Method | Arguments | Returns | Notes |
-|--------|-----------|---------|-------|
-| `raw` | `sql: str`, `*params` | `list[Self]` | Hydrates rows; not in PostgREST client mode |
-| `raw_sql` | `sql: str`, `*params` | `list[dict[str, Any]]` | Plain dict rows |
-
----
-
 ## Class methods — schema helper
 
 | Method | Arguments | Returns |
@@ -192,7 +183,7 @@ Reference for `matrx_orm.core.base.Model` (`QueryBuilder` included where `Model.
 | `select` | `(*fields: str)` |
 | `prefetch_related` | `(*fields: str)` |
 | `select_related` | `(*fields: str)` — FK names; JOIN + hydrate via `set_related` |
-| `join` | `(model_cls, on: str, join_type: str = "INNER")` |
+| `join` | `(model_cls, on: Predicate, join_type: str = "INNER")` |
 | `group_by` | `(*fields: str)` |
 | `having` | `(**kwargs)` — merged to one dict for SQL HAVING |
 | `annotate` | `(**kwargs)` — each value: aggregate/func with `as_sql` or string |
@@ -296,12 +287,6 @@ FK filter names resolve to the **database column** name via `_meta.foreign_keys`
 
 ---
 
-## Raw SQL parameters
-
-Positional `*params` bind as `$1`, `$2`, … (PostgreSQL-style) in generated SQL.
-
----
-
 ## Related types (returns)
 
 - `UpdateResult`: `rows_affected: int`, `updated_rows: list[dict[str, Any]]`, `to_dict()`.
@@ -309,4 +294,6 @@ Positional `*params` bind as `$1`, `$2`, … (PostgreSQL-style) in generated SQL
 
 ---
 
-*Generated from package sources; behavior may differ per database adapter (e.g. PostgREST: `raw` / DDL / some write paths not supported).*
+*Generated from package sources; behavior may differ per database adapter
+(e.g. DDL and some write paths are unavailable in PostgREST mode). Application
+callers use typed models, predicates, expressions, and operations only.*

{matrx_orm-3.1.28 → matrx_orm-3.1.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.28
+Version: 3.1.30
 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.28 → matrx_orm-3.1.30}/matrx_orm/__init__.py

@@ -29,6 +29,11 @@ from .core.config import (
     resolve_pool_mode,
 )
 from .core.db_function import ArrayArg, call_function, call_function_sync
+from .core.connections import (
+    create_external_pool,
+    get_registered_pool,
+    open_listener_connection,
+)
 from .entity import EntityCapabilityError, MatrxEntity
 from .core.diagnostics import collect_pool_diagnostics, log_pool_diagnostics
 from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
@@ -44,6 +49,8 @@ from .core.expressions import (
     Abs,
     Aggregate,
     ArrayAgg,
+    ArrayAny,
+    ArrayContains,
     ArrayIndex,
     ArrayLength,
     Avg,
@@ -51,11 +58,13 @@ from .core.expressions import (
     Case,
     Cast,
     ColumnComparison,
+    Compare,
     Coalesce,
     Concat,
     Count,
     CumeDist,
     DateTrunc,
+    DbFunction,
     DenseRank,
     Excluded,
     Exists,
@@ -67,6 +76,12 @@ from .core.expressions import (
     Func,
     Greatest,
     JsonText,
+    JsonPath,
+    JsonArrayPathExists,
+    Projection,
+    Like,
+    Regex,
+    JsonbConcat,
     JsonbMerge,
     JsonbObjectAgg,
     Lag,
@@ -82,7 +97,13 @@ from .core.expressions import (
     Ntile,
     OrderBy,
     OuterRef,
+    Predicate,
     PercentRank,
+    ConstantPredicate,
+    Interval,
+    Is,
+    TupleInArrays,
+    Value,
     Q,
     Rank,
     Round,
@@ -192,8 +213,6 @@ from .core.transaction import (
     advisory_lock,
     advisory_unlock,
     advisory_xact_lock,
-    execute_admin_command,
-    execute_admin_sql,
     set_local_guc,
     transaction,
     try_advisory_lock,
@@ -449,6 +468,21 @@ __all__ = [
     "OuterRef",
     "Subquery",
     "Exists",
+    "Predicate",
+    "Compare",
+    "Is",
+    "Value",
+    "JsonPath",
+    "JsonArrayPathExists",
+    "Projection",
+    "Like",
+    "Regex",
+    "DbFunction",
+    "ArrayAny",
+    "ArrayContains",
+    "TupleInArrays",
+    "ConstantPredicate",
+    "Interval",
     "Func",
     "Aggregate",
     "Coalesce",
@@ -469,6 +503,7 @@ __all__ = [
     "ArrayLength",
     "ArrayIndex",
     "JsonText",
+    "JsonbConcat",
     "JsonbMerge",
     "JsonbObjectAgg",
     "Filter",
@@ -525,8 +560,6 @@ __all__ = [
     "try_advisory_lock",
     "advisory_unlock",
     "rls_session",
-    "execute_admin_sql",
-    "execute_admin_command",
     # ── Resilience (opt-in transient-failure retry) ──────────────────────────
     "retry_on_transient",
     "is_read_only_sql",

{matrx_orm-3.1.28 → matrx_orm-3.1.30}/matrx_orm/adapters/MODULE_README.md

@@ -85,7 +85,6 @@ Filepath: src/matrx_orm/adapters/postgresql.py  [python]
       async def update(self, query: Dict[str, Any], data: Dict[str, Any]) -> int
       async def bulk_update(self, query: Dict[str, Any]) -> int
       async def delete(self, query: Dict[str, Any]) -> int
-      async def raw_sql(self, sql: str, params: List[Any] = None) -> Union[List[Dict[str, Any]], int]
       async def close(self)
       async def transaction(self)
       async def savepoint(self, name: str)
@@ -115,7 +114,6 @@ Filepath: src/matrx_orm/adapters/base_adapter.py  [python]
       async def update(self, query: Dict[str, Any], data: Dict[str, Any]) -> int
       async def bulk_update(self, query: Dict[str, Any]) -> int
       async def delete(self, query: Dict[str, Any]) -> int
-      async def raw_sql(self, sql: str, params: List[Any] = None) -> Union[List[Dict[str, Any]], int]
       async def transaction(self)
       async def close(self)
       async def __aenter__(self)
@@ -146,11 +144,6 @@ src.matrx_orm.adapters.postgresql.__init__ → src.matrx_orm.adapters.postgresql
   async src.matrx_orm.adapters.postgresql.update → connection.execute(sql, *params) (line 59)
   async src.matrx_orm.adapters.postgresql.bulk_update → connection.executemany(sql, params) (line 65)
   async src.matrx_orm.adapters.postgresql.delete → connection.execute(sql, *params) (line 71)
-  async src.matrx_orm.adapters.postgresql.raw_sql → startswith('SELECT') (line 76)
-  async src.matrx_orm.adapters.postgresql.raw_sql → upper() (line 76)
-  async src.matrx_orm.adapters.postgresql.raw_sql → sql.strip() (line 76)
-  async src.matrx_orm.adapters.postgresql.raw_sql → connection.fetch(sql, *params) (line 77)
-  async src.matrx_orm.adapters.postgresql.raw_sql → connection.execute(sql, *params) (line 80)
   async src.matrx_orm.adapters.postgresql.close → ...is_closed() (line 83)
   async src.matrx_orm.adapters.postgresql.close → ...close() (line 84)
   async src.matrx_orm.adapters.postgresql.transaction → connection.transaction() (line 88)

{matrx_orm-3.1.28 → matrx_orm-3.1.30}/matrx_orm/adapters/__init__.py

@@ -26,6 +26,7 @@ Register any ``BaseAdapter`` subclass before the first query::
     from matrx_orm.adapters import AdapterRegistry
     AdapterRegistry.register("my_project", MyCustomAdapter("my_project"))
 """
+
 from __future__ import annotations
 
 import logging
@@ -69,9 +70,7 @@ class AdapterRegistry:
         Replaces any previously registered adapter for the same config_name.
         """
         if not isinstance(adapter, BaseAdapter):
-            raise TypeError(
-                f"adapter must be a BaseAdapter subclass, got {type(adapter)!r}"
-            )
+            raise TypeError(f"adapter must be a BaseAdapter subclass, got {type(adapter)!r}")
         cls._adapters[config_name] = adapter
         logger.debug("Registered adapter %r for config %r", type(adapter).__name__, config_name)
 
@@ -92,6 +91,7 @@ class AdapterRegistry:
         an aliased config name shares the target's adapter instance.
         """
         from matrx_orm.core.config import resolve_database_name
+
         config_name = resolve_database_name(config_name)
         if config_name not in cls._adapters:
             cls._adapters[config_name] = cls._create_default(config_name)
@@ -107,6 +107,7 @@ class AdapterRegistry:
 
         if adapter_type == "supabase":
             from matrx_orm.adapters.supabase_adapter import SupabaseAdapter
+
             return SupabaseAdapter(config_name)
 
         # Allow dotted class path: "mypackage.adapters.MyAdapter"
@@ -125,6 +126,7 @@ class AdapterRegistry:
         """Read adapter_type from the registered DatabaseProjectConfig."""
         try:
             from matrx_orm.core.config import registry as _db_registry
+
             config = _db_registry._configs.get(config_name)
             if config is not None:
                 return getattr(config, "adapter_type", "postgresql")
@@ -139,13 +141,12 @@ class AdapterRegistry:
         if not module_path:
             raise ValueError(f"Invalid dotted adapter path: {dotted_path!r}")
         import importlib
+
         module = importlib.import_module(module_path)
         klass = getattr(module, class_name)
         instance = klass(config_name)
         if not isinstance(instance, BaseAdapter):
-            raise TypeError(
-                f"{dotted_path} does not produce a BaseAdapter subclass"
-            )
+            raise TypeError(f"{dotted_path} does not produce a BaseAdapter subclass")
         return instance
 
     # ------------------------------------------------------------------