matrx-orm 3.1.76__tar.gz → 3.1.78__tar.gz

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/CLAUDE.md

@@ -38,8 +38,11 @@ Every table that becomes a Model needs row identity: a single-column primary key
   Large reconciliation/export scans call `.all(use_cache=False)` so returned
   models do not quadratically populate the process identity cache. Contract:
   [`matrx_orm/query/FEATURE.md`](matrx_orm/query/FEATURE.md).
+- **Conflict writes**: bulk insert-ignore and counter-upsert row coercion runs
+  off the event loop before statement chunking. Contract:
+  [`matrx_orm/operations/FEATURE.md`](matrx_orm/operations/FEATURE.md).
 - **Migrations**: `MigrationDB`, `MigrationLoader`, `MigrationExecutor`, `makemigrations`, `migrate` — migrations declare explicit `dependencies` and apply in topological order (no multi-head/merge support yet).
-- **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model.
+- **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model; bulk response rendering stays off the event loop. Contract: [`matrx_orm/admin/FEATURE.md`](matrx_orm/admin/FEATURE.md).
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.76
+Version: 3.1.78
 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
@@ -25,13 +25,14 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.17
+Requires-Dist: matrx-utils>=2.0.19
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: admin
 Requires-Dist: fastapi>=0.115; extra == 'admin'
+Requires-Dist: orjson>=3.10; extra == 'admin'
 Provides-Extra: api
 Requires-Dist: aiohttp>=3.9.0; extra == 'api'
 Description-Content-Type: text/markdown
