matrx-orm 3.1.159__tar.gz → 3.1.161__tar.gz

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/BASE_CLASS_METHODS.md

@@ -559,6 +559,20 @@ Tests: `packages/matrx-orm/tests/level1/test_update_case_expression.py`.
 
 ### Session-scoped advisory lock — `advisory_lock` / `try_advisory_lock` / `advisory_unlock`
 
+> 🚨 **A session lock is only a lock where the connection has backend affinity.**
+> Through a connection pooler in TRANSACTION mode (Supavisor, PgBouncer, RDS Proxy…)
+> consecutive statements on one leased connection can land on DIFFERENT backends: the
+> lock is released the instant its own statement ends, `pg_advisory_unlock` reports it
+> was never held, and two independent callers BOTH acquire the same key while the code
+> reads as correct. Measured, not theorised — one deployment reached this way billed two
+> model calls for one answer and let two concurrent OAuth refreshes replay a one-use
+> refresh token (2026-09-17). Prove `SELECT pg_backend_pid()` is stable across two
+> statements on your connection before using these three functions. If it is not, guard
+> the work with a durable claim ROW (`INSERT … ON CONFLICT DO NOTHING` plus a lease), or
+> with `advisory_xact_lock` inside ONE `transaction()` when the guarded section fits in a
+> single transaction — a pooler pins one backend for an explicit transaction.
+> The tests below assert the SQL text only; no unit test can catch this.
+
 Three top-level primitives (`matrx_orm.core.transaction`, exported from `matrx_orm`) —
 the SESSION-scoped sibling of `advisory_xact_lock`/`try_advisory_xact_lock`. A
 transaction-scoped lock auto-releases at COMMIT/ROLLBACK, which doesn't fit a lock held

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.159
+Version: 3.1.161
 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,7 +25,7 @@ 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.47
+Requires-Dist: matrx-utils>=2.0.48
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/matrx_orm/__init__.py

@@ -264,6 +264,13 @@ from .core.session_context import (
     declaring_actor,
     session_context_gucs,
 )
