surreal-orm-lite 0.30.0__tar.gz → 0.30.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/CHANGELOG.md +51 -0
  2. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/PKG-INFO +24 -2
  3. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/README.md +23 -1
  4. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/connection_manager.py +10 -0
  7. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/query_set.py +21 -4
  8. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/transaction.py +82 -12
  9. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/.gitignore +0 -0
  10. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/LICENSE +0 -0
  11. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/Makefile +0 -0
  12. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/_sdk.py +0 -0
  13. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/aggregations.py +0 -0
  14. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/auth.py +0 -0
  15. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/cache.py +0 -0
  16. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/changefeed.py +0 -0
  17. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/concurrency.py +0 -0
  18. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/connection_config.py +0 -0
  19. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/constants.py +0 -0
  20. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/decoding.py +0 -0
  21. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/define_parser.py +0 -0
  22. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/edge.py +0 -0
  23. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/embedded.py +0 -0
  24. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/encoding.py +0 -0
  25. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/enum.py +0 -0
  26. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/exceptions.py +0 -0
  27. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/functions.py +0 -0
  28. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/geo.py +0 -0
  29. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/introspection.py +0 -0
  30. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/live.py +0 -0
  31. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/model_auth.py +0 -0
  32. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/model_base.py +0 -0
  33. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/model_generator.py +0 -0
  34. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/py.typed +0 -0
  35. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/q.py +0 -0
  36. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/routing.py +0 -0
  37. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/schema_state.py +0 -0
  38. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/signals.py +0 -0
  39. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/subquery.py +0 -0
  40. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/surql_literal.py +0 -0
  41. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/testing/__init__.py +0 -0
  42. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/testing/database.py +0 -0
  43. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  44. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/time_travel.py +0 -0
  45. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/types.py +0 -0
  46. {surreal_orm_lite-0.30.0 → surreal_orm_lite-0.30.3}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.30.3] - 2026-10-19
9
+
10
+ A statement that fails inside `transaction()` fails the whole transaction on every strategy: a
11
+ transaction block now behaves the same on SurrealDB 2.x and 3.x, over WebSocket, over HTTP and on
12
+ the embedded engine. No new public API.
13
+
14
+ ### Changed
15
+
16
+ - **A failed statement fails the whole `transaction()` block, on every strategy** (#268). After a
17
+ statement fails inside the block, even when the block catches its error and carries on, the
18
+ transaction is cancelled when the block ends, nothing of the block is committed, and leaving the
19
+ block raises `SurrealDbError`, or `SurrealDbConflictError` when the failure was a retryable
20
+ conflict, so `retry_on_conflict` retries the block. Interactive transactions (SurrealDB 3.x over
21
+ WebSocket) now behave like the buffered ones (SurrealDB 2.x, HTTP, the embedded engine), which
22
+ already failed as a whole at commit: the failed statement raises its error at once, then leaving
23
+ the block raises "The transaction was cancelled: a statement in it failed; nothing was committed
24
+ (…)", chained to that error.
25
+ - An explicit `tx.commit()` after a failed statement raises the same error and cancels the
26
+ transaction.
27
+ - When the block's own exception propagates, that exception is the one raised, as before.
28
+ - Reads the ORM answers itself do not fail the transaction: a table that does not exist reads as
29
+ no rows, and `get()` raises `SurrealDbNotFoundError`.
30
+ - A statement interrupted inside the block (a timeout or a task cancellation) fails the
31
+ transaction too.
32
+
33
+ Upgrade note: a block that catches a statement's error and carries on now raises when it ends,
34
+ on every strategy, as it already did on the buffered ones. To carry on after such an error, run
35
+ that statement in a transaction of its own or outside the transaction.
36
+
37
+ ```python
38
+ async with SurrealDBConnectionManager.transaction() as tx:
39
+ await User(id="alice", name="Alice").save(tx=tx)
40
+ try:
41
+ await Order(id="o2", user="User:alice", total=-1).save(tx=tx) # refused by a field ASSERT
42
+ except SurrealDbError:
43
+ pass # caught, but the transaction can no longer commit
44
+ # leaving the block raised SurrealDbError: alice was not saved either
45
+ ```
46
+
47
+ ### Fixed
48
+
49
+ - **The error of a failed statement, "Transaction failed and rolled back: …", now describes what
50
+ happens on every strategy** (#268): on an interactive transaction as on a buffered one, nothing
51
+ of the block is committed.
52
+
53
+ ### Notes
54
+
55
+ - Docs: the README transactions section (11) states the rule with an example, and the "ORM
56
+ behaviour: SurrealDB 2.x vs 3.x" table gains a row for a statement that fails inside
57
+ `transaction()` with its error caught in the block.
58
+
8
59
  ## [0.30.0] - 2026-10-19
9
60
 
10
61
  Schema introspection: the ORM reads the schema of a database as immutable typed objects and
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.30.0
3
+ Version: 0.30.3
4
4
  Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
5
5
  Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
6
6
  Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -725,6 +725,27 @@ async with SurrealDBConnectionManager.transaction() as tx:
725
725
  tx raise; `save(tx=)` requires an explicit `id`. `bulk_update`/`bulk_delete` return `0`
726
726
  (the row count is not knowable before commit).
727
727
 
728
+ **A failed statement fails the whole transaction, on every strategy.** After a statement fails
729
+ inside the block — even when the block catches its error and carries on — the transaction is
730
+ cancelled when the block ends, nothing of the block is committed, and leaving the block raises
731
+ `SurrealDbError` (`SurrealDbConflictError` for a retryable conflict, so `retry_on_conflict` still
732
+ retries the block). A buffered transaction fails as a whole at commit; an interactive one raises
733
+ the failed statement's error at once, then, when the block ends, "The transaction was cancelled: a
734
+ statement in it failed; nothing was committed (…)", chained to that error. An explicit
735
+ `tx.commit()` after a failure raises the same error. When the block's own exception propagates,
736
+ that exception wins, as before. Reads the ORM answers itself are not failed statements: a table
737
+ that does not exist reads as no rows, and `get()` raises `SurrealDbNotFoundError`.
738
+
739
+ ```python
740
+ async with SurrealDBConnectionManager.transaction() as tx:
741
+ await User(id="alice", name="Alice").save(tx=tx)
742
+ try:
743
+ await Order(id="o2", user="User:alice", total=-1).save(tx=tx) # refused by a field ASSERT
744
+ except SurrealDbError:
745
+ pass # caught, but the transaction can no longer commit
746
+ # leaving the block raised SurrealDbError: alice was not saved either
747
+ ```
748
+
728
749
  ### 12. Upsert & get_or_create / update_or_create
729
750
 
730
751
  ```python
@@ -4516,7 +4537,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4516
4537
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4517
4538
  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
4518
4539
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4519
- 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.
4540
+ 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.
4520
4541
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4521
4542
 
4522
4543
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4549,6 +4570,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4549
4570
  | `call_function(tx=)` — return value | `None` (buffered: queued until commit) | the function's value (interactive returns it immediately) | v0.15.0 |
4550
4571
  | `call_function(tx=, return_type=)` | raises `ValueError` (no value to coerce yet) | coerces the returned value | v0.15.0 |
4551
4572
  | Missing function called inside a transaction | surfaces at COMMIT as `SurrealDbError` (buffered: the call is only queued) | raises `SurrealDbNotFoundError` at call time | v0.15.0 |
4573
+ | A statement that fails inside `transaction()`, its error caught in the block | leaving the block raises `SurrealDbError`, nothing of the block committed (the buffered batch fails as a whole) | same on both lines; over WebSocket the statement raises at once, then the block's end cancels the transaction and raises `SurrealDbError` | v0.30.3 |
4552
4574
  | Declared parameter name that collides with a reserved word, as echoed by `INFO FOR DB` | quoted: `` $`by` `` — parser accepts it | bare: `$by` | v0.15.0 |
4553
4575
  | Auth methods (`signin`, `signup`, `authenticate`, `invalidate`, `info`) | same on both lines (native SDK primitives, verified on 2.6.5) | same on both lines (verified on 3.2.4) | v0.16.0 |
4554
4576
  | Auth failure — raw SDK exception for a wrong password | `InternalError` | `NotFoundError` | v0.16.0 |
@@ -674,6 +674,27 @@ async with SurrealDBConnectionManager.transaction() as tx:
674
674
  tx raise; `save(tx=)` requires an explicit `id`. `bulk_update`/`bulk_delete` return `0`
675
675
  (the row count is not knowable before commit).
676
676
 
677
+ **A failed statement fails the whole transaction, on every strategy.** After a statement fails
678
+ inside the block — even when the block catches its error and carries on — the transaction is
679
+ cancelled when the block ends, nothing of the block is committed, and leaving the block raises
680
+ `SurrealDbError` (`SurrealDbConflictError` for a retryable conflict, so `retry_on_conflict` still
681
+ retries the block). A buffered transaction fails as a whole at commit; an interactive one raises
682
+ the failed statement's error at once, then, when the block ends, "The transaction was cancelled: a
683
+ statement in it failed; nothing was committed (…)", chained to that error. An explicit
684
+ `tx.commit()` after a failure raises the same error. When the block's own exception propagates,
685
+ that exception wins, as before. Reads the ORM answers itself are not failed statements: a table
686
+ that does not exist reads as no rows, and `get()` raises `SurrealDbNotFoundError`.
687
+
688
+ ```python
689
+ async with SurrealDBConnectionManager.transaction() as tx:
690
+ await User(id="alice", name="Alice").save(tx=tx)
691
+ try:
692
+ await Order(id="o2", user="User:alice", total=-1).save(tx=tx) # refused by a field ASSERT
693
+ except SurrealDbError:
694
+ pass # caught, but the transaction can no longer commit
695
+ # leaving the block raised SurrealDbError: alice was not saved either
696
+ ```
697
+
677
698
  ### 12. Upsert & get_or_create / update_or_create
678
699
 
679
700
  ```python
@@ -4465,7 +4486,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4465
4486
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4466
4487
  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
4467
4488
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4468
- 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.
4489
+ 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.
4469
4490
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4470
4491
 
4471
4492
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4498,6 +4519,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4498
4519
  | `call_function(tx=)` — return value | `None` (buffered: queued until commit) | the function's value (interactive returns it immediately) | v0.15.0 |
4499
4520
  | `call_function(tx=, return_type=)` | raises `ValueError` (no value to coerce yet) | coerces the returned value | v0.15.0 |
4500
4521
  | Missing function called inside a transaction | surfaces at COMMIT as `SurrealDbError` (buffered: the call is only queued) | raises `SurrealDbNotFoundError` at call time | v0.15.0 |
4522
+ | A statement that fails inside `transaction()`, its error caught in the block | leaving the block raises `SurrealDbError`, nothing of the block committed (the buffered batch fails as a whole) | same on both lines; over WebSocket the statement raises at once, then the block's end cancels the transaction and raises `SurrealDbError` | v0.30.3 |
4501
4523
  | Declared parameter name that collides with a reserved word, as echoed by `INFO FOR DB` | quoted: `` $`by` `` — parser accepts it | bare: `$by` | v0.15.0 |
4502
4524
  | Auth methods (`signin`, `signup`, `authenticate`, `invalidate`, `info`) | same on both lines (native SDK primitives, verified on 2.6.5) | same on both lines (verified on 3.2.4) | v0.16.0 |
4503
4525
  | Auth failure — raw SDK exception for a wrong password | `InternalError` | `NotFoundError` | v0.16.0 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.30.0"
3
+ version = "0.30.3"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.30.0"
1
+ __version__ = "0.30.3"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -1627,6 +1627,16 @@ class SurrealDBConnectionManager:
1627
1627
  ``commit()`` BEFORE deferred ``post_*`` signals fire. An exception from a deferred
1628
1628
  handler surfaces AFTER a durable commit (not a rollback).
1629
1629
 
1630
+ A failed statement fails the transaction on every strategy (issue #268): after a statement
1631
+ fails inside the block — even when the block catches its error and carries on — the
1632
+ transaction is cancelled when the block ends, nothing is committed, and leaving the block
1633
+ raises ``SurrealDbError`` (``SurrealDbConflictError`` for a retryable conflict, so
1634
+ ``retry_on_conflict`` still retries). A buffered batch fails as a whole at commit; an
1635
+ interactive transaction raises "The transaction was cancelled: a statement in it failed;
1636
+ nothing was committed (…)", chained to the failed statement's error. When the body's own
1637
+ exception propagates, that exception wins. A read the ORM answers itself (a missing table
1638
+ read as no rows, ``get()`` raising ``SurrealDbNotFoundError``) is not a failed statement.
1639
+
1630
1640
  SurrealDB has no savepoints/nested transactions; nested ``transaction()`` calls
1631
1641
  open INDEPENDENT transactions, not savepoints.
1632
1642
 
@@ -1114,7 +1114,15 @@ class QuerySet:
1114
1114
  try:
1115
1115
  return await self._tx.run_read(query, vars_) # type: ignore[no-any-return]
1116
1116
  except ServerError as exc:
1117
- if await self._reads_as_empty(exc, subquery_tables):
1117
+ # A read the ORM answers itself (no rows, or sent again without the missing subquery table) does not
1118
+ # fail the transaction (issue #268); an error relayed does.
1119
+ try:
1120
+ empty = await self._reads_as_empty(exc, subquery_tables)
1121
+ except _subquery._MissingSubqueryTable:
1122
+ self._tx._absorb_failure(exc)
1123
+ raise
1124
+ if empty:
1125
+ self._tx._absorb_failure(exc)
1118
1126
  return []
1119
1127
  raise
1120
1128
  client = await self._manager().get_client()
@@ -1174,8 +1182,13 @@ class QuerySet:
1174
1182
  client = await self._manager().get_client()
1175
1183
  await client.query(_subquery.TABLE_PROBE, _encoding.encode(variables))
1176
1184
  except NotFoundError as exc:
1185
+ # The check's answer, never a failed statement of the transaction (issue #268).
1186
+ if self._tx is not None:
1187
+ self._tx._absorb_failure(exc)
1177
1188
  return _subquery.missing_table(exc) == table
1178
- except ServerError:
1189
+ except ServerError as exc:
1190
+ if self._tx is not None:
1191
+ self._tx._absorb_failure(exc)
1179
1192
  return False
1180
1193
  return False
1181
1194
 
@@ -1431,7 +1444,9 @@ class QuerySet:
1431
1444
  if self._tx is not None:
1432
1445
  try:
1433
1446
  rows = await self._tx.run_read("SELECT * FROM $rid;", {"rid": record_id})
1434
- except NotFoundError:
1447
+ except NotFoundError as exc:
1448
+ # "No record" is an answer, not a failed statement of the transaction (issue #268).
1449
+ self._tx._absorb_failure(exc)
1435
1450
  raise SurrealDbNotFoundError("No result found.") from None
1436
1451
  data = rows[0] if isinstance(rows, list) and rows else rows
1437
1452
  if not data:
@@ -1481,7 +1496,9 @@ class QuerySet:
1481
1496
  if self._tx is not None:
1482
1497
  try:
1483
1498
  rows = await self._tx.run_read(f"SELECT * FROM {self._model_table};", {})
1484
- except NotFoundError:
1499
+ except NotFoundError as exc:
1500
+ # A missing table reads as no rows: not a failed statement of the transaction (issue #268).
1501
+ self._tx._absorb_failure(exc)
1485
1502
  return self.model.from_db([])
1486
1503
  return self.model.from_db(rows if isinstance(rows, list) else [])
1487
1504
 
@@ -14,6 +14,12 @@ Two strategies share one public interface:
14
14
 
15
15
  ``connection_manager.transaction()`` probes ``client.begin()`` to pick the strategy.
16
16
 
17
+ A failed statement fails the transaction on both strategies (issue #268). A buffered batch fails as a whole at
18
+ commit. The interactive strategy records every statement that fails (a write or a read whose error the ORM does not
19
+ answer itself, e.g. a missing table read as no rows); ``commit()`` then cancels instead of committing and raises,
20
+ so leaving a ``transaction()`` block after a failed statement raises and nothing of the block is committed, even
21
+ when the block caught the statement's error.
22
+
17
23
  Query cache (v0.28.0): an ORM write that joins a transaction notes the tables it writes on it
18
24
  (``_note_cache_write``); the commit puts them in flight and invalidates their cached reads when
19
25
  it returns or raises (a failed commit's state is unknown). ``cancel()`` forgets them: nothing
@@ -32,6 +38,10 @@ from .exceptions import SurrealDbConflictError, SurrealDbError
32
38
 
33
39
  _NOT_EXECUTED_FILLER = "The query was not executed due to a failed transaction"
34
40
 
41
+ #: The error ``InteractiveTransaction.commit()`` raises after a failed statement (issue #268), followed by that
42
+ #: statement's error.
43
+ _CANCELLED_AFTER_FAILURE = "The transaction was cancelled: a statement in it failed; nothing was committed"
44
+
35
45
 
36
46
  def _is_pure_filler(result: Any) -> bool:
37
47
  """True if a statement's message is ONLY the generic 'not executed' filler.
@@ -75,6 +85,25 @@ class Transaction(ABC):
75
85
  # Query cache: the tables written in this transaction, invalidated at commit.
76
86
  self._cache_tables: set[str] = set()
77
87
  self._cache_all = False
88
+ # Issue #268: the errors of the statements that failed in this transaction (interactive strategy).
89
+ self._failures: list[BaseException] = []
90
+
91
+ def _note_failure(self, error: BaseException) -> None:
92
+ """Record that a statement run in this transaction failed with *error*: the transaction can no longer commit."""
93
+ self._failures.append(error)
94
+
95
+ def _absorb_failure(self, error: BaseException) -> None:
96
+ """Forget the failure *error*, which the ORM answered itself (issue #268).
97
+
98
+ A read the ORM reads as an answer — a missing table read as no rows, ``get()`` raising "not found", the
99
+ missing-table check of a subquery — does not fail the transaction. Matched by identity; an error that was
100
+ not recorded is ignored.
101
+ """
102
+ self._failures = [failure for failure in self._failures if failure is not error]
103
+
104
+ def _first_failure(self) -> BaseException | None:
105
+ """The error of the first statement that failed in this transaction and was not absorbed, else ``None``."""
106
+ return self._failures[0] if self._failures else None
78
107
 
79
108
  def _note_cache_write(self, tables: Iterable[str] | None) -> None:
80
109
  """Note the tables an ORM write in this transaction changes (``None``: every table).
@@ -139,8 +168,10 @@ class Transaction(ABC):
139
168
 
140
169
  ``query()`` silently returns ``None`` on a failed transaction, so the
141
170
  commit/write paths use ``query_raw()`` and call this. Any statement with
142
- ``status == "ERR"`` means the transaction rolled back. Prefers the root cause
143
- (the first ERR whose ``details.kind`` is not ``"NotExecuted"``).
171
+ ``status == "ERR"`` means the transaction is rolled back: a buffered batch at once, an
172
+ interactive transaction when it ends (its ``commit()`` cancels after a failed statement,
173
+ issue #268). Prefers the root cause (the first ERR whose ``details.kind`` is not
174
+ ``"NotExecuted"``).
144
175
  """
145
176
  if not isinstance(raw, dict) or not isinstance(raw.get("result"), list):
146
177
  raise SurrealDbError(f"Transaction failed: unrecognized query_raw() response shape: {raw!r}")
@@ -255,37 +286,72 @@ class InteractiveTransaction(Transaction):
255
286
  (done by the connection manager). Every operation passes ``txn_id=`` so it joins the
256
287
  server-side transaction; reads see uncommitted writes and are isolated from other
257
288
  operations on the same connection.
289
+
290
+ A statement that fails — its request raises, or the server reports an error — is recorded
291
+ (issue #268); its error still raises at once. ``commit()`` then cancels the transaction
292
+ instead of committing it and raises :data:`_CANCELLED_AFTER_FAILURE`, so the transaction fails
293
+ as a whole, as a buffered one does, even when the caller caught the statement's error.
258
294
  """
259
295
 
260
296
  def __init__(self, client: Any, txn_id: Any) -> None:
261
297
  super().__init__()
262
298
  self._client = client
263
299
  self._txn_id = txn_id
300
+ self._cancelled = False
264
301
 
265
302
  @property
266
303
  def is_interactive(self) -> bool:
267
304
  return True
268
305
 
269
306
  async def add(self, statement: str, variables: dict[str, Any] | None = None) -> Any:
270
- """Run a write inside the transaction; inspect status; return its rows."""
307
+ """Run a write inside the transaction; inspect status; return its rows.
308
+
309
+ A failure is recorded before it raises: the transaction will not commit (issue #268).
310
+ """
271
311
  payload = _encoding.encode(variables or {})
272
312
  try:
273
- raw = await self._client.query_raw(statement, payload, txn_id=self._txn_id)
274
- except Exception as exc:
275
- raise _as_conflict(exc) from exc
276
- self.raise_for_status(raw)
313
+ try:
314
+ raw = await self._client.query_raw(statement, payload, txn_id=self._txn_id)
315
+ except Exception as exc:
316
+ raise _as_conflict(exc) from exc
317
+ self.raise_for_status(raw)
318
+ except BaseException as failure:
319
+ self._note_failure(failure)
320
+ raise
277
321
  statements = raw["result"]
278
322
  return statements[-1]["result"] if statements else []
279
323
 
280
324
  async def run_read(self, statement: str, variables: dict[str, Any] | None = None) -> Any:
281
- """Run a read inside the transaction and return rows directly."""
325
+ """Run a read inside the transaction and return rows directly.
326
+
327
+ A failure is recorded before it raises (issue #268); the ORM forgets it when it reads the
328
+ error as an answer (:meth:`_absorb_failure`).
329
+ """
282
330
  payload = _encoding.encode(variables or {})
283
331
  try:
284
- return await self._client.query(statement, payload, txn_id=self._txn_id)
285
- except Exception as exc:
286
- raise _as_conflict(exc) from exc
332
+ try:
333
+ return await self._client.query(statement, payload, txn_id=self._txn_id)
334
+ except Exception as exc:
335
+ raise _as_conflict(exc) from exc
336
+ except BaseException as failure:
337
+ self._note_failure(failure)
338
+ raise
287
339
 
288
340
  async def commit(self) -> None:
341
+ """Commit the transaction; after a failed statement, cancel it and raise instead (issue #268).
342
+
343
+ Raises:
344
+ SurrealDbError: a statement failed in this transaction (:data:`_CANCELLED_AFTER_FAILURE`, followed by that
345
+ statement's error, which is chained as the cause): the transaction was cancelled, nothing was
346
+ committed. ``SurrealDbConflictError`` when that statement's error was a retryable conflict.
347
+ """
348
+ failure = self._first_failure()
349
+ if failure is not None:
350
+ from .concurrency import is_conflict_error
351
+
352
+ await self.cancel()
353
+ error_type = SurrealDbConflictError if is_conflict_error(failure) else SurrealDbError
354
+ raise error_type(f"{_CANCELLED_AFTER_FAILURE} ({str(failure) or type(failure).__name__})") from failure
289
355
  # The tables noted are in flight during the commit and invalidated when it returns
290
356
  # or raises (a failed commit's state is unknown).
291
357
  try:
@@ -298,7 +364,11 @@ class InteractiveTransaction(Transaction):
298
364
  self._forget_cache_writes()
299
365
 
300
366
  async def cancel(self) -> None:
301
- # Nothing became visible: the tables noted are forgotten, not invalidated.
367
+ # Nothing became visible: the tables noted are forgotten, not invalidated. Sent once: a
368
+ # commit() that cancelled after a failed statement is cancelled again by transaction().
302
369
  self._forget_cache_writes()
370
+ if self._cancelled:
371
+ return
372
+ self._cancelled = True
303
373
  with contextlib.suppress(Exception):
304
374
  await self._client.cancel(self._txn_id)