@@ -56,6 +57,8 @@ Python 3.13+ required. Needs a PostgreSQL server (or Supabase / any Postgres-com
 - **Admin router** (FastAPI): `admin_router` exposes a ready-to-mount set of read/write endpoints for every registered model.
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
+- **Local artifact reads**: `read_local_sqlite_rows` provides a validated, read-only
+  projection boundary for SQLite files owned by external tools such as Chromium.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the live DB schema — useful for keeping a frontend's row types in sync.
 

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/README.md

@@ -18,6 +18,8 @@ Python 3.13+ required. Needs a PostgreSQL server (or Supabase / any Postgres-com
 - **Admin router** (FastAPI): `admin_router` exposes a ready-to-mount set of read/write endpoints for every registered model.
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
+- **Local artifact reads**: `read_local_sqlite_rows` provides a validated, read-only
+  projection boundary for SQLite files owned by external tools such as Chromium.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the live DB schema — useful for keeping a frontend's row types in sync.
 

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/matrx_orm/__init__.py

@@ -43,6 +43,7 @@ from .platform_db import (
     platform_connection_url,
     register_platform_db,
 )
+from .local_sqlite import SQLiteValue, read_local_sqlite_rows
 from .core.diagnostics import collect_pool_diagnostics, log_pool_diagnostics
 from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
 from .core.one_database import OneDatabaseReport, PoolIdentity, audit_one_database
@@ -633,6 +634,12 @@ __all__ = [
     "AsyncPostgreSQLAdapter",
     "SupabaseAdapter",
     "PostgRESTClientAdapter",
+    "create_external_pool",
+    "get_registered_pool",
+    "open_listener_connection",
+    # ── Read-only local SQLite artifacts ──────────────────────────────────────
+    "SQLiteValue",
+    "read_local_sqlite_rows",
     # ── Cache ──────────────────────────────────────────────────────────────────
     "CachePolicy",
     "StateManager",

matrx_orm-3.1.78/matrx_orm/admin/FEATURE.md

@@ -0,0 +1,34 @@
+# Admin router
+
+`router.py` exposes model-registry CRUD and cache operations through the optional
+FastAPI admin surface.
+
+## Response rendering
+
+- **Bulk row rendering never runs on the event loop.** `list_rows` passes row
+  serialization and JSON encoding through `_render_list_rows_response`, which
+  offloads the CPU-bound work with `asyncio.to_thread`; `orjson` bounds the
+  GIL-held encoding section.
+- **Keep both list aliases.** `data` and `rows` contain the same serialized rows;
+  admin clients use both shapes during compatibility transitions.
+- **The page cap is 2,000 rows.** Keep `ADMIN_LIST_MAX_PAGE_SIZE` aligned with the
+  dashboard constant in `orm-proxy.ts`.
+
+## Database identity
+
+- **A table is `database.schema.table`.** `GET /tables` and cache stats expose
+  `database_name`; every columns, row, mutation, bulk, and cache endpoint accepts
+  `database=` and passes it to the multi-database model registry.
+- **Ambiguity is a controlled conflict.** An omitted database that matches more
+  than one registered model returns HTTP 409 with the candidates. It never guesses
+  and never escapes as a request crash.
+
+Verified against `router.py` and
+`tests/level1/test_admin_db_columns.py` on 2026-08-17.
+
+## Change Log
+
+- 2026-08-17 — Moved bulk row serialization and JSON encoding off the event
+  loop after a 1.1-second production stall.
+- 2026-08-17 — Carried database identity through every admin relation endpoint
+  and converted unqualified cross-database ambiguity into HTTP 409.

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/matrx_orm/admin/router.py

@@ -24,6 +24,7 @@ Effective routes (relative to the mount prefix):
 
 from __future__ import annotations
 
+import asyncio
 import base64
 import binascii
 import json
@@ -32,7 +33,8 @@ import math
 import re
 from typing import Any
 
-from fastapi import APIRouter, HTTPException, Query, Request
+import orjson
+from fastapi import APIRouter, HTTPException, Query, Request, Response
 from fastapi.responses import JSONResponse
 
 from matrx_orm.core.expressions import Q
@@ -56,22 +58,42 @@ _COMPOSITE_ROW_ID_PREFIX = "cmp1_"
 # ---------------------------------------------------------------------------
 
 
-def _model_by_table(table_name: str, schema: str | None = None) -> type | None:
-    return model_registry.get_model_by_table(schema or "public", table_name)
+def _model_by_table(
+    table_name: str,
+    schema: str | None = None,
+    database: str | None = None,
+) -> type | None:
+    return model_registry.get_model_by_table(
+        schema or "public",
+        table_name,
+        database=database,
+    )
 
 
-def _require_model(table_name: str, schema: str | None = None) -> type:
-    model = _model_by_table(table_name, schema)
+def _require_model(
+    table_name: str,
+    schema: str | None = None,
+    database: str | None = None,
+) -> type:
+    try:
+        model = _model_by_table(table_name, schema, database)
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
     if model is None:
         effective_schema = schema or "public"
+        database_suffix = f" in database '{database}'" if database else ""
         log.warning(
-            "Table '%s.%s' not found in model registry",
+            "Table '%s.%s' not found in model registry%s",
             effective_schema,
             table_name,
+            database_suffix,
         )
         raise HTTPException(
             status_code=404,
-            detail=f"Table '{effective_schema}.{table_name}' not found in model registry",
+            detail=(
+                f"Table '{effective_schema}.{table_name}' not found in model registry"
+                f"{database_suffix}"
+            ),
         )
     return model
 
@@ -113,6 +135,46 @@ def _serialize(instance: Any) -> dict[str, Any]:
     return complete
 
 
+def _build_list_rows_response(
+    items: list[Any],
+    *,
+    total_count: int,
+    page: int,
+    page_size: int,
+) -> Response:
+    data = [_serialize(row) for row in items]
+    total_pages = math.ceil(total_count / page_size) if page_size > 0 else 0
+    return Response(
+        content=orjson.dumps(
+            {
+                "data": data,
+                "rows": data,
+                "total": total_count,
+                "page": page,
+                "page_size": page_size,
+                "total_pages": total_pages,
+            }
+        ),
+        media_type="application/json",
+    )
+
+
+async def _render_list_rows_response(
+    items: list[Any],
+    *,
+    total_count: int,
+    page: int,
+    page_size: int,
+) -> Response:
+    return await asyncio.to_thread(
+        _build_list_rows_response,
+        items,
+        total_count=total_count,
+        page=page,
+        page_size=page_size,
+    )
+
+
 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:
@@ -386,16 +448,19 @@ async def _fetch_check_choices(model: type) -> dict[str, list[str]]:
 async def list_tables() -> list[dict[str, object]]:
     models = model_registry.all_models()
     log.info("list_tables: %d models in registry", len(models))
-    sample_model = next(iter(models.values()), None)
-    db_counts = await _fetch_db_column_counts(sample_model) if sample_model else {}
+    counts_by_database: dict[str, dict[tuple[str, str], int]] = {}
     tables = []
     for model in models.values():
         meta = model._meta
         schema = _model_schema(model)
+        database = model.get_database_name()
+        if database not in counts_by_database:
+            counts_by_database[database] = await _fetch_db_column_counts(model)
         orm_count = len(meta.fields)
-        db_count = db_counts.get((schema, meta.table_name))
+        db_count = counts_by_database[database].get((schema, meta.table_name))
         tables.append(
             {
+                "database_name": database,
                 "table_name": meta.table_name,
                 "table_schema": schema,
                 "name": meta.table_name,
@@ -403,7 +468,7 @@ async def list_tables() -> list[dict[str, object]]:
                 "column_count": db_count if db_count is not None else orm_count,
             }
         )
-    tables.sort(key=lambda t: (t["table_schema"], t["table_name"]))
+    tables.sort(key=lambda t: (t["database_name"], t["table_schema"], t["table_name"]))
     return tables
 
 
@@ -411,8 +476,9 @@ async def list_tables() -> list[dict[str, object]]:
 async def get_columns(
     table_name: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> list[dict[str, object]]:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     columns = await _admin_column_descriptors(model)
 
     # Enrich with CHECK constraint choices from the database
@@ -605,8 +671,9 @@ async def list_rows(
     sort_dir: str = Query("asc", pattern="^(asc|desc)$"),
     search: str | None = Query(None, description="Column filters as 'col1:val1,col2:val2'"),
     schema: str | None = Query(None, description="PostgreSQL schema name"),
-) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    database: str | None = Query(None, description="Registered database project name"),
+) -> Response:
+    model = _require_model(table_name, schema, database)
     log.info(
         "list_rows: table=%s page=%d size=%d sort_by=%s sort_dir=%s search=%s",
         table_name,
@@ -629,25 +696,18 @@ async def list_rows(
         paginator = Paginator(qb, per_page=page_size)
         # page() is 1-based; our API uses 0-based pages
         page_obj = await paginator.page(page + 1)
-        data = [_serialize(row) for row in page_obj.items]
-        total_pages = math.ceil(page_obj.total_count / page_size) if page_size > 0 else 0
-
         log.info(
             "list_rows: %s returned %d rows (total %d)",
             table_name,
-            len(data),
+            len(page_obj.items),
             page_obj.total_count,
         )
 
-        return JSONResponse(
-            content={
-                "data": data,
-                "rows": data,
-                "total": page_obj.total_count,
-                "page": page,
-                "page_size": page_size,
-                "total_pages": total_pages,
-            }
+        return await _render_list_rows_response(
+            page_obj.items,
+            total_count=page_obj.total_count,
+            page=page,
+            page_size=page_size,
         )
 
     except ValueError:
@@ -672,8 +732,9 @@ async def get_row(
     table_name: str,
     row_id: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("get_row: table=%s id=%s", table_name, row_id)
 
     try:
@@ -689,8 +750,9 @@ async def create_row(
     table_name: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     log.info("create_row: table=%s fields=%s", table_name, list(body.keys()))
 
@@ -709,8 +771,9 @@ async def update_row(
     row_id: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     log.info("update_row: table=%s id=%s fields=%s", table_name, row_id, list(body.keys()))
 
@@ -729,8 +792,9 @@ async def delete_row(
     table_name: str,
     row_id: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("delete_row: table=%s id=%s", table_name, row_id)
 
     try:
@@ -748,10 +812,11 @@ async def bulk_delete_rows(
     table_name: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Delete many rows in one call. Never fails the whole batch on one bad id —
     returns a partial-result envelope so the caller can report what landed."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     ids = body.get("ids")
     if not isinstance(ids, list) or not ids:
@@ -795,11 +860,12 @@ async def bulk_update_rows(
     table_name: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Apply the same field changes to many rows in one call. Never fails the
     whole batch on one bad id — returns a partial-result envelope (same shape
     as bulk-delete) so the caller can report what landed."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     ids = body.get("ids")
     data = body.get("data")
@@ -866,12 +932,13 @@ async def cache_stats() -> list[dict[str, object]]:
         results.append(
             {
                 "model_name": model.__name__,
+                "database_name": model.get_database_name(),
                 "table_name": model._meta.table_name,
                 "table_schema": _model_schema(model),
                 "cached_count": count,
             }
         )
-    results.sort(key=lambda r: (r["table_schema"], r["table_name"]))
+    results.sort(key=lambda r: (r["database_name"], r["table_schema"], r["table_name"]))
     return results
 
 
@@ -879,9 +946,10 @@ async def cache_stats() -> list[dict[str, object]]:
 async def clear_table_cache(
     table_name: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Flush the entire in-memory cache for a table."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("clear_table_cache: %s", table_name)
 
     try:
@@ -897,9 +965,10 @@ async def evict_row_cache(
     table_name: str,
     row_id: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Evict a single record from the in-memory cache."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("evict_row_cache: %s/%s", table_name, row_id)
 
     try:

matrx_orm-3.1.78/matrx_orm/local_sqlite.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import re
+import sqlite3
+from collections.abc import Sequence
+from pathlib import Path
+
+type SQLiteValue = str | int | float | bytes | None
+
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+def _identifier(value: str) -> str:
+    if not _IDENTIFIER.fullmatch(value):
+        raise ValueError(f"invalid SQLite identifier: {value!r}")
+    return f'"{value}"'
+
+
+def read_local_sqlite_rows(
+    database: str | Path,
+    *,
+    table: str,
+    columns: Sequence[str],
+    order_by: Sequence[str] = (),
+) -> list[tuple[SQLiteValue, ...]]:
+    """Read a projected table from a local SQLite artifact in read-only mode."""
+    if not columns:
+        raise ValueError("columns must contain at least one identifier")
+
+    projection = ", ".join(_identifier(column) for column in columns)
+    statement = f"SELECT {projection} FROM {_identifier(table)}"
+    if order_by:
+        statement += " ORDER BY " + ", ".join(_identifier(column) for column in order_by)
+
+    path = Path(database).expanduser().resolve()
+    connection = sqlite3.connect(f"{path.as_uri()}?mode=ro", uri=True)
+    try:
+        return [tuple(row) for row in connection.execute(statement)]
+    finally:
+        connection.close()

matrx_orm-3.1.78/matrx_orm/operations/FEATURE.md

@@ -0,0 +1,23 @@
+# Conflict-write operations
+
+`conflict_writes.py` provides typed insert-ignore and conflict-update primitives
+for append-only rows, partial unique indexes, and atomic counters.
+
+## Event-loop safety
+
+- **Bulk row coercion never runs on the event loop.** `bulk_insert_ignore` and
+  `bulk_upsert_increment` pass model construction, defaults, and field DB-value
+  conversion through `_prep_bulk_rows`, which uses `asyncio.to_thread`.
+- **Single-row writes stay inline.** `insert_ignore` and
+  `upsert_with_conflict` avoid thread-dispatch overhead for one row.
+- **Statement chunking still enforces the bind-parameter ceiling.** Offloading
+  row preparation does not change `_MAX_BIND_PARAMS` or caller-connection
+  transaction semantics.
+
+Verified against `conflict_writes.py` and
+`tests/level1/test_conflict_writes.py` on 2026-08-17.
+
+## Change Log
+
+- 2026-08-17 — Moved bulk model materialization off the event loop after a
+  scheduled search-performance import froze unrelated requests for 2.8 seconds.

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/matrx_orm/operations/conflict_writes.py

@@ -33,6 +33,7 @@ primitive instead of hand-rolled f-strings.
 
 from __future__ import annotations
 
+import asyncio
 import re
 from typing import TYPE_CHECKING, Any
 
@@ -115,6 +116,12 @@ def _prep_rows(model_cls: type[Model], objects_data: list[dict[str, Any]]) -> li
     return data_list
 
 
+async def _prep_bulk_rows(
+    model_cls: type[Model], objects_data: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    return await asyncio.to_thread(_prep_rows, model_cls, objects_data)
+
+
 async def _run(
     model_cls: type[Model],
     sql: str,
@@ -171,7 +178,7 @@ async def bulk_insert_ignore(
     if isinstance(returning, str) and not _IDENT_RE.match(returning):
         raise ValueError(f"returning column must be a plain identifier; got {returning!r}")
     returning_clause = "*" if returning is True else returning if returning else "1"
-    data_list = _prep_rows(model_cls, objects_data)
+    data_list = await _prep_bulk_rows(model_cls, objects_data)
     target_clause = _render_conflict_target(on_conflict)
     table = model_cls._meta.qualified_table_name
     col_count = len({k for row in data_list for k in row})
@@ -362,7 +369,7 @@ async def bulk_upsert_increment(
             raise ValueError(f"set_fields column must be a plain identifier; got {col!r}")
         if col in increments:
             raise ValueError(f"{col!r} is in both increments and set_fields — pick one")
-    data_list = _prep_rows(model_cls, objects_data)
+    data_list = await _prep_bulk_rows(model_cls, objects_data)
     target_clause = _render_conflict_target(on_conflict)
     table = model_cls._meta.qualified_table_name
 

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.76"
+version = "3.1.78"
 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" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.17",
+    "matrx-utils>=2.0.19",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",
@@ -59,6 +59,7 @@ api = [
 ]
 admin = [
     "fastapi>=0.115",
+    "orjson>=3.10",
 ]
 
 [project.scripts]

{matrx_orm-3.1.76 → matrx_orm-3.1.78}/tests/level1/test_admin_db_columns.py

@@ -4,13 +4,16 @@ from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
+from fastapi import HTTPException
 from matrx_orm.admin.router import (
     COMPOSITE_ROW_ID_FIELD,
     _admin_column_descriptors,
     _db_row_to_descriptor,
     _decode_row_id,
     _model_by_table,
+    _require_model,
     _serialize,
+    list_tables,
 )
 
 
@@ -35,7 +38,7 @@ def test_admin_model_lookup_defaults_to_exact_public_key() -> None:
         return_value=sentinel,
     ) as lookup:
         assert _model_by_table("definition") is sentinel
-    lookup.assert_called_once_with("public", "definition")
+    lookup.assert_called_once_with("public", "definition", database=None)
 
 
 def test_admin_model_lookup_uses_requested_schema() -> None:
@@ -44,7 +47,66 @@ def test_admin_model_lookup_uses_requested_schema() -> None:
         return_value=None,
     ) as lookup:
         assert _model_by_table("definition", "agent") is None
-    lookup.assert_called_once_with("agent", "definition")
+    lookup.assert_called_once_with("agent", "definition", database=None)
+
+
+def test_admin_model_lookup_uses_requested_database() -> None:
+    sentinel = object()
+    with patch(
+        "matrx_orm.admin.router.model_registry.get_model_by_table",
+        return_value=sentinel,
+    ) as lookup:
+        assert _model_by_table("users", "auth", "main") is sentinel
+    lookup.assert_called_once_with("auth", "users", database="main")
+
+
+def test_admin_model_lookup_returns_conflict_for_ambiguous_relation() -> None:
+    with (
+        patch(
+            "matrx_orm.admin.router.model_registry.get_model_by_table",
+            side_effect=ValueError("Table 'auth.users' is ambiguous across databases"),
+        ),
+        pytest.raises(HTTPException) as exc_info,
+    ):
+        _require_model("users", "auth")
+
+    assert exc_info.value.status_code == 409
+    assert "ambiguous" in str(exc_info.value.detail)
+
+
+@pytest.mark.asyncio
+async def test_admin_table_inventory_exposes_database_identity() -> None:
+    model = SimpleNamespace(
+        __name__="Users",
+        _meta=SimpleNamespace(
+            table_name="users",
+            db_schema="auth",
+            fields={"id": object()},
+        ),
+        get_database_name=lambda: "supabase_automation_matrix",
+    )
+    with (
+        patch(
+            "matrx_orm.admin.router.model_registry.all_models",
+            return_value={("supabase_automation_matrix", "auth", "Users"): model},
+        ),
+        patch(
+            "matrx_orm.admin.router._fetch_db_column_counts",
+            new=AsyncMock(return_value={("auth", "users"): 24}),
+        ),
+    ):
+        tables = await list_tables()
+
+    assert tables == [
+        {
+            "database_name": "supabase_automation_matrix",
+            "table_name": "users",
+            "table_schema": "auth",
+            "name": "users",
+            "model_name": "Users",
+            "column_count": 24,
+        }
+    ]
 
 
 def test_composite_row_identity_round_trips() -> None: