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

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

@@ -5,6 +5,108 @@ 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
+datetimes far beyond the years a Python `datetime` holds, and the ORM now reads them back as the
+server's own text. No new public API.
+
+### Fixed
+
+- **Reading a datetime before year 1 or after year 9999** (#279). SurrealDB stores datetimes from
+  year -262143 to +262142, on 2.x and 3.x, but the surrealdb SDK 2.0.0 decodes a datetime into a
+  Python `datetime`, which holds years 1-9999 only: one such value failed the whole response it
+  was in, whether it came from `get()`, `filter()`, `raw_query()` or a live notification. The
+  ORM's clients now read it as its RFC 3339 text, the one SurrealDB gives it with `<string>`:
+  `"0000-06-01T00:00:00Z"`, `"-0001-01-01T00:00:00Z"`, `"+10000-01-01T00:00:00.500Z"` (a sign and
+  at least four digits outside years 0000-9999, every nanosecond kept). An untyped field holds
+  that string; a `datetime` field refuses it with a `ValidationError` naming the field, so `get()`
+  raises it and `filter().exec()` and `raw_query()` return such rows as dicts, as for any row
+  that does not validate. Written back through the ORM, the value is stored as that string. A
+  datetime within years 1-9999, before 1970 included, reads as the SDK's `datetime`, as before.
+
+### Notes
+
+- As for zero durations, native sets and degenerate geometries, only the clients the ORM opens
+  (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`, the embedded engine's
+  included) read these values; an `AsyncSurreal` client the application builds itself keeps the
+  SDK's behaviour. The ORM leaves them to the SDK as soon as an installed SDK decodes them itself.
+  README: "Values the SDK cannot read" and a new row of the 2.x/3.x behaviour table.
+- The function catalogue test (`TestFunctionEnumsE2E`) calls `rand::time()` between 2000 and 2030
+  and checks the result. Unbounded, it drew a year-0 datetime in about one call in 7,400 (27 in
+  200,000 on each line), which made the test fail at random.
+- 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.0] - 2026-10-19
 
 Server-side events and DDL helpers: the ORM writes and applies `DEFINE EVENT` and

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: surreal-orm-lite
-Version: 0.31.0
+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)).
@@ -2499,31 +2516,42 @@ an `IntEnum` gives the value), so use `.value` to build a key, a URL or a log li
 #### Values the SDK cannot read
 
 The surrealdb SDK 2.0.0 cannot decode a zero duration, a SurrealDB 3.x native set (a
-`TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)) or a degenerate geometry (see
-[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)): one such value fails the whole
-response it is in. The clients the ORM opens read them anyway, through a hook around the SDK's own
-CBOR decoder that handles only these values; everything else reads exactly as the SDK reads it:
+`TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)), a degenerate geometry (see
+[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)) or a datetime outside years
+1-9999, the years a Python `datetime` holds (SurrealDB stores years -262143 to +262142, on both
+lines): one such value fails the whole response it is in. The clients the ORM opens read them
+anyway, through a hook around the SDK's own CBOR decoder that handles only these values; everything
+else reads exactly as the SDK reads it:
 
 - a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
   `Duration(0)` in an untyped one;
 - a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as a
   `list` when its items are unhashable (record ids, objects, nested sets) or two of them are equal
-  in Python, like `1` and `true`: every item the server holds comes back.
+  in Python, like `1` and `true`: every item the server holds comes back;
+- a datetime before `0001-01-01T00:00:00Z` or after `9999-12-31T23:59:59.999999999Z` reads as its
+  RFC 3339 text, the one SurrealDB gives it (`<string>`): `"0000-06-01T00:00:00Z"`,
+  `"-0001-01-01T00:00:00Z"`, `"+10000-01-01T00:00:00.500Z"` (a sign and at least four digits outside
+  years 0000-9999, every nanosecond kept). An untyped field, `raw_query()` and live notifications
+  give that string; a `datetime` field refuses it with a `ValidationError` naming the field: `get()`
+  raises it, and `filter().exec()` and `raw_query()` return such rows as dicts, as for any row that
+  does not validate. A datetime within years 1-9999, before 1970 included, reads as the SDK's
+  `datetime`, as before.
 
 Written back through the ORM (`merge(v=row.v)`, or `update()`, which rewrites the whole row, the
 untouched fields included), a zero duration stays a duration, but a native set is stored as an
-array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), and
-a degenerate geometry as a plain object (see
-[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)). In an untyped field, `update()`
-flattens the SDK's `Duration(0)` into an object, like any SDK value there
+array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), a
+degenerate geometry as a plain object (see
+[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)), and a datetime outside years
+1-9999 as its text, a string. In an untyped field, `update()` flattens the SDK's `Duration(0)` into
+an object, like any SDK value there
 ([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
 
 The hook is installed only while the installed SDK cannot decode these values, and only on the
 ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`), the embedded
 engine's included (see [Embedded engine and test fixtures](#26-embedded-engine-and-test-fixtures)):
-there a zero duration and a degenerate geometry read as on a server, and `<set>[…]` is stored as an
-array, as on 2.x. An `AsyncSurreal` client the application builds itself keeps the SDK's behaviour
-and fails on them.
+there a zero duration, a degenerate geometry and a datetime outside years 1-9999 read as on a
+server, and `<set>[…]` is stored as an array, as on 2.x. An `AsyncSurreal` client the application
+builds itself keeps the SDK's behaviour and fails on them.
 A later SDK reads zero durations and native sets itself
 ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
 leaves them to it.
@@ -4674,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
@@ -4708,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
 
@@ -4849,7 +4879,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
 listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
 on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
 otherwise. The full suite and every divergence below were re-verified on both new versions.
-Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
+Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
 The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
 
 | ORM capability                                                                                                                         | SurrealDB 2.6.x / 2.7.x                                                                                                                                                       | SurrealDB 3.2.x / 3.3.x                                                                                                                                                             | Since                                |
@@ -4976,6 +5006,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
 | An event whose `THEN` fails (a `THROW`, an error)                                                                                      | the write is refused; the SDK's `InternalError` (`An error occurred: …` for a `THROW`, the bare cause otherwise)                                                              | the write is refused; the SDK's `InternalError` (`Error while processing event <name>: …`)                                                                                          | v0.31.0                              |
 | Event and function definitions read back (`EventState`, `FunctionState`)                                                               | a block on several lines, each statement ending with `;`; `option<T>` parameters as written                                                                                   | a block on one line, no `;` after a single statement; optional parameters rendered with `none` first                                                                                | v0.31.0                              |
 | `define_function()`, `remove_function()` and `call_function()`                                                                         | same on both lines: the next `call_function()` sees a redefinition on every connection of this process to the same namespace and database, whatever its URL                   | the same                                                                                                                                                                            | v0.31.0                              |
+| Reading a datetime before year 1 or after year 9999 (SurrealDB stores years -262143 to +262142)                                        | its RFC 3339 text, as `<string>` gives it (`"+10000-01-01T00:00:00Z"`): an untyped field holds it, a `datetime` field refuses it (`ValidationError`)                          | same on both lines                                                                                                                                                                  | v0.31.1                              |
 | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0                                                     | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips)                                                                                                                   | 3.3.0 identical to 3.2.4, except the system-user signin row                                                                                                                         | v0.19.1                              |
 
 > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -5004,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.0 → 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)).
@@ -2448,31 +2465,42 @@ an `IntEnum` gives the value), so use `.value` to build a key, a URL or a log li
 #### Values the SDK cannot read
 
 The surrealdb SDK 2.0.0 cannot decode a zero duration, a SurrealDB 3.x native set (a
-`TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)) or a degenerate geometry (see
-[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)): one such value fails the whole
-response it is in. The clients the ORM opens read them anyway, through a hook around the SDK's own
-CBOR decoder that handles only these values; everything else reads exactly as the SDK reads it:
+`TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)), a degenerate geometry (see
+[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)) or a datetime outside years
+1-9999, the years a Python `datetime` holds (SurrealDB stores years -262143 to +262142, on both
+lines): one such value fails the whole response it is in. The clients the ORM opens read them
+anyway, through a hook around the SDK's own CBOR decoder that handles only these values; everything
+else reads exactly as the SDK reads it:
 
 - a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
   `Duration(0)` in an untyped one;
 - a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as a
   `list` when its items are unhashable (record ids, objects, nested sets) or two of them are equal
-  in Python, like `1` and `true`: every item the server holds comes back.
+  in Python, like `1` and `true`: every item the server holds comes back;
+- a datetime before `0001-01-01T00:00:00Z` or after `9999-12-31T23:59:59.999999999Z` reads as its
+  RFC 3339 text, the one SurrealDB gives it (`<string>`): `"0000-06-01T00:00:00Z"`,
+  `"-0001-01-01T00:00:00Z"`, `"+10000-01-01T00:00:00.500Z"` (a sign and at least four digits outside
+  years 0000-9999, every nanosecond kept). An untyped field, `raw_query()` and live notifications
+  give that string; a `datetime` field refuses it with a `ValidationError` naming the field: `get()`
+  raises it, and `filter().exec()` and `raw_query()` return such rows as dicts, as for any row that
+  does not validate. A datetime within years 1-9999, before 1970 included, reads as the SDK's
+  `datetime`, as before.
 
 Written back through the ORM (`merge(v=row.v)`, or `update()`, which rewrites the whole row, the
 untouched fields included), a zero duration stays a duration, but a native set is stored as an
