surreal-orm-lite 0.31.1__tar.gz → 0.31.2__tar.gz

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/CHANGELOG.md

@@ -5,6 +5,74 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.31.2] - 2026-10-19
+
+Transaction errors give the server's reason and the failed statement's position, without the
+server's excerpt of the statement, and a buffered commit raises `SurrealDbError` on the embedded
+engine too (#278). No new public API.
+
+### Fixed
+
+- **Transaction errors give the server's reason and the statement's position, without the
+  server's excerpt of the statement** (#278). When the server refused the query as a whole (a
+  statement it cannot parse), the error read "Transaction failed: unrecognized query_raw()
+  response shape: {…}" and quoted the server's raw response, its excerpt of the statement
+  included. It now gives the server's reason and the position:
+
+  - at a buffered commit (SurrealDB 2.x, HTTP, the embedded engine), "Transaction failed: the
+    server refused statement 2 of 3: … (at line 1, column 7 of the statement)", the line and column
+    of the statement as written, before the ORM renames its `$name` parameters for the batch; a
+    delimiter left unclosed names the statement it opens in, even when the server first reports it
+    in a later statement or on the batch's `COMMIT` line;
+  - for a write or a definition in an interactive transaction (SurrealDB 3.x over WebSocket),
+    "Transaction failed: the server refused the statement: … (at line 1, column 7 of the
+    statement)";
+  - a failed statement's error, "Transaction failed and rolled back: …", keeps only the first line
+    of a reason that quotes the query;
+  - a response of any other shape raises "Transaction failed: unrecognized query_raw() response
+    shape (<type>)", without the response.
+
+  The server's full text stays reachable as the error's `__context__`, which a formatted traceback
+  does not print. A read in a transaction still raises the SDK's own error, as it does outside a
+  transaction.
+
+- **A buffered commit on the embedded engine raises `SurrealDbError`** (#278). The engine reports a
+  query it cannot parse as a bare `RuntimeError`, which propagated out of the `transaction()` block;
+  the commit now raises `SurrealDbError`, or `SurrealDbConflictError` for a retryable conflict, as
+  on a server.
+- **A statement holding conflict words is not taken for a conflict** (#278). When the server could
+  not parse a statement holding words such as "write conflict", `is_conflict_error()` recognised
+  the transaction's error as a retryable conflict, so `retry_on_conflict` retried it, and an
+  interactive transaction's cancellation error was a `SurrealDbConflictError`. Conflicts are now
+  recognised from the server's reason, not from its excerpt of the statement.
+
+### Changed
+
+- **The cancellation error names the failed statement's error type** (#278). Since v0.30.3,
+  leaving an interactive `transaction()` block after a failed statement, or an explicit
+  `tx.commit()`, raises "The transaction was cancelled: a statement in it failed; nothing was
+  committed (…)", whose parenthesis repeated the failed statement's error text. The parenthesis now
+  holds that error's type name, for example `(SurrealDbError)`. The error itself is still chained
+  as `__cause__`, and a retryable conflict still raises `SurrealDbConflictError`, so
+  `retry_on_conflict` behaves as before.
+- **`is_conflict_error()` follows the chain a traceback prints** (#278): a context suppressed with
+  `raise … from None` is no longer read, since the ORM keeps the server's full text there, which
+  may quote the statement; `__cause__` and an implicit `__context__` are still followed. A conflict
+  your code re-raises as another exception with `raise … from None` is therefore no longer
+  recognised, nor retried by `retry_on_conflict`: chain it (`raise … from exc`, or `raise …`
+  without `from` inside the `except` block), or raise a `SurrealDbConflictError`, to keep it
+  retryable.
+
+### Notes
+
+- The v0.31.0 caution on the DDL appliers with `tx=` (#278), that an error raised when the
+  transaction ends can carry the server's excerpt of the statement, no longer applies: that error
+  now gives the server's reason and the statement's position instead. README sections 11 and 32
+  and the embedded-engine table say so.
+- Same behaviour on SurrealDB 2.x, 3.x and the embedded engine. Server pins unchanged: tested
+  against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus 3.1.5 for backward
+  compatibility.
+
 ## [0.31.1] - 2026-10-19
 
 A datetime outside years 1-9999 no longer fails the response it is in (#279). SurrealDB stores

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: surreal-orm-lite
-Version: 0.31.1
+Version: 0.31.2
 Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -732,10 +732,11 @@ cancelled when the block ends, nothing of the block is committed, and leaving th
 `SurrealDbError` (`SurrealDbConflictError` for a retryable conflict, so `retry_on_conflict` still
 retries the block). A buffered transaction fails as a whole at commit; an interactive one raises
 the failed statement's error at once, then, when the block ends, "The transaction was cancelled: a
-statement in it failed; nothing was committed (…)", chained to that error. An explicit
-`tx.commit()` after a failure raises the same error. When the block's own exception propagates,
-that exception wins, as before. Reads the ORM answers itself are not failed statements: a table
-that does not exist reads as no rows, and `get()` raises `SurrealDbNotFoundError`.
+statement in it failed; nothing was committed (SurrealDbError)", which names the type of that
+error and is chained to it. An explicit `tx.commit()` after a failure raises the same error. When
+the block's own exception propagates, that exception wins, as before. Reads the ORM answers itself
+are not failed statements: a table that does not exist reads as no rows, and `get()` raises
+`SurrealDbNotFoundError`.
 
 ```python
 async with SurrealDBConnectionManager.transaction() as tx:
@@ -747,6 +748,18 @@ async with SurrealDBConnectionManager.transaction() as tx:
 # leaving the block raised SurrealDbError: alice was not saved either
 ```
 
+**Transaction errors leave out the server's excerpt of the statement** (v0.31.2). When the server
+refuses the query as a whole (a statement it cannot parse), the error gives the server's reason and
+the position, without the server's excerpt of the statement: a buffered commit raises "Transaction
+failed: the server refused statement 2 of 3: … (at line 1, column 7 of the statement)", the
+embedded engine included, and a write or a definition in an interactive transaction raises
+"Transaction failed: the server refused the statement: … (at line 1, column 7 of the statement)".
+The line and column are those of the statement as written, before the ORM renames its `$name`
+parameters for the batch, and a delimiter left unclosed names the statement it opens in, even when
+the server stops in a later statement. The server's full text stays reachable as the error's
+`__context__`, which a traceback does not print. A read in a transaction is not affected: it raises
+the SDK's own error, as it does outside a transaction.
+
 ### 12. Upsert & get_or_create / update_or_create
 
 ```python
@@ -891,7 +904,11 @@ except SurrealDbConflictError:
 - Total attempts = `max_retries + 1`; after they are exhausted the conflict is re-raised as
   `SurrealDbConflictError`. The numeric parameters are validated at decoration time.
 - Detection anchors on SurrealDB's own retryable marker ("This transaction can be retried"), so
-  a non-retryable failure (e.g. a duplicate-key error) is **not** retried.
+  a non-retryable failure (e.g. a duplicate-key error) is **not** retried. `is_conflict_error()`
+  reads the exception and its chain as a traceback prints it: a context suppressed with
+  `raise … from None` is not read (v0.31.2), so a conflict you re-raise as another exception with
+  `raise … from None` is no longer recognised: chain it (`raise … from exc`, or `raise …` without
+  `from` inside the `except` block), or raise a `SurrealDbConflictError`.
 - The exception type is identical on 2.6.x and 3.x; conflicts simply arise more often on 3.x
   (optimistic MVCC) than on 2.6.x (see the behaviour table), except on change-feed tables, where
   2.x refuses concurrent writes that 3.x accepts (see [section 22](#22-change-feeds-changes)).
@@ -4685,7 +4702,8 @@ await SurrealDBConnectionManager.remove_function("fn::greet")
   (SurrealDB 2.x, HTTP, the embedded engine) only queues the statement, so a refusal comes back when the block
   commits, as the transaction's own error, never as `SurrealDbAuthenticationError` or `SurrealDbNotFoundError`,
   `missing_ok=False` included. When a definition is applied in a transaction (`tx=`), an error raised when the
-  transaction ends can still carry the server's message, statement excerpt included ([#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)).
+  transaction ends gives the server's reason and the statement's position, without the server's excerpt of the
+  statement (v0.31.2, [#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)).
 - Live queries see the rows an event writes (`watch()` on their table). The query cache
   ([section 29](#29-query-cache-cache-querycache)) does not: it forgets the tables the ORM itself writes, so a cached
   read of a table that events write stays as it was until its time to live runs out. Do not cache such reads, or call
@@ -4719,9 +4737,10 @@ swallow the clauses the ORM appends, a second statement where one expression is
 defence: expressions are trusted application code, never user input. To use a value, read it from the record
 (`$after.email`) or from a `DEFINE PARAM`, never format it into the text. Kinds are parsed and written in canonical
 form. An `Event`'s `repr()` leaves out its expressions, and a refusal raised without `tx=` names the event or the
-function, never its statement; with `tx=`, an error raised when the transaction ends can still carry the server's
-message, statement excerpt included ([#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)). Applying a definition needs a privileged system user: run
-`define_events()` and `define_function()` at start-up or deployment, not on a record user's session.
+function, never its statement; with `tx=`, an error raised when the transaction ends gives the server's reason and
+the statement's position, without the server's excerpt of the statement (v0.31.2,
+[#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)). Applying a definition needs a privileged
+system user: run `define_events()` and `define_function()` at start-up or deployment, not on a record user's session.
 
 #### Coming from the full SurrealDB-ORM
 
@@ -5016,7 +5035,7 @@ Capabilities not listed behave as on a 2.x server.
 | Anonymous session                                                   | the in-process owner (full access); `info()` returns `None`                                                                                                                                                                                                                                                                                           | not used by the ORM (the configured user signs in); an anonymous `info()` raises `SurrealDbAuthenticationError` | v0.25.0 |
 | `invalidate()`                                                      | back to the in-process owner                                                                                                                                                                                                                                                                                                                          | signs in again as the configured user                                                                           | v0.25.0 |
 | Reading a table that does not exist                                 | `[]`, raw queries included (as on 2.x)                                                                                                                                                                                                                                                                                                                | the ORM reads `[]`; a raw query on 3.x raises `NotFoundError`                                                   | v0.25.0 |
-| Parse errors                                                        | bare `RuntimeError` (the DDL helpers raise `SurrealDbError`)                                                                                                                                                                                                                                                                                          | the SDK's error classes                                                                                         | v0.25.0 |
+| Parse errors                                                        | bare `RuntimeError` (the DDL helpers and the commit of `transaction()` raise `SurrealDbError`)                                                                                                                                                                                                                                                        | the SDK's error classes                                                                                         | v0.25.0 |
 | Time travel (`as_of()`)                                             | `surrealkv+versioned://` only (`?versioned=true` is ignored by SDK 2.0.0); any other URL → `SurrealDbError` before any request; `fetch()` refused (2.x core)                                                                                                                                                                                          | versioned storage required (see the 2.x/3.x table)                                                              | v0.26.0 |
 | Several connections (`add_connection()`)                            | `mem://`: each name is a database of its own; an on-disk store (`surrealkv://`, `file://`) is open under one name at a time — a second name raises `SurrealDbConnectionError`                                                                                                                                                                         | each name opens its own clients; two databases on one server are isolated                                       | v0.29.0 |
 | Schema introspection (`DatabaseIntrospector`)                       | reads like a 2.x server (core 2.3.10): same state and same generated model types as on the servers; the anonymous owner session may run `INFO`; `COUNT` indexes cannot be defined                                                                                                                                                                     | need a system user (root, namespace or database user)                                                           | v0.30.0 |

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/README.md

@@ -681,10 +681,11 @@ cancelled when the block ends, nothing of the block is committed, and leaving th
 `SurrealDbError` (`SurrealDbConflictError` for a retryable conflict, so `retry_on_conflict` still
 retries the block). A buffered transaction fails as a whole at commit; an interactive one raises
 the failed statement's error at once, then, when the block ends, "The transaction was cancelled: a
-statement in it failed; nothing was committed (…)", chained to that error. An explicit
-`tx.commit()` after a failure raises the same error. When the block's own exception propagates,
-that exception wins, as before. Reads the ORM answers itself are not failed statements: a table
-that does not exist reads as no rows, and `get()` raises `SurrealDbNotFoundError`.
+statement in it failed; nothing was committed (SurrealDbError)", which names the type of that
+error and is chained to it. An explicit `tx.commit()` after a failure raises the same error. When
+the block's own exception propagates, that exception wins, as before. Reads the ORM answers itself
+are not failed statements: a table that does not exist reads as no rows, and `get()` raises
+`SurrealDbNotFoundError`.
 
 ```python
 async with SurrealDBConnectionManager.transaction() as tx:
@@ -696,6 +697,18 @@ async with SurrealDBConnectionManager.transaction() as tx:
 # leaving the block raised SurrealDbError: alice was not saved either
 ```
 
+**Transaction errors leave out the server's excerpt of the statement** (v0.31.2). When the server
+refuses the query as a whole (a statement it cannot parse), the error gives the server's reason and
+the position, without the server's excerpt of the statement: a buffered commit raises "Transaction
+failed: the server refused statement 2 of 3: … (at line 1, column 7 of the statement)", the
+embedded engine included, and a write or a definition in an interactive transaction raises
+"Transaction failed: the server refused the statement: … (at line 1, column 7 of the statement)".
+The line and column are those of the statement as written, before the ORM renames its `$name`
+parameters for the batch, and a delimiter left unclosed names the statement it opens in, even when
+the server stops in a later statement. The server's full text stays reachable as the error's
+`__context__`, which a traceback does not print. A read in a transaction is not affected: it raises
+the SDK's own error, as it does outside a transaction.
+
 ### 12. Upsert & get_or_create / update_or_create
 
 ```python
@@ -840,7 +853,11 @@ except SurrealDbConflictError:
 - Total attempts = `max_retries + 1`; after they are exhausted the conflict is re-raised as
   `SurrealDbConflictError`. The numeric parameters are validated at decoration time.
 - Detection anchors on SurrealDB's own retryable marker ("This transaction can be retried"), so
-  a non-retryable failure (e.g. a duplicate-key error) is **not** retried.
+  a non-retryable failure (e.g. a duplicate-key error) is **not** retried. `is_conflict_error()`
+  reads the exception and its chain as a traceback prints it: a context suppressed with
+  `raise … from None` is not read (v0.31.2), so a conflict you re-raise as another exception with
+  `raise … from None` is no longer recognised: chain it (`raise … from exc`, or `raise …` without
+  `from` inside the `except` block), or raise a `SurrealDbConflictError`.
 - The exception type is identical on 2.6.x and 3.x; conflicts simply arise more often on 3.x
   (optimistic MVCC) than on 2.6.x (see the behaviour table), except on change-feed tables, where
   2.x refuses concurrent writes that 3.x accepts (see [section 22](#22-change-feeds-changes)).
@@ -4634,7 +4651,8 @@ await SurrealDBConnectionManager.remove_function("fn::greet")
   (SurrealDB 2.x, HTTP, the embedded engine) only queues the statement, so a refusal comes back when the block
   commits, as the transaction's own error, never as `SurrealDbAuthenticationError` or `SurrealDbNotFoundError`,
   `missing_ok=False` included. When a definition is applied in a transaction (`tx=`), an error raised when the
-  transaction ends can still carry the server's message, statement excerpt included ([#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)).
+  transaction ends gives the server's reason and the statement's position, without the server's excerpt of the
+  statement (v0.31.2, [#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)).
 - Live queries see the rows an event writes (`watch()` on their table). The query cache
   ([section 29](#29-query-cache-cache-querycache)) does not: it forgets the tables the ORM itself writes, so a cached
   read of a table that events write stays as it was until its time to live runs out. Do not cache such reads, or call
@@ -4668,9 +4686,10 @@ swallow the clauses the ORM appends, a second statement where one expression is
 defence: expressions are trusted application code, never user input. To use a value, read it from the record
 (`$after.email`) or from a `DEFINE PARAM`, never format it into the text. Kinds are parsed and written in canonical
 form. An `Event`'s `repr()` leaves out its expressions, and a refusal raised without `tx=` names the event or the
-function, never its statement; with `tx=`, an error raised when the transaction ends can still carry the server's
-message, statement excerpt included ([#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)). Applying a definition needs a privileged system user: run
-`define_events()` and `define_function()` at start-up or deployment, not on a record user's session.
+function, never its statement; with `tx=`, an error raised when the transaction ends gives the server's reason and
+the statement's position, without the server's excerpt of the statement (v0.31.2,
+[#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)). Applying a definition needs a privileged
+system user: run `define_events()` and `define_function()` at start-up or deployment, not on a record user's session.
 
 #### Coming from the full SurrealDB-ORM
 
@@ -4965,7 +4984,7 @@ Capabilities not listed behave as on a 2.x server.
 | Anonymous session                                                   | the in-process owner (full access); `info()` returns `None`                                                                                                                                                                                                                                                                                           | not used by the ORM (the configured user signs in); an anonymous `info()` raises `SurrealDbAuthenticationError` | v0.25.0 |
 | `invalidate()`                                                      | back to the in-process owner                                                                                                                                                                                                                                                                                                                          | signs in again as the configured user                                                                           | v0.25.0 |
 | Reading a table that does not exist                                 | `[]`, raw queries included (as on 2.x)                                                                                                                                                                                                                                                                                                                | the ORM reads `[]`; a raw query on 3.x raises `NotFoundError`                                                   | v0.25.0 |
-| Parse errors                                                        | bare `RuntimeError` (the DDL helpers raise `SurrealDbError`)                                                                                                                                                                                                                                                                                          | the SDK's error classes                                                                                         | v0.25.0 |
+| Parse errors                                                        | bare `RuntimeError` (the DDL helpers and the commit of `transaction()` raise `SurrealDbError`)                                                                                                                                                                                                                                                        | the SDK's error classes                                                                                         | v0.25.0 |
 | Time travel (`as_of()`)                                             | `surrealkv+versioned://` only (`?versioned=true` is ignored by SDK 2.0.0); any other URL → `SurrealDbError` before any request; `fetch()` refused (2.x core)                                                                                                                                                                                          | versioned storage required (see the 2.x/3.x table)                                                              | v0.26.0 |
 | Several connections (`add_connection()`)                            | `mem://`: each name is a database of its own; an on-disk store (`surrealkv://`, `file://`) is open under one name at a time — a second name raises `SurrealDbConnectionError`                                                                                                                                                                         | each name opens its own clients; two databases on one server are isolated                                       | v0.29.0 |
 | Schema introspection (`DatabaseIntrospector`)                       | reads like a 2.x server (core 2.3.10): same state and same generated model types as on the servers; the anonymous owner session may run `INFO`; `COUNT` indexes cannot be defined                                                                                                                                                                     | need a system user (root, namespace or database user)                                                           | v0.30.0 |

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.31.1"
+version = "0.31.2"
 description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
 readme = "README.md"
 requires-python = ">=3.11"

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.31.1"
+__version__ = "0.31.2"
 
 from ._sdk import BoundExcluded, BoundIncluded
 from .aggregations import Aggregation, Avg, Count, Max, Min, Sum

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/concurrency.py

@@ -42,7 +42,9 @@ def is_conflict_error(error: BaseException) -> bool:
     A :class:`SurrealDbConflictError` always qualifies. Otherwise the exception
     and its ``__cause__`` / ``__context__`` chain are scanned for one of the
     conflict signal phrases (so a conflict wrapped in another exception is still
-    recognised).
+    recognised). The chain is the one a traceback prints: a context suppressed with
+    ``raise … from None`` is not part of it (#278) — the ORM keeps a server's full
+    text there, and a statement it quotes may hold conflict words.
     """
     if isinstance(error, SurrealDbConflictError):
         return True
@@ -53,7 +55,10 @@ def is_conflict_error(error: BaseException) -> bool:
         text = str(current).lower()
         if any(signal in text for signal in _CONFLICT_SIGNALS):
             return True
-        current = current.__cause__ or current.__context__
+        if current.__cause__ is not None:
+            current = current.__cause__
+        else:
+            current = None if current.__suppress_context__ else current.__context__
     return False
 
 

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/connection_manager.py

@@ -1682,9 +1682,15 @@ class SurrealDBConnectionManager:
         raises ``SurrealDbError`` (``SurrealDbConflictError`` for a retryable conflict, so
         ``retry_on_conflict`` still retries). A buffered batch fails as a whole at commit; an
         interactive transaction raises "The transaction was cancelled: a statement in it failed;
-        nothing was committed (…)", chained to the failed statement's error. When the body's own
-        exception propagates, that exception wins. A read the ORM answers itself (a missing table
-        read as no rows, ``get()`` raising ``SurrealDbNotFoundError``) is not a failed statement.
+        nothing was committed (SurrealDbError)", which names the type of the failed statement's
+        error and is chained to it. When the body's own exception propagates, that exception wins.
+        A read the ORM answers itself (a missing table read as no rows, ``get()`` raising
+        ``SurrealDbNotFoundError``) is not a failed statement.
+
+        A query the server refuses as a whole (a statement it cannot parse) raises ``SurrealDbError``
+        with the server's reason and the position, without the server's excerpt of the statement
+        (issue #278): "Transaction failed: the server refused statement 2 of 3: … (at line 1, column 7
+        of the statement)" at a buffered commit, the embedded engine included.
 
         SurrealDB has no savepoints/nested transactions; nested ``transaction()`` calls
         open INDEPENDENT transactions, not savepoints.
@@ -2488,7 +2494,7 @@ class SurrealDBConnectionManager:
             without *tx*, a refusal names the event and its table, never its statement, whose ``when`` and
             ``then`` may hold a secret). In a buffered transaction (*tx* over HTTP, on SurrealDB 2.x or the
             embedded engine) the statement is only queued: a refusal comes back when the block commits, as the
-            transaction's own error, never as ``SurrealDbAuthenticationError``. With *tx*, an error raised when the transaction ends can still carry the server's message, statement excerpt included (#278).
+            transaction's own error, never as ``SurrealDbAuthenticationError``. With *tx*, an error raised when the transaction ends gives the server's reason and the statement's position, without the server's excerpt of the statement (#278).
         :raises SurrealDbAuthenticationError: the session may not define events.
         """
         check_call_transaction(cls._connection_name or "default", tx, operation="define_event()")
@@ -2610,7 +2616,7 @@ class SurrealDBConnectionManager:
             statement (``Can't apply function definition: 'fn::greet' -> …``: without *tx*, a refusal names the
             function, never its statement, whose body may hold a secret). In a buffered transaction (*tx* over HTTP,
             on SurrealDB 2.x or the embedded engine) the statement is only queued: a refusal comes back when the
-            block commits, as the transaction's own error, never as ``SurrealDbAuthenticationError``. With *tx*, an error raised when the transaction ends can still carry the server's message, statement excerpt included (#278).
+            block commits, as the transaction's own error, never as ``SurrealDbAuthenticationError``. With *tx*, an error raised when the transaction ends gives the server's reason and the statement's position, without the server's excerpt of the statement (#278).
         """
         check_call_transaction(cls._connection_name or "default", tx, operation="define_function()")
         statement = function_ddl(

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/model_base.py

@@ -849,8 +849,8 @@ class BaseSurrealModel(BaseModel):
 
         Without *tx*, a refusal names the event and its table, never its statement, whose ``when`` and ``then``
         may hold a secret: ``Can't apply event definition: 'email_audit' on table 'account' -> <the server's
-        reason>``. With *tx*, an error raised when the transaction ends can still carry the server's message,
-        statement excerpt included (#278).
+        reason>``. With *tx*, an error raised when the transaction ends gives the server's reason and the
+        statement's position, without the server's excerpt of the statement (#278).
 
         Args:
             overwrite: see :meth:`event_ddl`.

{surreal_orm_lite-0.31.1 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/transaction.py

@@ -24,14 +24,23 @@ Query cache (v0.28.0): an ORM write that joins a transaction notes the tables it
 (``_note_cache_write``); the commit puts them in flight and invalidates their cached reads when
 it returns or raises (a failed commit's state is unknown). ``cancel()`` forgets them: nothing
 became visible.
+
+Errors (issue #278): the errors a failed transaction raises give the server's reason and the failed statement's
+position, without the server's excerpt of the statement; the server's own text stays reachable as their suppressed
+``__context__``. A query the server or the embedded engine refuses at a buffered commit raises ``SurrealDbError`` on
+every engine (the embedded engine's bare ``RuntimeError`` included), ``SurrealDbConflictError`` for a retryable
+conflict; a transport error (a lost connection, a timeout) is not a refusal and propagates unchanged, since the
+commit's outcome is unknown. A read relays the SDK's own error, as outside a transaction. After a failed statement,
+an interactive transaction's cancellation error names only that statement's error type.
 """
 
 import contextlib
 import re
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable, Iterable
-from typing import Any
+from typing import Any, NoReturn
 
+from . import _sdk
 from . import cache as _cache
 from . import encoding as _encoding
 from .exceptions import SurrealDbConflictError, SurrealDbError
@@ -41,10 +50,19 @@ _PARAMETER = re.compile(r"\$(\w+)")
 
 _NOT_EXECUTED_FILLER = "The query was not executed due to a failed transaction"
 
-#: The error ``InteractiveTransaction.commit()`` raises after a failed statement (issue #268), followed by that
-#: statement's error.
+#: The error ``InteractiveTransaction.commit()`` raises after a failed statement (issue #268), followed by the type
+#: name of that statement's error in parentheses (issue #278), e.g. ``(SurrealDbError)``.
 _CANCELLED_AFTER_FAILURE = "The transaction was cancelled: a statement in it failed; nothing was committed"
 
+#: Where a server's error starts quoting the query it refused (issue #278): a parse error's `` --> [line:column]``, on
+#: a line of its own, followed by an excerpt of the query.
+_QUERY_EXCERPT = re.compile(r"\n\s*--> \[(\d+):(\d+)\]")
+
+#: Maps a position of a buffered batch's query (line, column) to the queued statement it falls in (issue #278):
+#: ``(number, count, line, column)``, the line and column in the text the caller queued; ``None`` outside every
+#: statement (:meth:`BufferedTransaction._locate`).
+_Locate = Callable[[int, int], tuple[int, int, int, int] | None]
+
 
 def _is_pure_filler(result: Any) -> bool:
     """True if a statement's message is ONLY the generic 'not executed' filler.
@@ -65,6 +83,111 @@ def _as_conflict(exc: Exception) -> Exception:
     return exc
 
 
+def _error_type(server_text: str) -> type[SurrealDbError]:
+    """``SurrealDbConflictError`` when *server_text* reports a retryable conflict, else ``SurrealDbError``."""
+    from .concurrency import is_conflict_error
+
+    return SurrealDbConflictError if is_conflict_error(SurrealDbError(server_text)) else SurrealDbError
+
+
+def _server_reason(message: str) -> tuple[str, list[tuple[int, int]]]:
+    """The server's reason in *message*, without any of the query's text, and the positions it gives (issue #278).
+
+    A message that quotes the query — a parse error, from `` --> [line:column]`` on, and on some errors in the lines
+    before it too (a regex's) — is cut to its first line, and every line and column it gives is returned, in order
+    (an unclosed delimiter gives where the parser stopped, then where the delimiter opens). Any other message is the
+    reason as it is, with no position.
+    """
+    positions = [(int(found[1]), int(found[2])) for found in _QUERY_EXCERPT.finditer(message)]
+    if not positions:
+        return message, []
+    return message.partition("\n")[0].rstrip(), positions
+
+
+def _refusal(message: str, locate: _Locate | None = None) -> SurrealDbError:
+    """The ORM's error for a query the server refused as a whole with *message* (issue #278).
+
+    ``Transaction failed: the server refused <what>: <reason> (at line <l>, column <c> of <where>)``: the reason is
+    :func:`_server_reason`'s, never the query's text. With *locate* (a buffered batch), the position names the queued
+    statement, ``statement 2 of 3``, with the line and column in the text the caller queued; without it, the position
+    is the statement's (an interactive transaction runs one at a time). The server gives an unclosed delimiter two
+    positions, where it stopped and then where the delimiter opens: the stop can fall in a later statement or on the
+    ``COMMIT`` line. So the statement named is the one that holds the last position falling in a queued statement,
+    and the position given is the first the server gives in that statement (where it stopped, when that is in it
+    too); outside every statement, the query's first position. ``SurrealDbConflictError`` when the reason reports a
+    retryable conflict: the excerpt, which may quote conflict words, is not read.
+    """
+    reason, positions = _server_reason(message)
+    error_type = _error_type(reason)
+    if not positions:
+        return error_type(f"Transaction failed: the server refused the query: {reason}")
+    line, column = positions[0]
+    what, where = "the statement", "the statement"
+    if locate is not None:
+        places = [place for place in (locate(*position) for position in positions) if place is not None]
+        if not places:
+            what, where = "the query", "the query"
+        else:
+            number, count, line, column = next(place for place in places if place[0] == places[-1][0])
+            what = f"statement {number} of {count}"
+    at = f"at line {line}, column {column} of {where}"
+    return error_type(f"Transaction failed: the server refused {what}: {reason} ({at})")
+
+
+def _raise_hiding(error: SurrealDbError, server_text: str) -> NoReturn:
+    """Raise *error* ``from None``, *server_text* kept as its ``__context__`` (a ``SurrealDbError``) (issue #278).
+
+    A formatted traceback shows *error* alone: the server's text, which may quote the statement, stays reachable for
+    debugging without being printed.
+    """
+    try:
+        raise SurrealDbError(server_text)
+    except SurrealDbError:
+        raise error from None
+
+
+def _raise_for_status(raw: Any, locate: _Locate | None = None) -> None:
+    """:meth:`Transaction.raise_for_status`, with *locate* for a buffered batch (issue #278): a position then names
+    the queued statement (``statement 2 of 3``)."""
+    if not isinstance(raw, dict) or not isinstance(raw.get("result"), list):
+        envelope = raw.get("error") if isinstance(raw, dict) else None
+        message = envelope.get("message") if isinstance(envelope, dict) else None
+        if isinstance(message, str) and message:
+            _raise_hiding(_refusal(message, locate), message)
+        _raise_hiding(
+            SurrealDbError(f"Transaction failed: unrecognized query_raw() response shape ({type(raw).__name__})"),
+            repr(raw),
+        )
+    statements = raw["result"]
+    errors = [s for s in statements if isinstance(s, dict) and s.get("status") == "ERR"]
+    if not errors:
+        return
+    # Prefer a real error (kind != NotExecuted, and not the generic "not executed"
+    # filler); else the first ERR whose message is not that filler (the real cause is
+    # sometimes a NotExecuted statement, e.g. "Cannot COMMIT: Transaction conflict ...",
+    # and some servers omit `details` on filler statements); else the first ERR.
+    root = (
+        next(
+            (
+                e
+                for e in errors
+                if (e.get("details") or {}).get("kind") != "NotExecuted" and not _is_pure_filler(e.get("result"))
+            ),
+            None,
+        )
+        or next((e for e in errors if not _is_pure_filler(e.get("result"))), None)
+        or errors[0]
+    )
+    message = str(root.get("result") or "transaction failed")
+    reason, positions = _server_reason(message)
+    # Type retryable conflicts so callers / retry_on_conflict can catch them, from the reason alone (#278): a real
+    # conflict has no excerpt, and an excerpt may quote conflict words.
+    error = _error_type(reason)(f"Transaction failed and rolled back: {reason}")
+    if not positions:
+        raise error
+    _raise_hiding(error, message)
+
+
 class Transaction(ABC):
     """Base transaction: shared post-commit machinery + the call-site interface.
 
@@ -167,7 +290,7 @@ class Transaction(ABC):
 
     @staticmethod
     def raise_for_status(raw: Any) -> None:
-        """Inspect a ``query_raw()`` response and raise if any statement failed.
+        """Inspect a ``query_raw()`` response and raise if the query or any statement failed.
 
         ``query()`` silently returns ``None`` on a failed transaction, so the
         commit/write paths use ``query_raw()`` and call this. Any statement with
@@ -175,35 +298,16 @@ class Transaction(ABC):
         interactive transaction when it ends (its ``commit()`` cancels after a failed statement,
         issue #268). Prefers the root cause (the first ERR whose ``details.kind`` is not
         ``"NotExecuted"``).
+
+        The error leaves out the server's excerpt of the query (issue #278). A query the server
+        refused as a whole (an ``error`` envelope, e.g. a statement it cannot parse) raises
+        ``Transaction failed: the server refused …`` with the server's reason and the position it
+        gives (:func:`_refusal`); a failed statement raises ``Transaction failed and rolled back:
+        <the server's reason>``, a reason that quotes the query cut to its first line. Whenever the
+        message leaves part of the server's text out, that text is kept as the error's suppressed
+        ``__context__``. ``SurrealDbConflictError`` for a retryable conflict.
         """
-        if not isinstance(raw, dict) or not isinstance(raw.get("result"), list):
-            raise SurrealDbError(f"Transaction failed: unrecognized query_raw() response shape: {raw!r}")
-        statements = raw["result"]
-        errors = [s for s in statements if isinstance(s, dict) and s.get("status") == "ERR"]
-        if not errors:
-            return
-        # Prefer a real error (kind != NotExecuted, and not the generic "not executed"
-        # filler); else the first ERR whose message is not that filler (the real cause is
-        # sometimes a NotExecuted statement, e.g. "Cannot COMMIT: Transaction conflict ...",
-        # and some servers omit `details` on filler statements); else the first ERR.
-        root = (
-            next(
-                (
-                    e
-                    for e in errors
-                    if (e.get("details") or {}).get("kind") != "NotExecuted" and not _is_pure_filler(e.get("result"))
-                ),
-                None,
-            )
-            or next((e for e in errors if not _is_pure_filler(e.get("result"))), None)
-            or errors[0]
-        )
-        message = root.get("result") or "transaction failed"
-        full = f"Transaction failed and rolled back: {message}"
-        # Type retryable conflicts so callers / retry_on_conflict can catch them.
-        if isinstance(_as_conflict(SurrealDbError(full)), SurrealDbConflictError):
-            raise SurrealDbConflictError(full)
-        raise SurrealDbError(full)
+        _raise_for_status(raw)
 
 
 class BufferedTransaction(Transaction):
@@ -219,6 +323,9 @@ class BufferedTransaction(Transaction):
         self.statements: list[str] = []
         self.variables: dict[str, Any] = {}
         self._counter: int = 0
+        # Issue #278: per queued statement, the length of its prefix and where add() inserted it (offsets in the
+        # caller's text), so that a position the server gives is moved back to the caller's column.
+        self._renamed_at: list[tuple[int, list[int]]] = []
 
     @property
     def is_interactive(self) -> bool:
@@ -234,19 +341,27 @@ class BufferedTransaction(Transaction):
         Each ``$name`` of ``variables`` becomes ``$t<N>_name``, in a single pass over the statement (#261): a name is
         matched whole, so one that is a prefix of another is not corrupted, a renamed name is never renamed again, and
         a parameter that is not one of ``variables`` (``$this``, ``$value``…) is left alone. Returns None: nothing
-        executes until commit, so buffered writes cannot return rows.
+        executes until commit, so buffered writes cannot return rows. Where each prefix goes is noted, so that a
+        position the server reports at commit is given in the caller's text (issue #278).
         """
         variables = _encoding.encode(variables)
         prefix = f"t{self._counter}_"
         renamed = statement
+        inserted: list[int] = []
         if variables:
-            renamed = _PARAMETER.sub(
-                lambda match: f"${prefix}{match[1]}" if match[1] in variables else match[0],
-                statement,
-            )
+            names = set(variables)
+
+            def rename(match: re.Match[str]) -> str:
+                if match[1] not in names:
+                    return match[0]
+                inserted.append(match.start() + 1)  # right after the "$"
+                return f"${prefix}{match[1]}"
+
+            renamed = _PARAMETER.sub(rename, statement)
             for name, value in variables.items():
                 self.variables[f"{prefix}{name}"] = value
         self.statements.append(renamed)
+        self._renamed_at.append((len(prefix), inserted))
         self._counter += 1
         return None
 
@@ -264,6 +379,42 @@ class BufferedTransaction(Transaction):
         body = "\n".join(self.statements)
         return f"BEGIN TRANSACTION;\n{body}\nCOMMIT TRANSACTION;"
 
+    def _locate(self, line: int, column: int) -> tuple[int, int, int, int] | None:
+        """The queued statement that *line* of :meth:`build_query`'s query falls in, and the position in the caller's
+        text: ``(number, count, line, column)``; ``None`` outside every statement (issue #278).
+
+        Line 1 is ``BEGIN TRANSACTION;``; each statement starts on the line after the previous one ends.
+        """
+        first = 2
+        for index, statement in enumerate(self.statements):
+            last = first + statement.count("\n")
+            if first <= line <= last:
+                own_line = line - first + 1
+                return index + 1, len(self.statements), own_line, self._caller_column(index, own_line, column)
+            first = last + 1
+        return None
+
+    def _caller_column(self, index: int, line: int, column: int) -> int:
+        """*column* of *line* of the queued statement *index*, moved back over the prefixes :meth:`add` inserted
+        before it on that line. SurrealDB counts columns in characters, as Python does; a column inside a prefix
+        becomes the name's first character. Unchanged when ``statements`` no longer matches what :meth:`add` noted.
+        """
+        if len(self._renamed_at) != len(self.statements):
+            return column
+        size, inserted = self._renamed_at[index]
+        line_start = sum(len(text) + 1 for text in self.statements[index].split("\n")[: line - 1])
+        offset = line_start + column - 1
+        on_earlier_lines = before = 0
+        for earlier, original in enumerate(inserted):
+            start = original + earlier * size  # where this prefix starts in the queued text
+            if start + size <= line_start:
+                on_earlier_lines += 1
+            if start + size <= offset:
+                before += 1
+            elif start <= offset:
+                return start - line_start + 1 - (before - on_earlier_lines) * size
+        return column - (before - on_earlier_lines) * size
+
     async def commit(self) -> None:
         # The tables noted are in flight during the commit and invalidated when it returns
         # or raises (a failed commit's state is unknown).
@@ -273,8 +424,17 @@ class BufferedTransaction(Transaction):
                     return
                 # query_raw (NOT query): query() returns None on a failed tx; query_raw gives
                 # per-statement status for raise_for_status.
-                raw = await self._client.query_raw(self.build_query(), _encoding.encode(self.variables))
-                self.raise_for_status(raw)
+                try:
+                    raw = await self._client.query_raw(self.build_query(), _encoding.encode(self.variables))
+                except RuntimeError as exc:
+                    # The embedded engine raises a bare RuntimeError for a query it refuses as a whole (issue
+                    # #278): the same error as a server's envelope, the engine's error kept as the suppressed
+                    # __context__. A server client's RuntimeError is not the server's answer: it propagates.
+                    embedded = _sdk.SdkAsyncEmbeddedConnection
+                    if embedded is None or not isinstance(self._client, embedded):
+                        raise
+                    raise _refusal(str(exc), self._locate) from None
+                _raise_for_status(raw, self._locate)
         finally:
             self._forget_cache_writes()
 
@@ -284,6 +444,7 @@ class BufferedTransaction(Transaction):
         self._forget_cache_writes()
         self.statements = []
         self.variables = {}
+        self._renamed_at = []
 
 
 class InteractiveTransaction(Transaction):
@@ -348,9 +509,10 @@ class InteractiveTransaction(Transaction):
         """Commit the transaction; after a failed statement, cancel it and raise instead (issue #268).
 
         Raises:
-            SurrealDbError: a statement failed in this transaction (:data:`_CANCELLED_AFTER_FAILURE`, followed by that
-                statement's error, which is chained as the cause): the transaction was cancelled, nothing was
-                committed. ``SurrealDbConflictError`` when that statement's error was a retryable conflict.
+            SurrealDbError: a statement failed in this transaction (:data:`_CANCELLED_AFTER_FAILURE`, followed by the
+                type name of that statement's error, e.g. ``(SurrealDbError)``; the error itself is chained as the
+                cause): the transaction was cancelled, nothing was committed. ``SurrealDbConflictError`` when that
+                statement's error was a retryable conflict.
         """
         failure = self._first_failure()
         if failure is not None:
@@ -358,7 +520,8 @@ class InteractiveTransaction(Transaction):
 
             await self.cancel()
             error_type = SurrealDbConflictError if is_conflict_error(failure) else SurrealDbError
-            raise error_type(f"{_CANCELLED_AFTER_FAILURE} ({str(failure) or type(failure).__name__})") from failure
+            # Only the type name (issue #278): the failed statement's error is the cause, its text is not repeated.
+            raise error_type(f"{_CANCELLED_AFTER_FAILURE} ({type(failure).__name__})") from failure
         # The tables noted are in flight during the commit and invalidated when it returns
         # or raises (a failed commit's state is unknown).
         try: