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

{matrx_orm-3.1.6 → matrx_orm-3.1.8}/BASE_CLASS_METHODS.md

@@ -1,5 +1,21 @@
 # ORM Manager Base Class Methods
 
+> **`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`
+> 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:
+>
+> ```python
+> base = Model.filter(doc_id=x)
+> raw_count   = await base.exclude(raw_text="").count()
+> clean_count = await base.exclude(cleaned_text="").count()  # independent of raw_count
+> ```
+>
+> The one thing to remember: always use the RETURN VALUE of a chain call. A
+> bare `qb.filter(x=1)` statement (return discarded) is a no-op on `qb`
+> itself — reassign (`qb = qb.filter(x=1)`) or chain directly.
+
 > **Model-direct aliases (single-table work).** For small, isolated, single-table
 > work you do NOT need the manager — the generated `Model` class itself exposes
 > the same vocabulary as classmethods: `load_by_id(id)`, `load_by_id_or_none(id)`,

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

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

@@ -27,7 +27,7 @@ from .core.config import (
     resolve_database_name,
     resolve_pool_mode,
 )
-from .core.db_function import ArrayArg, call_function
+from .core.db_function import ArrayArg, call_function, call_function_sync
 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
@@ -318,6 +318,7 @@ __all__ = [
     "install_asyncpg_idle_close_filter",
     # ── DB-side function calls (RPC) ──────────────────────────────────────────
     "call_function",
+    "call_function_sync",
     "MatrxEntity",
     "EntityCapabilityError",
     "ArrayArg",

{matrx_orm-3.1.6 → matrx_orm-3.1.8}/matrx_orm/core/base.py

@@ -1263,6 +1263,71 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
 
         return run_sync(cls.filter(**kwargs).all())
 
+    @classmethod
+    def create_sync(cls, **kwargs: Any) -> Self:
+        """Synchronous twin of create(). Sync contexts only."""
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "Model.create_sync() called in an async context. Use await Model.create(...) instead."
+            )
+        except RuntimeError as e:
+            if "no running event loop" not in str(e):
+                raise
+
+        return run_sync(cls.create(**kwargs))
+
+    @classmethod
+    def upsert_sync(
+        cls,
+        data: dict[str, Any],
+        conflict_fields: list[str] | None = None,
+        update_fields: list[str] | None = None,
+        *,
+        on_conflict: list[str] | ConflictTarget | None = None,  # noqa: F821
+    ) -> Self:
+        """Synchronous twin of upsert(). Sync contexts only."""
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "Model.upsert_sync() called in an async context. Use await Model.upsert(...) instead."
+            )
+        except RuntimeError as e:
+            if "no running event loop" not in str(e):
+                raise
+
+        return run_sync(
+            cls.upsert(data, conflict_fields, update_fields, on_conflict=on_conflict)
+        )
+
+    @classmethod
+    def update_where_sync(cls, filters: dict[str, Any], **updates: Any) -> UpdateResult:
+        """Synchronous twin of update_where(). Sync contexts only."""
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "Model.update_where_sync() called in an async context. Use await Model.update_where(...) instead."
+            )
+        except RuntimeError as e:
+            if "no running event loop" not in str(e):
+                raise
+
+        return run_sync(cls.update_where(filters, **updates))
+
+    @classmethod
+    def delete_where_sync(cls, **filters: Any) -> int:
+        """Synchronous twin of delete_where(). Sync contexts only."""
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "Model.delete_where_sync() called in an async context. Use await Model.delete_where(...) instead."
+            )
+        except RuntimeError as e:
+            if "no running event loop" not in str(e):
+                raise
+
+        return run_sync(cls.delete_where(**filters))
+
     @classmethod
     async def all(cls) -> list[Self]:
         try:

{matrx_orm-3.1.6 → matrx_orm-3.1.8}/matrx_orm/core/db_function.py

@@ -70,7 +70,7 @@ from typing import Any, Literal
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.core.transaction import get_active_connection
 
-__all__ = ["call_function", "ArrayArg"]
+__all__ = ["call_function", "call_function_sync", "ArrayArg"]
 
 # Postgres unquoted-identifier shape. Deliberately strict — this is the only
 # thing standing between a caller-supplied name and the query string, so a