-array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), and
-a degenerate geometry as a plain object (see
-[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)). In an untyped field, `update()`
-flattens the SDK's `Duration(0)` into an object, like any SDK value there
+array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), a
+degenerate geometry as a plain object (see
+[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)), and a datetime outside years
+1-9999 as its text, a string. In an untyped field, `update()` flattens the SDK's `Duration(0)` into
+an object, like any SDK value there
 ([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
 
 The hook is installed only while the installed SDK cannot decode these values, and only on the
 ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`), the embedded
 engine's included (see [Embedded engine and test fixtures](#26-embedded-engine-and-test-fixtures)):
-there a zero duration and a degenerate geometry read as on a server, and `<set>[…]` is stored as an
-array, as on 2.x. An `AsyncSurreal` client the application builds itself keeps the SDK's behaviour
-and fails on them.
+there a zero duration, a degenerate geometry and a datetime outside years 1-9999 read as on a
+server, and `<set>[…]` is stored as an array, as on 2.x. An `AsyncSurreal` client the application
+builds itself keeps the SDK's behaviour and fails on them.
 A later SDK reads zero durations and native sets itself
 ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
 leaves them to it.
@@ -4623,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
@@ -4657,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
 
@@ -4798,7 +4828,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
 listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
 on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
 otherwise. The full suite and every divergence below were re-verified on both new versions.
-Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
+Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
 The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
 
 | ORM capability                                                                                                                         | SurrealDB 2.6.x / 2.7.x                                                                                                                                                       | SurrealDB 3.2.x / 3.3.x                                                                                                                                                             | Since                                |
@@ -4925,6 +4955,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
 | An event whose `THEN` fails (a `THROW`, an error)                                                                                      | the write is refused; the SDK's `InternalError` (`An error occurred: …` for a `THROW`, the bare cause otherwise)                                                              | the write is refused; the SDK's `InternalError` (`Error while processing event <name>: …`)                                                                                          | v0.31.0                              |
 | Event and function definitions read back (`EventState`, `FunctionState`)                                                               | a block on several lines, each statement ending with `;`; `option<T>` parameters as written                                                                                   | a block on one line, no `;` after a single statement; optional parameters rendered with `none` first                                                                                | v0.31.0                              |
 | `define_function()`, `remove_function()` and `call_function()`                                                                         | same on both lines: the next `call_function()` sees a redefinition on every connection of this process to the same namespace and database, whatever its URL                   | the same                                                                                                                                                                            | v0.31.0                              |
+| Reading a datetime before year 1 or after year 9999 (SurrealDB stores years -262143 to +262142)                                        | its RFC 3339 text, as `<string>` gives it (`"+10000-01-01T00:00:00Z"`): an untyped field holds it, a `datetime` field refuses it (`ValidationError`)                          | same on both lines                                                                                                                                                                  | v0.31.1                              |
 | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0                                                     | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips)                                                                                                                   | 3.3.0 identical to 3.2.4, except the system-user signin row                                                                                                                         | v0.19.1                              |
 
 > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -4953,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.0 → surreal_orm_lite-0.31.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.31.0"
+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.0 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/__init__.py

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

{surreal_orm_lite-0.31.0 → surreal_orm_lite-0.31.2}/src/surreal_orm_lite/_sdk.py

@@ -30,12 +30,16 @@ then that module.
 
 v0.27.0 adds ``ThrownError`` (a top-level export of SDK 2.0.0): SurrealDB 3.1 reports a table that does not
 exist, read by a ``LET`` inside a block, as a ``ThrownError`` instead of a ``NotFoundError``.
+
+#279 adds ``TAG_DATETIME_COMPACT`` (a top-level export of SDK 2.0.0, like ``TAG_DURATION_COMPACT``): the read
+hook reads a datetime outside years 1-9999, which the SDK's ``tag_decoder`` refuses.
 """
 
 import importlib
 from typing import TYPE_CHECKING, Any, Final
 
 from surrealdb import (  # noqa: F401
+    TAG_DATETIME_COMPACT,
     TAG_DECIMAL_STRING,
     TAG_DURATION_COMPACT,
     AlreadyExistsError,
@@ -157,8 +161,9 @@ __all__ = [
     "cbor_encode",
     "cbor_decode",
     "SdkInvalidDurationError",
-    # Read hook (#235)
+    # Read hook (#235); a datetime outside years 1-9999 (#279)
     "cbor_tag_decoder",
+    "TAG_DATETIME_COMPACT",
     "SdkAsyncWsConnection",
     "SdkAsyncHttpConnection",
     "SdkAsyncEmbeddedConnection",

{surreal_orm_lite-0.31.0 → 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.0 → 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(