+from .write_actor import (
+    ACTOR_REQUIRED_TABLES,
+    UndeterminedWriteActor,
+    set_write_feature_resolver,
+    write_needs_named_actor,
+    writing_system,
+)
 from .core.signals import (
     Signal,
     post_create,
@@ -685,6 +692,11 @@ __all__ = [
     "declared_actor_gucs",
     "declaring_actor",
     "session_context_gucs",
+    "ACTOR_REQUIRED_TABLES",
+    "UndeterminedWriteActor",
+    "set_write_feature_resolver",
+    "write_needs_named_actor",
+    "writing_system",
     "advisory_xact_lock",
     "try_advisory_xact_lock",
     "advisory_lock",

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/matrx_orm/adapters/MODULE_README.md

@@ -71,35 +71,6 @@ Filepath: src/matrx_orm/adapters/__init__.py  [python]
 
 
 
----
-Filepath: src/matrx_orm/adapters/postgresql.py  [python]
-
-  class PostgreSQLAdapter(BaseAdapter):
-      def __init__(self)
-      async def _get_connection(self)
-      async def execute_query(self, query: Dict[str, Any]) -> List[Dict[str, Any]]
-      async def count(self, query: Dict[str, Any]) -> int
-      async def exists(self, query: Dict[str, Any]) -> bool
-      async def insert(self, query: Dict[str, Any]) -> Dict[str, Any]
-      async def bulk_insert(self, query: Dict[str, Any]) -> List[Dict[str, Any]]
-      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 close(self)
-      async def transaction(self)
-      async def savepoint(self, name: str)
-      async def rollback_to_savepoint(self, name: str)
-      async def release_savepoint(self, name: str)
-      def _build_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_count_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_exists_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_insert_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_bulk_insert_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_update_sql(self, query: Dict[str, Any], data: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_bulk_update_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-      def _build_delete_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]
-
-
 ---
 Filepath: src/matrx_orm/adapters/base_adapter.py  [python]
 

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/matrx_orm/core/transaction.py

@@ -143,6 +143,24 @@ async def advisory_lock(key: str | int, *, connection: Any) -> None:
     same connection (e.g. a long-running background pass that itself opens
     its own nested transactions).
 
+    🚨 **REQUIRES CONNECTION AFFINITY — READ THIS BEFORE USING IT.** A
+    session-scoped lock lives in the backend session, so it is only a lock if
+    every statement of the guarded section reaches the SAME backend. Through a
+    connection pooler in TRANSACTION mode (Supavisor, PgBouncer, RDS Proxy…)
+    consecutive statements on one leased connection can land on DIFFERENT
+    backends: the lock is then released the instant its own statement ends,
+    ``pg_advisory_unlock`` reports it was never held, and two independent
+    callers BOTH acquire the same key while the code reads as correct. Measured,
+    not theorised — a deployment reached this way billed two model calls for one
+    answer and let two concurrent OAuth refreshes replay a one-use refresh
+    token. Before reaching for this: prove the backend pid is stable across two
+    statements on your connection (``SELECT pg_backend_pid()`` twice). If it is
+    not, this function cannot help you — guard the work with a durable claim ROW
+    (``INSERT … ON CONFLICT DO NOTHING`` plus a lease) instead, or use
+    :func:`advisory_xact_lock` INSIDE one ``transaction()`` when the whole
+    guarded section fits in a single transaction (a pooler pins one backend for
+    an explicit transaction).
+
     Requires an explicit ``connection=`` (an asyncpg connection obtained via
     :func:`acquire_connection`, held for the duration of the locked section) —
     a session-scoped lock has no meaning tied to the ``transaction()``
@@ -175,6 +193,10 @@ async def try_advisory_lock(key: str | int, *, connection: Any) -> bool:
     blocks/queues). Same connection/release contract as :func:`advisory_lock`
     — pair with :func:`advisory_unlock` in a ``try/finally``.
 
+    🚨 The same connection-affinity warning as :func:`advisory_lock` applies in
+    full: through a transaction-mode pooler this returns ``True`` for TWO
+    concurrent callers on the same key.
+
     The single-worker serialization shape: several callers race to start the
     same background pass (e.g. one per org); the first to arrive wins and
     runs it, the rest skip (no waiting) and let the winner's release + their

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/matrx_orm/query/executor.py

@@ -11,6 +11,7 @@ from matrx_utils import vcprint
 from matrx_orm.adapters import AdapterRegistry
 from matrx_orm.adapters.base_adapter import BaseAdapter
 from matrx_orm.core.types import AggregateResult, UpdateResult
+from matrx_orm.write_actor import names_its_actor
 from matrx_orm.exceptions import (
     DatabaseError,
     IntegrityError,
@@ -1192,6 +1193,7 @@ class QueryExecutor:
         )
         return await self.db.execute_write_dict(query)
 
+    @names_its_actor
     async def insert(self, query: dict[str, Any]) -> dict[str, Any]:
         """INSERT a single row, RETURNING *."""
         self._guard_writable("insert")
@@ -1236,6 +1238,7 @@ class QueryExecutor:
             # inside another IntegrityError, producing banner-in-banner output.
             raise
 
+    @names_its_actor
     async def bulk_insert(self, query: dict[str, Any]) -> list[Model]:
         """Bulk INSERT, RETURNING *."""
         self._guard_writable("bulk_insert")
@@ -1310,6 +1313,7 @@ class QueryExecutor:
                 },
             ) from e
 
+    @names_its_actor
     async def upsert(self, query: dict[str, Any]) -> dict[str, Any]:
         """INSERT ... ON CONFLICT (...) DO UPDATE SET ... RETURNING *
 
@@ -1379,6 +1383,7 @@ class QueryExecutor:
             # Already classified upstream — see note on single-insert.
             raise
 
+    @names_its_actor
     async def bulk_upsert(self, query: dict[str, Any]) -> list[Model]:
         """Bulk INSERT ... ON CONFLICT DO UPDATE.
 
@@ -1524,6 +1529,7 @@ class QueryExecutor:
         inner_where = f" WHERE {where_clause}" if where_clause else ""
         return f" WHERE {pk} IN (SELECT {pk} FROM {table}{inner_where} ORDER BY {pk} FOR UPDATE)"
 
+    @names_its_actor
     async def update(self, **kwargs: Any) -> UpdateResult:
         """UPDATE rows matching the WHERE clause built from filters."""
         self._guard_writable("update")
@@ -1655,6 +1661,11 @@ class QueryExecutor:
                 details={"operation": "update", "error": describe_db_exception(e).as_text()},
             ) from e
 
+    # DELETE too, and not out of tidiness: a hard delete on
+    # ``platform.associations`` fires ``_gc_assoc_harddelete``, which writes
+    # OTHER tables inside this statement. That cascade is exactly where the
+    # unnamed-actor refusal surfaced "nowhere near the writer that caused it".
+    @names_its_actor
     async def delete(self) -> int:
         """DELETE rows matching the WHERE clause."""
         self._guard_writable("delete")

matrx_orm-3.1.161/matrx_orm/write_actor.py

@@ -0,0 +1,234 @@
+"""ONE DOOR: a write to a table that refuses an unnamed actor names one here.
+
+🚨 THE CLASS THIS CLOSES (2026-09-17). ``platform.associations`` refuses a write
+that declares ``actor_tier=code`` and names no system — "an AI did it" with no
+name is not provenance — and it reads that name from ``SET LOCAL`` GUCs, which
+exist only inside a transaction that declared them.
+
+``68db29e50b`` put the fix on the ASSOCIATION ENGINE (``assoc.associate(...)``),
+which covered the eleven service writers that go through it and covered nothing
+else. Four production writers call the model straight —
+``aidream/services/agent_data/operations.py``, ``kind_records/store.py``,
+``kind_records/children.py``, ``google_sync/records.py`` — and the engine's own
+``associate`` reaches the table through ``get_or_create``, a fifth method the
+census grep for ``Associations.create`` never saw. A safe path beside an unsafe
+one is not a fix: the door has to be removed, not signposted.
+
+So the seam sits UNDER every one of them, at the ORM's DML floor
+(``QueryExecutor.insert`` / ``bulk_insert`` / ``upsert`` / ``bulk_upsert`` /
+``update``). Nothing writes a row without passing through those five methods —
+``create``, ``bulk_create``, ``get_or_create``, ``update_or_create``, ``save``,
+``upsert``, the managers in ``matrx_orm.extended`` and any future entry point
+all funnel here — so there is exactly one place a write to an actor-required
+table can happen, and it declares the actor.
+
+WHAT IT DECLARES, AND WHY NEVER A CONSTANT
+------------------------------------------
+A caller that already declared an actor passes straight through, byte for byte
+unchanged: the seam only speaks when nobody did. What it then says is the name
+of the code ACTUALLY making the write — the running feature when the host's
+context names one, else the calling module. There is no fallback string. The
+first version of this walk stopped at the generic ``aidream_association_write``
+whenever it found no ``aidream.`` frame, which satisfies the database's
+constraint while defeating the entire point of it: the operator reading
+``updated_by_system`` learns nothing, and a script, a package or a worker —
+exactly the automated paths this exists for — all resolve to the same
+meaningless word. When the writer cannot be named this raises
+:class:`UndeterminedWriteActor` AT THE CALL SITE, naming the frame it could not
+resolve, which is the loud failure the doctrine requires of a stand-in.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+from types import FrameType
+from typing import Any
+
+__all__ = [
+    "ACTOR_REQUIRED_TABLES",
+    "UndeterminedWriteActor",
+    "actor_named_for_write",
+    "names_its_actor",
+    "set_write_feature_resolver",
+    "write_needs_named_actor",
+    "writing_system",
+]
+
+#: ``(schema, table)`` pairs whose database-side rule refuses a write that
+#: declares ``actor_tier=code`` and names no system. Membership is what makes
+#: the seam speak; every other table's writes are untouched (no extra
+#: transaction, no extra round trip).
+ACTOR_REQUIRED_TABLES: frozenset[tuple[str, str]] = frozenset(
+    {
+        ("platform", "associations"),
+    }
+)
+
+#: How long a system name may be. ``app.actor_system`` is text, but a name
+#: longer than this is a stack artefact, not a name a person can act on.
+_MAX_SYSTEM = 64
+
+
+class UndeterminedWriteActor(RuntimeError):
+    """The code making this write could not be named, so nothing was written.
+
+    Deliberately fatal. The alternative — a constant like
+    ``aidream_association_write`` — passes the database's check and tells the
+    operator reading the row nothing at all.
+    """
+
+
+_feature_resolver: Callable[[], str | None] | None = None
+
+
+def set_write_feature_resolver(resolver: Callable[[], str | None] | None) -> None:
+    """Teach the seam how to ask the HOST which feature is running.
+
+    matrx-orm cannot import the host, and the running feature is the truthful,
+    operator-actionable answer when there is one. ``aidream`` wires
+    ``try_get_app_context().source_feature`` here at startup. Unwired (a script,
+    a test, another package) the seam falls back to the calling module, which is
+    still a real name — never a constant.
+    """
+    global _feature_resolver
+    _feature_resolver = resolver
+
+
+def write_needs_named_actor(model: Any) -> bool:
+    """Does a write to ``model``'s table have to name its actor?"""
+    if model is None:
+        return False
+    schema = getattr(model, "_db_schema", None)
+    table = getattr(model, "_table_name", None)
+    if not schema or not table:
+        return False
+    return (str(schema), str(table)) in ACTOR_REQUIRED_TABLES
+
+
+# Frames that are the plumbing, never the author. The ORM's own modules and the
+# generic async/context machinery it is wrapped in say nothing about WHO wrote
+# the row, so the walk steps over them to reach the first frame that does.
+_PLUMBING_PREFIXES: tuple[str, ...] = (
+    "matrx_orm.",
+    "contextlib",
+    "asyncio.",
+    "functools",
+)
+_PLUMBING_MODULES: frozenset[str] = frozenset({"matrx_orm", "asyncio", "contextlib", "functools"})
+
+
+def _is_plumbing(module: str) -> bool:
+    return module in _PLUMBING_MODULES or module.startswith(_PLUMBING_PREFIXES)
+
+
+def _name_of(frame: FrameType) -> str | None:
+    """A name a person can act on for the code running in ``frame``.
+
+    The last TWO dotted segments of the module, because the leaf alone is a
+    coin flip: ``records`` is ``google_sync/records.py`` and four other files,
+    and an operator reading ``updated_by_system='records'`` is no better off
+    than with a constant. ``google_sync.records`` names the writer.
+    """
+    module = str(frame.f_globals.get("__name__") or "")
+    if module and module != "__main__":
+        return ".".join(module.split(".")[-2:])[:_MAX_SYSTEM]
+    filename = str(frame.f_globals.get("__file__") or "")
+    stem = Path(filename).stem if filename else ""
+    return stem[:_MAX_SYSTEM] or None
+
+
+def writing_system() -> str:
+    """WHICH system is writing this row — read off the running program, never invented.
+
+    Raises :class:`UndeterminedWriteActor` rather than returning a placeholder.
+    """
+    if _feature_resolver is not None:
+        try:
+            feature = _feature_resolver()
+        except Exception:  # noqa: BLE001 — a broken host hook must not name the row
+            feature = None
+        if feature and str(feature).strip():
+            return str(feature).strip()[:_MAX_SYSTEM]
+
+    import sys
+
+    frame: FrameType | None = sys._getframe(1)
+    # The frame a person would look at if this refuses: the innermost one that
+    # is not the ORM itself. Reporting the OUTERMOST frame instead names
+    # `.venv/bin/pytest` or the process entry point, which is useless.
+    nearest: FrameType | None = frame
+    while frame is not None:
+        module = str(frame.f_globals.get("__name__") or "")
+        if nearest is None or str(nearest.f_globals.get("__name__") or "").startswith("matrx_orm"):
+            if not module.startswith("matrx_orm"):
+                nearest = frame
+        if not _is_plumbing(module):
+            name = _name_of(frame)
+            if name:
+                return name
+        frame = frame.f_back
+
+    where = (
+        f"{nearest.f_code.co_filename}:{nearest.f_lineno}"
+        if nearest is not None
+        else "an unreadable stack"
+    )
+    raise UndeterminedWriteActor(
+        "A write to an actor-required table could not name the code making it. "
+        f"The outermost frame the seam could read was {where}, and every frame above "
+        "it belongs to the ORM or to async plumbing. Declare the actor at the call "
+        "site — `async with actor_session('code', '<your system>'):` — rather than "
+        "letting an unnamed write reach the database, which would be refused there "
+        "anyway, at CASCADE time, nowhere near here."
+    )
+
+
+@asynccontextmanager
+async def actor_named_for_write(database: str) -> AsyncIterator[None]:
+    """Run the block with an actor declared, if nobody declared one already.
+
+    Pass-through when ``current_actor()`` is set: a caller that named itself is
+    never second-guessed, and no transaction is opened on its behalf.
+    """
+    from matrx_orm.core.session_context import current_actor, declaring_actor
+    from matrx_orm.core.transaction import set_local_guc, transaction
+
+    if current_actor() is not None:
+        yield
+        return
+
+    system = writing_system()
+    # The GUCs are transaction-local, so the declaration is only worth anything
+    # inside one. Nested, this opens a SAVEPOINT and the SET LOCAL applies to
+    # the enclosing transaction — which is correct: the enclosing work had no
+    # actor either.
+    async with transaction(database=database):
+        with declaring_actor("code", system) as actor:
+            for guc_name, guc_value in actor.as_gucs().items():
+                await set_local_guc(guc_name, guc_value)
+            yield
+
+
+def names_its_actor(method: Callable[..., Any]) -> Callable[..., Any]:
+    """Mark a ``QueryExecutor`` DML method as passing through the seam.
+
+    Every DML method on the executor carries this, and
+    ``matrx_orm/tests/test_every_write_door_names_its_actor.py`` walks the
+    executor's AST to prove a newly added one does too — a new write door is
+    the only way this class could re-open.
+    """
+
+    @functools.wraps(method)
+    async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        model = getattr(self, "model", None)
+        if not write_needs_named_actor(model):
+            return await method(self, *args, **kwargs)
+        database = getattr(self, "database", None) or getattr(model, "_database", None)
+        async with actor_named_for_write(str(database)):
+            return await method(self, *args, **kwargs)
+
+    wrapper.__matrx_names_its_actor__ = True  # type: ignore[attr-defined]
+    return wrapper

{matrx_orm-3.1.159 → matrx_orm-3.1.161}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.159"
+version = "3.1.161"
 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.47",
+    "matrx-utils>=2.0.48",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.159/matrx_orm/adapters/postgresql.py

@@ -1,167 +0,0 @@
-from typing import Any, Dict, List, Tuple
-import asyncpg
-from matrx_orm.adapters.base_adapter import BaseAdapter
-from matrx_orm import get_database_config
-from matrx_orm.core.tls import resolve_asyncpg_ssl
-from matrx_utils.conf import settings
-
-
-class PostgreSQLAdapter(BaseAdapter):
-    def __init__(self):
-        self.current_database = settings.DEFAULT_DB_PROJECT
-        self.config = get_database_config(self.current_database)
-        self.connection = None
-
-    async def _get_connection(self):
-        if self.connection is None or self.connection.is_closed():
-            ssl_config = await resolve_asyncpg_ssl(self.config.get("ssl", "require"))
-            self.connection = await asyncpg.connect(
-                host=self.config["host"],
-                port=self.config["port"],
-                database=self.config["database_name"],
-                user=self.config["user"],
-                password=self.config["password"],
-                ssl=ssl_config,
-            )
-        return self.connection
-
-    async def execute_query(self, query: Dict[str, Any]) -> List[Dict[str, Any]]:
-        sql, params = self._build_sql(query)
-        connection = await self._get_connection()
-        rows = await connection.fetch(sql, *params)
-        return [dict(row) for row in rows]
-
-    async def count(self, query: Dict[str, Any]) -> int:
-        sql, params = self._build_count_sql(query)
-        connection = await self._get_connection()
-        row = await connection.fetchrow(sql, *params)
-        return row["count"]
-
-    async def exists(self, query: Dict[str, Any]) -> bool:
-        sql, params = self._build_exists_sql(query)
-        connection = await self._get_connection()
-        row = await connection.fetchrow(sql, *params)
-        return row["exists"]
-
-    async def insert(self, query: Dict[str, Any]) -> Dict[str, Any]:
-        sql, params = self._build_insert_sql(query)
-        connection = await self._get_connection()
-        row = await connection.fetchrow(sql, *params)
-        return dict(row)
-
-    async def bulk_insert(self, query: Dict[str, Any]) -> List[Dict[str, Any]]:
-        sql, params = self._build_bulk_insert_sql(query)
-        connection = await self._get_connection()
-        await connection.executemany(sql, params)
-        return await connection.fetch(sql, *params)
-
-    async def update(self, query: Dict[str, Any], data: Dict[str, Any]) -> int:
-        sql, params = self._build_update_sql(query, data)
-        connection = await self._get_connection()
-        result = await connection.execute(sql, *params)
-        return result
-
-    async def bulk_update(self, query: Dict[str, Any]) -> int:
-        sql, params = self._build_bulk_update_sql(query)
-        connection = await self._get_connection()
-        result = await connection.executemany(sql, params)
-        return result
-
-    async def delete(self, query: Dict[str, Any]) -> int:
-        sql, params = self._build_delete_sql(query)
-        connection = await self._get_connection()
-        result = await connection.execute(sql, *params)
-        return result
-
-    async def close(self):
-        if self.connection is not None and not self.connection.is_closed():
-            await self.connection.close()
-
-    async def transaction(self):
-        connection = await self._get_connection()
-        async with connection.transaction():
-            yield
-
-    async def savepoint(self, name: str):
-        connection = await self._get_connection()
-        await connection.execute(f"SAVEPOINT {name}")
-
-    async def rollback_to_savepoint(self, name: str):
-        connection = await self._get_connection()
-        await connection.execute(f"ROLLBACK TO SAVEPOINT {name}")
-
-    async def release_savepoint(self, name: str):
-        connection = await self._get_connection()
-        await connection.execute(f"RELEASE SAVEPOINT {name}")
-
-    def _build_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        # Generic SQL building logic for select statements
-        sql = f"SELECT * FROM {query['model'].__tablename__} WHERE "
-        filters = []
-        params = []
-        for field, value in query["filters"].items():
-            filters.append(f"{field} = ${len(params) + 1}")
-            params.append(value)
-        sql += " AND ".join(filters)
-        return sql, params
-
-    def _build_count_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        sql = f"SELECT COUNT(*) FROM {query['model'].__tablename__} WHERE "
-        filters = []
-        params = []
-        for field, value in query["filters"].items():
-            filters.append(f"{field} = ${len(params) + 1}")
-            params.append(value)
-        sql += " AND ".join(filters)
-        return sql, params
-
-    def _build_exists_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        sql = f"SELECT EXISTS(SELECT 1 FROM {query['model'].__tablename__} WHERE "
-        filters = []
-        params = []
-        for field, value in query["filters"].items():
-            filters.append(f"{field} = ${len(params) + 1}")
-            params.append(value)
-        sql += " AND ".join(filters) + ")"
-        return sql, params
-
-    def _build_insert_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        fields = ", ".join(query["data"].keys())
-        placeholders = ", ".join([f"${i + 1}" for i in range(len(query["data"]))])
-        sql = f"INSERT INTO {query['model'].__tablename__} ({fields}) VALUES ({placeholders}) RETURNING *"
-        params = list(query["data"].values())
-        return sql, params
-
-    def _build_bulk_insert_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        fields = ", ".join(query["data"][0].keys())
-        placeholders = ", ".join([f"${i + 1}" for i in range(len(query["data"][0]))])
-        sql = f"INSERT INTO {query['model'].__tablename__} ({fields}) VALUES ({placeholders})"
-        params = [tuple(row.values()) for row in query["data"]]
-        return sql, params
-
-    def _build_update_sql(
-        self, query: Dict[str, Any], data: Dict[str, Any]
-    ) -> Tuple[str, List[Any]]:
-        set_clause = ", ".join([f"{key} = ${i + 1}" for i, key in enumerate(data.keys())])
-        sql = f"UPDATE {query['model'].__tablename__} SET {set_clause} WHERE "
-        filters = []
-        params = list(data.values())
-        for field, value in query["filters"].items():
-            filters.append(f"{field} = ${len(params) + 1}")
-            params.append(value)
-        sql += " AND ".join(filters)
-        return sql, params
-
-    def _build_bulk_update_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        # Similar to update but for bulk updates
-        raise NotImplementedError("Bulk update logic to be implemented")
-
-    def _build_delete_sql(self, query: Dict[str, Any]) -> Tuple[str, List[Any]]:
-        sql = f"DELETE FROM {query['model'].__tablename__} WHERE "
-        filters = []
-        params = []
-        for field, value in query["filters"].items():
-            filters.append(f"{field} = ${len(params) + 1}")
-            params.append(value)
-        sql += " AND ".join(filters)
-        return sql, params