@@ -195,3 +195,27 @@ async def call_function(
             rows = await conn.fetch(sql, *bound_args)
             return [dict(r) for r in rows]
         return await conn.fetchval(sql, *bound_args)
+
+
+def call_function_sync(
+    database: str,
+    schema: str,
+    function: str,
+    *args: Any,
+    mode: Literal["scalar", "none", "rows"] = "scalar",
+    field: str | None = None,
+) -> Any:
+    """Synchronous twin of :func:`call_function`. Sync contexts only."""
+    import asyncio
+
+    from matrx_orm.core.async_db_manager import run_sync
+
+    try:
+        asyncio.get_running_loop()
+        raise RuntimeError(
+            "call_function_sync() called in an async context. Use await call_function(...) instead."
+        )
+    except RuntimeError as e:
+        if "no running event loop" not in str(e):
+            raise
+    return run_sync(call_function(database, schema, function, *args, mode=mode, field=field))

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

@@ -127,46 +127,68 @@ class QueryBuilder(Generic[ModelT]):
     """Lazy, chainable query spec — built up via `.filter()`/`.exclude()`/etc,
     executed on `.all()`/`.count()`/`.exists()`/`.values()`/....
 
-    ⚠️ **MUTATES IN PLACE, DOES NOT CLONE.** Every chain method
-    (`.filter()`, `.exclude()`, `.join()`, `.annotate()`, `.filter_raw()`,
-    `.order_by()`, `.limit()`, ...) appends to `self`'s internal lists/dicts
-    and returns `self` — it is Django-`QuerySet`-SHAPED but NOT
-    Django-`QuerySet`-SAFE: Django clones on every chain call so branching
-    off a saved queryset is side-effect-free; this builder does not, so
-    branching off a saved builder ACCUMULATES.
-
-    Concretely, this is a bug, not a style nit::
-
-        pages_qs = Model.filter(doc_id=x)
-        a = await pages_qs.exclude(raw_text="").count()
-        b = await pages_qs.exclude(cleaned_text="").count()  # BUG: still has
-            # the raw_text exclude from the line above — `b` silently counts
-            # "NOT raw_text AND NOT cleaned_text", not just "NOT cleaned_text".
-
-    (This exact shape shipped in `aidream/services/rag/library_status.py`;
-    see the fix + comment there for the corrected pattern.)
-
-    **The safe patterns:**
-      - Reassign every time: `qb = qb.filter_raw(...)` (fine — no branching
-        off a shared base after the reassignment).
-      - Build a FRESH queryset for each independent read:
-        `await Model.filter(x=1).exclude(a="").count()` and
-        `await Model.filter(x=1).exclude(b="").count()` as two separate
-        expressions, never sharing a `pages_qs`-style variable across calls
-        that each need a different filter set.
-      - If you truly need to branch off one shared base, don't reuse the
-        builder object itself — reissue `Model.filter(...)` (or whatever
-        built the base) for each branch.
-
-    This is intentional current behavior, not an oversight to "just fix" —
-    switching to clone-on-chain is a real, wide-blast-radius ORM change
-    (every `matrx-*` package + `aidream/services/*` calls this) that needs
-    its own audited migration, not a silent semantic flip. Tracked as a
-    platform follow-up; see `tests/level1/test_querybuilder_mutation_semantics.py`
-    for the pinned-current-behavior regression test that must be updated
-    (not just deleted) the day this changes.
+    **Clone-on-chain (copy-on-write) — Django-`QuerySet`-SAFE.** Every chain
+    method (`.filter()`, `.exclude()`, `.join()`, `.annotate()`,
+    `.filter_raw()`, `.order_by()`, `.limit()`, ...) returns a NEW
+    `QueryBuilder` that shares nothing mutable with `self` — the original
+    builder is never modified. This matches Django's `QuerySet`: branching
+    off a saved queryset is side-effect-free, and reusing a variable across
+    independent calls no longer accumulates state.
+
+    ::
+
+        base = Model.filter(doc_id=x)
+        raw_count   = await base.exclude(raw_text="").count()
+        clean_count = await base.exclude(cleaned_text="").count()
+        # Independent — `clean_count` does NOT carry the raw_text exclude.
+        # `base` itself is untouched by either branch.
+
+    (Before this, the two branches above bled into each other — the exact
+    shape that shipped a real count-corruption bug in
+    `aidream/services/rag/library_status.py`, worked around there by
+    building fresh querysets. That workaround is no longer required, though
+    still harmless.)
+
+    **Still true:** always use the RETURN VALUE of a chain call — a bare
+    `qb.filter(x=1)` statement (return discarded, not reassigned) is now a
+    no-op on `qb` itself (the filter lives only on the discarded clone).
+    Reassign (`qb = qb.filter(x=1)`) or chain directly
+    (`Model.filter(x=1).exclude(y=2)`).
+
+    Terminal methods (`.all()`, `.first()`, `.get()`, `.count()`,
+    `.exists()`, `.values()`, `.update()`, `.delete()`, `.aggregate()`, ...)
+    execute the query and do NOT clone.
     """
 
+    def _clone(self) -> QueryBuilder[ModelT]:
+        """Return a new QueryBuilder sharing `self`'s scalar state but with
+        every mutable container (lists/dicts/sets this builder appends to)
+        copied — so mutating the clone's containers never touches `self`'s,
+        and vice versa. Elements inside those containers (filter dicts, Q
+        objects, join specs, ...) are treated as immutable value objects and
+        are NOT deep-copied — only the containers themselves are copied.
+        """
+        new = self.__class__.__new__(self.__class__)
+        new.__dict__.update(self.__dict__)
+        new.filters = list(self.filters)
+        new.excludes = list(self.excludes)
+        new.order_by_fields = list(self.order_by_fields)
+        new.select_fields = list(self.select_fields)
+        new.deferred_fields = set(self.deferred_fields)
+        new.only_fields = set(self.only_fields)
+        new.prefetch_fields = list(self.prefetch_fields)
+        new.joins = list(self.joins)
+        new.group_by_fields = list(self.group_by_fields)
+        new.having_filters = list(self.having_filters)
+        new.aggregations = list(self.aggregations)
+        new.distinct_fields = list(self.distinct_fields) if self.distinct_fields is not None else None
+        new.for_update_opts = dict(self.for_update_opts) if self.for_update_opts is not None else None
+        new.select_related_fields = list(self.select_related_fields)
+        new.ctes = list(self.ctes)
+        new.vector_order = dict(self.vector_order) if self.vector_order is not None else None
+        new.raw_filters = list(self.raw_filters)
+        return new
+
     model: type[ModelT]
     database: str
     filters: list[Any]  # dict[str,Any] or Q objects
@@ -235,18 +257,17 @@ class QueryBuilder(Generic[ModelT]):
             .filter(Q(status="active") | Q(role="admin"))
             .filter(Q(a=1), b=2)          # AND composition
 
-        ⚠️ Mutates `self` and returns it — does NOT clone (see the class
-        docstring). Reusing a saved builder across independent branches
-        accumulates filters onto every branch.
+        Clone-on-chain: returns a NEW builder; `self` is unchanged.
         """
         from ..core.expressions import Exists, Q, TsMatch
 
+        new = self._clone()
         for arg in args:
             # Positional predicate expressions the executor renders from the
             # filters list: Q, Exists(...) (correlated subquery), and
             # TsMatch(...) (full-text WHERE match).
             if isinstance(arg, (Q, Exists, TsMatch)):
-                self.filters.append(arg)
+                new.filters.append(arg)
             else:
                 raise TypeError(
                     "Positional filter argument must be a Q, Exists, or TsMatch object, "
@@ -254,8 +275,8 @@ class QueryBuilder(Generic[ModelT]):
                 )
         if kwargs:
             self._validate_filter_keys(kwargs)
-            self.filters.append(kwargs)
-        return self
+            new.filters.append(kwargs)
+        return new
 
     def _validate_filter_keys(self, kwargs: dict[str, Any]) -> None:
         """Reject filter kwargs whose field/operator don't exist on the model.
@@ -330,15 +351,15 @@ class QueryBuilder(Generic[ModelT]):
     def exclude(self, **kwargs: Any) -> QueryBuilder[ModelT]:
         """Apply SQL exclusion filters.
 
-        ⚠️ Mutates `self` and returns it — does NOT clone (see the class
-        docstring). Calling `.exclude()` twice off the SAME saved builder
-        variable ANDs both excludes together onto one query — it does not
-        give you two independent counts. Build a fresh queryset per
-        independent read instead.
+        Clone-on-chain: returns a NEW builder; `self` is unchanged. Calling
+        `.exclude()` twice off the SAME saved builder variable now gives two
+        INDEPENDENT branches (each excludes only its own kwargs) — it does
+        not AND both excludes together the way in-place mutation used to.
         """
+        new = self._clone()
         if kwargs:
-            self.excludes.append(kwargs)
-        return self
+            new.excludes.append(kwargs)
+        return new
 
     def filter_raw(self, sql: str, *params: Any) -> QueryBuilder[ModelT]:
         """Add a parametrized raw SQL fragment to the WHERE clause (AND-ed).
@@ -392,33 +413,40 @@ class QueryBuilder(Generic[ModelT]):
                 f"but found placeholders {sorted(found) or 'none'} for {len(params)} param(s).\n"
                 f"  SQL: {sql!r}"
             )
-        self.raw_filters.append((sql, list(params)))
-        return self
+        new = self._clone()
+        new.raw_filters.append((sql, list(params)))
+        return new
 
     def order_by(self, *fields: str | Any) -> QueryBuilder[ModelT]:
-        self.order_by_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.order_by_fields.extend(fields)
+        return new
 
     def limit(self, value: int) -> QueryBuilder[ModelT]:
-        self.limit_val = value
-        return self
+        new = self._clone()
+        new.limit_val = value
+        return new
 
     def offset(self, value: int) -> QueryBuilder[ModelT]:
-        self.offset_val = value
-        return self
+        new = self._clone()
+        new.offset_val = value
+        return new
 
     def select(self, *fields: str) -> QueryBuilder[ModelT]:
-        self.select_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.select_fields.extend(fields)
+        return new
 
     def prefetch_related(self, *fields: str) -> QueryBuilder[ModelT]:
-        self.prefetch_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.prefetch_fields.extend(fields)
+        return new
 
     def select_related(self, *fields: str) -> QueryBuilder[ModelT]:
         """Eager-load FK targets via JOIN in the same query (no N+1)."""
-        self.select_related_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.select_related_fields.extend(fields)
+        return new
 
     def join(
         self,
@@ -482,7 +510,8 @@ class QueryBuilder(Generic[ModelT]):
             on_sql, on_params = partner.render()
             qb.join(KgEntities, on=f"e2.id = {on_sql}", on_params=on_params, alias="e2")
         """
-        self.joins.append(
+        new = self._clone()
+        new.joins.append(
             {
                 "model": model_cls,
                 "on": on,
@@ -491,15 +520,17 @@ class QueryBuilder(Generic[ModelT]):
                 "on_params": list(on_params) if on_params else [],
             }
         )
-        return self
+        return new
 
     def group_by(self, *fields: str) -> QueryBuilder[ModelT]:
-        self.group_by_fields.extend(fields)
-        return self
+        new = self._clone()
+        new.group_by_fields.extend(fields)
+        return new
 
     def having(self, **kwargs: Any) -> QueryBuilder[ModelT]:
-        self.having_filters.append(kwargs)
-        return self
+        new = self._clone()
+        new.having_filters.append(kwargs)
+        return new
 
     def annotate(self, **kwargs: Any) -> QueryBuilder[ModelT]:
         """Add computed columns (aggregates or functions) to the SELECT.
@@ -508,9 +539,10 @@ class QueryBuilder(Generic[ModelT]):
 
             .annotate(total=Sum("amount"), name_lower=Lower("username"))
         """
+        new = self._clone()
         for key, value in kwargs.items():
-            self.aggregations.append({"name": key, "function": value})
-        return self
+            new.aggregations.append({"name": key, "function": value})
+        return new
 
     def distinct(self, *fields: str) -> QueryBuilder[ModelT]:
         """Add DISTINCT or DISTINCT ON to the query.
@@ -518,8 +550,9 @@ class QueryBuilder(Generic[ModelT]):
         No args  → ``SELECT DISTINCT ...``
         With args → ``SELECT DISTINCT ON (f1, f2) ...`` (PostgreSQL-specific)
         """
-        self.distinct_fields = list(fields)
-        return self
+        new = self._clone()
+        new.distinct_fields = list(fields)
+        return new
 
     def select_for_update(
         self,
@@ -531,8 +564,9 @@ class QueryBuilder(Generic[ModelT]):
 
         Must be used inside a transaction.
         """
-        self.for_update_opts = {"nowait": nowait, "skip_locked": skip_locked, "of": of or []}
-        return self
+        new = self._clone()
+        new.for_update_opts = {"nowait": nowait, "skip_locked": skip_locked, "of": of or []}
+        return new
 
     def using(self, database: str) -> QueryBuilder[ModelT]:
         """Override the database for this query.
@@ -541,8 +575,9 @@ class QueryBuilder(Generic[ModelT]):
 
             await User.filter(is_active=True).using("replica").all()
         """
-        self.database = database
-        return self
+        new = self._clone()
+        new.database = database
+        return new
 
     def timeout(self, seconds: float) -> QueryBuilder[ModelT]:
         """Override the STATEMENT timeout for this query only (seconds).
@@ -566,8 +601,9 @@ class QueryBuilder(Generic[ModelT]):
         """
         if seconds is not None and seconds <= 0:
             raise ValueError(f"timeout() requires a positive number of seconds, got {seconds!r}")
-        self.timeout_val = seconds
-        return self
+        new = self._clone()
+        new.timeout_val = seconds
+        return new
 
     def from_alias(self, alias: str) -> QueryBuilder[ModelT]:
         """Alias the base (FROM) table — renders ``FROM <table> AS <alias>``.
@@ -589,8 +625,9 @@ class QueryBuilder(Generic[ModelT]):
                 f"from_alias must be a plain ASCII identifier, got {alias!r} — it is "
                 "trusted, code-supplied text (a short alias like 'c'), never user input"
             )
-        self.from_alias_name = alias
-        return self
+        new = self._clone()
+        new.from_alias_name = alias
+        return new
 
     def only(self, *fields: str) -> QueryBuilder[ModelT]:
         """Load only these columns. Unlisted columns on the model instance will be None.
@@ -599,9 +636,10 @@ class QueryBuilder(Generic[ModelT]):
 
             await User.filter(is_active=True).only("id", "email").all()
         """
-        self.only_fields = set(fields)
-        self.select_fields = list(fields)
-        return self
+        new = self._clone()
+        new.only_fields = set(fields)
+        new.select_fields = list(fields)
+        return new
 
     def defer(self, *fields: str) -> QueryBuilder[ModelT]:
         """Exclude these columns from the SELECT. They will be None on the returned instances.
@@ -610,8 +648,9 @@ class QueryBuilder(Generic[ModelT]):
 
             await User.filter(is_active=True).defer("large_blob", "heavy_json").all()
         """
-        self.deferred_fields = set(fields)
-        return self
+        new = self._clone()
+        new.deferred_fields = set(fields)
+        return new
 
     def with_cte(self, *ctes: Any) -> QueryBuilder[ModelT]:
         """Prepend one or more CTEs (WITH clauses) to the query.
@@ -627,8 +666,9 @@ class QueryBuilder(Generic[ModelT]):
             tree = CTE("org_tree", raw_recursive_sql, recursive=True)
             rows = await Org.filter().with_cte(tree).raw_sql(\"SELECT * FROM org_tree\")
         """
-        self.ctes.extend(ctes)
-        return self
+        new = self._clone()
+        new.ctes.extend(ctes)
+        return new
 
     def nearest(
         self,
@@ -665,20 +705,22 @@ class QueryBuilder(Generic[ModelT]):
             for doc in results:
                 print(doc._vector_distance, doc.title)
         """
-        self.vector_order = {"column": column, "vector": vector, "metric": metric}
-        self.vector_null_guard = null_guard
-        return self
+        new = self._clone()
+        new.vector_order = {"column": column, "vector": vector, "metric": metric}
+        new.vector_null_guard = null_guard
+        return new
 
     def reverse(self) -> QueryBuilder[ModelT]:
         """Reverse each ordering term."""
+        new = self._clone()
         reversed_fields = []
-        for term in self.order_by_fields:
+        for term in new.order_by_fields:
             if isinstance(term, str):
                 reversed_fields.append(term[1:] if term.startswith("-") else f"-{term}")
             else:
                 reversed_fields.append(term)
-        self.order_by_fields = reversed_fields
-        return self
+        new.order_by_fields = reversed_fields
+        return new
 
     # ------------------------------------------------------------------
     # Internal query dict construction
@@ -814,8 +856,7 @@ class QueryBuilder(Generic[ModelT]):
         """Order by primary key (all columns, for composite PKs) descending
         and fetch the first record."""
         pk_names = self.model._meta.primary_keys or ["id"]
-        self.order_by(*(f"-{pk}" for pk in pk_names))
-        return await self.first()
+        return await self.order_by(*(f"-{pk}" for pk in pk_names)).first()
 
     async def get(self) -> ModelT:
         """Retrieve exactly one matching record; raises if 0 or >1 found.
@@ -917,11 +958,14 @@ class QueryBuilder(Generic[ModelT]):
                 total=Sum("amount"), avg=Avg("amount"), count=Count("id")
             )
         """
-        if kwargs:
-            for key, value in kwargs.items():
-                self.aggregations.append({"name": key, "function": value})
+        # Terminal, but takes query-shaping args — build on a clone so `self`
+        # is never mutated (clone-on-chain contract: a reused base builder must
+        # stay pristine after a derived .aggregate() call).
+        target = self._clone() if kwargs else self
+        for key, value in kwargs.items():
+            target.aggregations.append({"name": key, "function": value})
         try:
-            return await self._get_executor().aggregate()
+            return await target._get_executor().aggregate()
         except ORMException as e:
             e.enrich(
                 model=self.model, operation="aggregate", filters=self._merge_filters_excludes()
@@ -929,9 +973,10 @@ class QueryBuilder(Generic[ModelT]):
             raise
 
     async def values(self, *fields: str) -> list[dict[str, Any]]:
+        target = self._clone() if fields else self
         if fields:
-            self.select_fields = list(fields)
-        return await self._get_executor().values()
+            target.select_fields = list(fields)
+        return await target._get_executor().values()
 
     def compile(self, *fields: str) -> tuple[str, list[Any]]:
         """Build the SELECT SQL + bound-parameter list WITHOUT executing.
@@ -950,9 +995,10 @@ class QueryBuilder(Generic[ModelT]):
                 await conn.execute("SET LOCAL hnsw.iterative_scan = 'relaxed_order'")
                 rows = await conn.fetch(sql, *params)
         """
+        target = self._clone() if fields else self
         if fields:
-            self.select_fields = list(fields)
-        return self._get_executor()._build_query()
+            target.select_fields = list(fields)
+        return target._get_executor()._build_query()
 
     async def fetch_via(
         self,
@@ -1000,14 +1046,47 @@ class QueryBuilder(Generic[ModelT]):
     async def values_list(
         self, *fields: str, flat: bool = False
     ) -> list[tuple[Any, ...]] | list[Any]:
+        target = self._clone() if fields else self
         if fields:
-            self.select_fields = list(fields)
-        return await self._get_executor().values_list(flat=flat)
+            target.select_fields = list(fields)
+        return await target._get_executor().values_list(flat=flat)
 
     # ------------------------------------------------------------------
     # Synchronous wrappers
     # ------------------------------------------------------------------
 
+    def all_sync(self) -> list[ModelT]:
+        """Synchronous execution of the built query. Sync contexts only."""
+        import asyncio
+
+        from matrx_orm.core.async_db_manager import run_sync
+
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "QueryBuilder.all_sync() called in an async context. Use await .all() instead."
+            )
+        except RuntimeError as e:
+            if "no running event loop" not in str(e):
+                raise
+        return run_sync(self.all())
+
+    def first_sync(self) -> ModelT | None:
+        """Synchronous twin of first(). Sync contexts only."""
+        import asyncio
+
+        from matrx_orm.core.async_db_manager import run_sync
+
+        try:
+            asyncio.get_running_loop()
+            raise RuntimeError(
+                "QueryBuilder.first_sync() called in an async context. Use await .first() instead."
+            )
+        except RuntimeError as e:
+            if "no running event loop" not in str(e):
+                raise
+        return run_sync(self.first())
+
     def values_sync(self, *fields: str) -> list[dict[str, Any]]:
         """Synchronous wrapper for values()."""
         try:
@@ -1047,8 +1126,9 @@ class QueryBuilder(Generic[ModelT]):
         if isinstance(k, slice):
             start = k.start or 0
             stop = k.stop if k.stop is not None else 0
+            new = self
             if stop > 0:
-                self.limit(stop - start)
-            self.offset(start)
-            return self
+                new = new.limit(stop - start)
+            new = new.offset(start)
+            return new
         raise TypeError("Index access not supported, use slicing")