surreal-orm-lite 0.30.3__tar.gz → 0.30.7__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.3 → surreal_orm_lite-0.30.7}/CHANGELOG.md +121 -0
  2. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/PKG-INFO +71 -32
  3. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/README.md +70 -31
  4. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/connection_manager.py +43 -2
  7. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/edge.py +6 -4
  8. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/model_base.py +170 -138
  9. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/model_generator.py +54 -50
  10. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/transaction.py +11 -4
  11. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/utils.py +142 -2
  12. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/.gitignore +0 -0
  13. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/LICENSE +0 -0
  14. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/Makefile +0 -0
  15. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/cache.py +0 -0
  19. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/changefeed.py +0 -0
  20. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/concurrency.py +0 -0
  21. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/connection_config.py +0 -0
  22. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/define_parser.py +0 -0
  25. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/embedded.py +0 -0
  26. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/encoding.py +0 -0
  27. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/enum.py +0 -0
  28. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/exceptions.py +0 -0
  29. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/functions.py +0 -0
  30. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/geo.py +0 -0
  31. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/introspection.py +0 -0
  32. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/model_auth.py +0 -0
  34. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/py.typed +0 -0
  35. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/q.py +0 -0
  36. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/query_set.py +0 -0
  37. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/routing.py +0 -0
  38. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/schema_state.py +0 -0
  39. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/signals.py +0 -0
  40. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/subquery.py +0 -0
  41. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/surql_literal.py +0 -0
  42. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/testing/__init__.py +0 -0
  43. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/testing/database.py +0 -0
  44. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  45. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/time_travel.py +0 -0
  46. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,127 @@ 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.7] - 2026-10-19
9
+
10
+ An instance stays in step with its stored row (#261): `save()` applies the whole row the server
11
+ returns, every call that applies a returned row validates it as a read does, and `update()` keeps
12
+ the stored nanoseconds of a datetime it did not change, so a record with a top-level `READONLY`
13
+ datetime can be updated. No new public API, but what an instance holds after a write changes for
14
+ every model: read **Changed** before upgrading.
15
+
16
+ ### Fixed
17
+
18
+ - **`update()` after `save()` or `get()` on a `READONLY` top-level `datetime`** is no longer
19
+ refused by the server (#261). SurrealDB stores nanoseconds and the SDK reads microseconds, so
20
+ `update()` wrote back a changed value. See item 5 under Changed.
21
+ - **Sub-fields a `DEFAULT` fills** (`prefs.at DEFAULT time::now()`) are on the instance right after
22
+ `save()` (explicit id, auto id, interactive transaction), so a following `update()` no longer
23
+ sends them as `NONE`, which the server refused for a required sub-field and which erased an
24
+ optional one (#261).
25
+ - **`tuple` and `set` fields** hold their declared type after `save()`, `upsert()`, `merge()` and
26
+ `patch()`, as after `get()` (item 2 under Changed), not the SDK's `list` (#261).
27
+ - **A returned column named like a Pydantic `@computed_field` or a model method** (`json`) no
28
+ longer replaces that attribute (#261). In 0.30.1, with a `@computed_field` (which `model_dump()`
29
+ writes), auto-id `save()`, `refresh()` and `merge()` raised `AttributeError` after the record was
30
+ stored.
31
+ - **`generate_models_from_db()`**: generated classes no longer carry the note about `DEFAULT`
32
+ sub-fields, and the `READONLY` `update()` note remains only for a datetime below the top level
33
+ or a top-level one past the 32nd (#261).
34
+ - **Buffered transactions**: a statement's parameters are renamed in one pass (#261). In 0.30.1,
35
+ `$a` next to a variable named `t0_a` was renamed twice and bound to `t0_a`'s value, and a
36
+ statement with thousands of bound values was slow to queue.
37
+
38
+ ```python
39
+ # DEFINE FIELD created ON event TYPE datetime DEFAULT time::now() READONLY;
40
+ event = await Event.objects().get("launch") # created read to the microsecond
41
+ event.title = "Launch day"
42
+ await event.update() # was refused ("readonly"); the stored created keeps its nanoseconds
43
+ ```
44
+
45
+ ### Changed
46
+
47
+ Each item was measured against 0.30.1 on SurrealDB 3.3.4, 2.7.0 and the embedded engine
48
+ (`mem://`) and holds on all three unless stated.
49
+
50
+ 1. **Explicit-id `save()`, an edge's `save()` and interactive `save(tx=)` apply the whole stored
51
+ row** (#261). In 0.30.1, explicit-id `save()` and interactive `save(tx=)` read back only the
52
+ `server_fields` and computed fields, and an edge's `save()` (either id) only its `id` and
53
+ `server_fields`: the instance kept the values passed in. Now a naive `datetime` becomes the
54
+ aware UTC `datetime` a read gives (compare it with aware values), a sub-model field holds a new
55
+ instance (not the object passed in), and values a `VALUE` clause rewrote or the server coerced
56
+ replace the ones sent (`VALUE string::lowercase($value)` turns `"AbC"` into `"abc"` on the
57
+ instance). Interactive transactions exist on SurrealDB 3.x over WebSocket only; a buffered
58
+ transaction (HTTP, 2.x, the embedded engine) still leaves the instance as it was.
59
+ 2. **Every call that applies the returned row validates it like a read** (#261): `save()` with
60
+ either id, an edge's `save()`, `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
61
+ `patch()` and the `atomic_*` helpers. An enum field holds the enum member, not the raw
62
+ `str`/`int` (a `str` or `int` enum still compares equal to its value, a plain `Enum` member no
63
+ longer does); `tuple`, `set`, `date` and `Range` fields hold their declared type instead of the
64
+ SDK's `list`, midnight `datetime` and `Range`; a `float` field stored in a `decimal` column holds
65
+ a `float`, not a `Decimal`; a `list[Duration]` holds the ORM's `Duration`s, not the SDK's. In
66
+ 0.30.1, `refresh()`, `merge()`, auto-id `save()`, `upsert()`, `patch()` and `atomic_*` kept the
67
+ SDK's values for these fields (explicit-id `save()` kept the values passed in).
68
+ 3. **The model's validators run on the returned row for every model** (#261). Field and model
69
+ validators (any mode) and `model_post_init` run once per call listed in item 2, on a validated
70
+ copy of the row, and their result is applied to every field. In 0.30.1 they ran only when the
71
+ row held a sub-model field, a nested `timedelta` field or a geometry field stored as a GeoJSON
72
+ object, and their result reached only those fields; otherwise they did not run at all. A
73
+ validator that is not idempotent is applied again, as on `get()`, and a following `update()`
74
+ writes that value back: with `label` validated as `v + "!"`, `Model(id="a", label="x")`,
75
+ `save()` then `update()` stored `x!` in 0.30.1 and stores `x!!` now; `merge()` then `update()`
76
+ gives the same difference.
77
+ 4. **Under `extra="allow"`, the returned row's undeclared columns go to `model_extra`** after the
78
+ calls listed in item 2, where a read puts them (0.30.1 dropped them), and `merge(refresh=False)`
79
+ with an undeclared key updates `model_extra` (#261).
80
+ 5. **`update()` and `upsert()` keep the stored nanoseconds of a datetime written back unchanged**
81
+ (one that still floors to the stored value at the microsecond), for every top-level datetime up
82
+ to 32 per record, so a record whose `READONLY` datetimes are top-level fields can be updated
83
+ after `get()` or `save()` (#261). Below the top level (a sub-model, a `list`, a `tuple`, a set)
84
+ this depends on the data: change such a record with `merge()`.
85
+
86
+ ### Notes
87
+
88
+ - SurrealDB 2.x still refuses `update()` and `upsert()` of an existing record that has a field
89
+ with a non-optional `TYPE` and a `VALUE` clause the model does not write, such as a generated
90
+ `updated: Computed[datetime]` (#267): change such a record with `merge()` there. 0.30.1 behaved
91
+ the same way before this release; SurrealDB 3.x recomputes the field. The v0.30.0 example
92
+ notebook changes its generated `NbPerson` with `merge()` for that reason.
93
+ - The README's "After a write that returns the row", "Precision and `Decimal`" and "What the
94
+ generator does not do" sections, and a new row of the 2.x vs 3.x behaviour table, describe these
95
+ changes.
96
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus
97
+ 3.1.5 for backward compatibility.
98
+
99
+ ## [0.30.5] - 2026-10-19
100
+
101
+ `SurrealDBConnectionManager.kill()` no longer reports a connection lost under the request as a
102
+ KILL the server refused. No new public API.
103
+
104
+ ### Fixed
105
+
106
+ - **A `kill()` caught by a dropped connection returns normally** (#266). A KILL sent as the
107
+ WebSocket went down, before the SDK had noticed the drop, failed inside the SDK (its receive loop
108
+ clears the pending requests, so the request's own cleanup raised a `KeyError`), and `kill()`
109
+ turned that into `SurrealDbError: Failed to kill live query …` although the server never
110
+ answered. `kill()` now asks the client: when its connection dropped under the request (the SDK's
111
+ receive task has ended, after a wait of at most one second when the error came from the
112
+ transport), it closes the dead socket and records the live query as ended, as it already did for
113
+ a client found dead before the call, and the stream's readers end. A refusal from a live server
114
+ still raises `SurrealDbError` and keeps the uuid alive, so a retry can re-attach to it.
115
+ - **A cancelled `kill()` raises `asyncio.CancelledError`** (#266), even when the SDK reports the
116
+ cancelled request as an ordinary error; it used to become `SurrealDbError`. The readers are
117
+ released either way.
118
+ - **`kill()` releases the stream's readers before it closes a dead socket** (#266), so an
119
+ automatic resubscribe woken by the same drop cannot reopen a subscription that is being stopped.
120
+ The window was open where closing the socket yields to the event loop, as on Python 3.11.
121
+
122
+ ### Notes
123
+
124
+ - Docs: the README live-queries section says that a kill caught by a dropped connection is not a
125
+ refusal.
126
+ - Same behaviour on SurrealDB 2.x and 3.x (live queries are WebSocket-only). Server pins
127
+ unchanged: tested against SurrealDB 3.3.4 and 2.7.0, plus 3.1.5 for backward compatibility.
128
+
8
129
  ## [0.30.3] - 2026-10-19
9
130
 
10
131
  A statement that fails inside `transaction()` fails the whole transaction on every strategy: a
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.30.3
3
+ Version: 0.30.7
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
@@ -1763,6 +1763,8 @@ exactly what ends a stream.
1763
1763
  - **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
1764
1764
  the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
1765
1765
  and the subscription is still running — so you can subscribe to it again or retry `stop()`.
1766
+ A kill caught by a dropped connection is not a refusal: the subscription died with the socket,
1767
+ so `kill()` records it as ended and returns normally.
1766
1768
  - **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
1767
1769
  notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
1768
1770
 
@@ -2245,8 +2247,12 @@ reads, a `timedelta` is converted from the SDK's duration at any depth too: a to
2245
2247
  `list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
2246
2248
  all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
2247
2249
  Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
2248
- change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
2249
- `datetime`, as before.
2250
+ change it in place. A naive `datetime` is written as UTC and read back as an aware UTC `datetime`.
2251
+ The instance keeps it naive until a call applies the row the server returns (see
2252
+ [After a write that returns the row](#after-a-write-that-returns-the-row)): after `save()` (since
2253
+ #261 with an explicit id too), `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
2254
+ `patch()` or an `atomic_*` helper, the field holds that aware UTC `datetime`, so compare it with
2255
+ aware values. `update()`, and `save(tx=)` in a buffered transaction, leave it naive.
2250
2256
 
2251
2257
  #### `Duration`
2252
2258
 
@@ -2369,7 +2375,23 @@ both lines.
2369
2375
  #### Precision and `Decimal`
2370
2376
 
2371
2377
  - `datetime`: to the microsecond. The SDK truncates the server's nanoseconds, so a stored
2372
- `d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`.
2378
+ `d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`. `update()` and `upsert()` rewrite the
2379
+ whole record, but a `datetime` you did not change (it still floors to the stored value) keeps
2380
+ the stored nanoseconds, on both lines and the embedded engine: a record whose `READONLY`
2381
+ datetimes are top-level fields can be updated after `get()` or `save()`, even when they hold
2382
+ nanoseconds ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). A
2383
+ datetime you changed is written as you set it, and a `READONLY` field still refuses it. So that
2384
+ the statement stays small whatever the data, only the top-level datetimes are sure to be kept,
2385
+ up to 32 per record. Below the top level (in a sub-model, a `list` or a `tuple`, down to three
2386
+ levels) a datetime is kept only while the values rebuilt to reach it fit in what the fields
2387
+ before it left of those 32, so it depends on the data: an `update()` that passes in a test can
2388
+ fail once a list of timestamped items before the sub-model grows. A datetime not kept, and one
2389
+ in a set (its items have no position to match a stored value by), is written as sent: a
2390
+ `READONLY` field holding one may refuse `update()`, so change such a record with `merge()`.
2391
+ SurrealDB 2.x also refuses, for now, `update()` and `upsert()` of an existing record that has
2392
+ a field with a non-optional `TYPE` and a `VALUE` clause the model does not write (a `Computed`
2393
+ field, such as a generated `updated: Computed[datetime]`): change it with `merge()` there
2394
+ ([#267](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/267)).
2373
2395
  - `timedelta`: floored to the microsecond on read (`1h30m1ns` reads `timedelta(seconds=5400)`).
2374
2396
  - `Duration`: exact, to the nanosecond.
2375
2397
  - `Decimal`: a value whose `str()` writes no exponent is sent as before. A value written with an
@@ -2432,22 +2454,40 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2432
2454
 
2433
2455
  #### After a write that returns the row
2434
2456
 
2435
- `save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
2436
- apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2437
- fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2438
- that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2439
- `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2440
- `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2441
- model's own validators included, and a sub-model field holds its model instance, not the row's
2442
- `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2443
- whole does not validate, each such field is validated on its own, except one that the model's own
2444
- validators could reshape (a `field_validator` on that field, a `model_validator`, a
2445
- `model_post_init`): that one, like a value that does not validate, is applied as received, so
2446
- these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2447
- (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2448
- `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2449
- stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2450
- top-level `date` and `set` fields while serialising them.
2457
+ `save()` (with or without an id, an edge's too), `refresh()`, `merge()`, `upsert()`, `patch()` and
2458
+ the `atomic_*` helpers apply the row the server returns to the instance. After `save()` the
2459
+ instance therefore holds what the record holds: the `server_fields` and computed fields, the
2460
+ sub-fields a `DEFAULT` filled (`prefs.at DEFAULT time::now()`), and the values the server coerced
2461
+ or rewrote (`VALUE string::lowercase($value)`), so a following `update()` writes them back
2462
+ unchanged ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). An id you
2463
+ gave stays as you gave it; an auto id is the server's `RecordID`. A buffered transaction (HTTP,
2464
+ SurrealDB 2.x, the embedded engine) returns no row before commit: there `save(tx=)` leaves the
2465
+ instance as it was, and `refresh()` after the commit reads the row.
2466
+
2467
+ The top-level `timedelta`, `Duration` and geometry fields (since v0.24.0, see
2468
+ [section 25](#25-geospatial-fields)) are converted on the way, and every other field gets the
2469
+ value a read gives (#261; before, only a field holding a sub-model, a geometry or a nested
2470
+ `timedelta` did): the row goes through the model's validation, the model's own validators
2471
+ included. A sub-model field holds its model instance, not the row's `dict`, with the ORM's
2472
+ durations, `timedelta`s, ranges and geometries inside; an enum field holds the enum, not its `str`
2473
+ or `int`; a `tuple`, set, `date` or `Range` field holds its declared type, not the SDK's `list`,
2474
+ midnight `datetime` or `Range`; a `float` field stored in a `decimal` column holds a `float`, not a
2475
+ `Decimal`; a `list[Duration]` holds the ORM's durations. When the row as a whole does not validate,
2476
+ each field is validated on its own, except one that the model's own validators could reshape (a
2477
+ `field_validator` on that field, a `model_validator`, a `model_post_init`): that one, like a value
2478
+ that does not validate, is applied as received, so these calls never fail on it. The `id` keeps
2479
+ the server's `RecordID`. A column the model does not declare goes where a read puts it: as the SDK
2480
+ reads it into `model_extra` under `extra="allow"`, nowhere otherwise. So a column holding a Pydantic
2481
+ `@computed_field` (`model_dump()` writes it) or named like a method (`json`) never replaces that
2482
+ attribute.
2483
+
2484
+ Writing such an instance back is safe, sub-models included: a following `update()` replaces the
2485
+ record with these values, as after `get()`. So a `float` field stored in a `decimal` column writes
2486
+ the float's rounding (`0.12345678901234567890` becomes `0.1234567890123457`: declare `Decimal` to
2487
+ keep every digit), and under `extra="allow"` the columns in `model_extra` are written back, not
2488
+ removed. An enum declared `(str, Enum)` or `(int, Enum)` holds the member, as after `get()`: it
2489
+ compares equal to its value, but `str()` and f-strings give `Color.RED`, not `red` (a `StrEnum` or
2490
+ an `IntEnum` gives the value), so use `.value` to build a key, a URL or a log line from it.
2451
2491
 
2452
2492
  #### Values the SDK cannot read
2453
2493
 
@@ -2493,9 +2533,8 @@ refused value raises `ValueError` before anything is sent.
2493
2533
 
2494
2534
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2495
2535
  `timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
2496
- `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2497
- validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2498
- top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
2536
+ `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; so
2537
+ does lite, every field but the `id` since #261, with top-level durations converted (see
2499
2538
  [After a write that returns the row](#after-a-write-that-returns-the-row)).
2500
2539
 
2501
2540
  ### 25. Geospatial fields
@@ -4307,14 +4346,13 @@ class Person(BaseSurrealModel):
4307
4346
  object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
4308
4347
  - `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
4309
4348
  still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
4310
- - `update()` fails on an instance holding a `READONLY` `datetime` field, after `get()` as after `save()`: Python keeps
4311
- microseconds, SurrealDB nanoseconds, and the server refuses the changed value. The generated class says so: change
4312
- such a record with `merge()`.
4313
- - A sub-field filled by a `DEFAULT` the model does not hold (`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a
4314
- `dict[str, Any]` field) stays `None` on the instance after `save()`, which reads back only `server_fields` and
4315
- computed fields. A following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
4316
- erases it when it is optional. The generated class says so: call `refresh()` after `save()` before an `update()`, or
4317
- change the record with `merge()`.
4349
+ - `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
4350
+ a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
4351
+ microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
4352
+ `READONLY` datetimes to the nanosecond, up to 32 per record; below the top level it keeps one only while the fields
4353
+ before it leave room, which depends on the data (see [Precision and `Decimal`](#precision-and-decimal)). The
4354
+ generated class says so, as does a class with more than 32 top-level fields that may hold a datetime: change such a
4355
+ record with `merge()`.
4318
4356
  - `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
4319
4357
  (SurrealDB 2.x accepts at most N items, 3.x exactly N).
4320
4358
  - `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
@@ -4537,7 +4575,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4537
4575
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4538
4576
  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
4539
4577
  otherwise. The full suite and every divergence below were re-verified on both new versions.
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.
4578
+ 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.
4541
4579
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4542
4580
 
4543
4581
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4656,6 +4694,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4656
4694
  | Schema introspection of a database removed while the connection is open | empty schema | `SurrealDbError` (the database does not exist) until the database is defined again | v0.30.0 |
4657
4695
  | DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
4658
4696
  | A regex with a backslash pair before a `/` (schema introspection) | `/a\\/b/` accepted (a backslash, then an escaped slash), `/\\/` refused: such a definition is a `SchemaIssue`, not read | `/\\/` accepted (an escaped backslash, then the closing slash), `/a\\/b/` refused: such a definition is a `SchemaIssue`, not read | v0.30.0 |
4697
+ | `save()` applies the returned row (explicit id, edges); `update()`/`upsert()` keep an unchanged stored `datetime` (nanoseconds) | stored row and read types (enums, sets…) after `save()`; a top-level `READONLY` datetime updates, a nested one may not; refused if a typed `VALUE` field is left out (#267) | as on 2.x (verified on 3.3.4 and 3.1.5), but a typed `VALUE` field left out is recomputed; `save(tx=)` in an interactive transaction applies the row too, a buffered one does not | v0.30.7 |
4659
4698
  | 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 |
4660
4699
 
4661
4700
  > **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.
@@ -1712,6 +1712,8 @@ exactly what ends a stream.
1712
1712
  - **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
1713
1713
  the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
1714
1714
  and the subscription is still running — so you can subscribe to it again or retry `stop()`.
1715
+ A kill caught by a dropped connection is not a refusal: the subscription died with the socket,
1716
+ so `kill()` records it as ended and returns normally.
1715
1717
  - **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
1716
1718
  notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
1717
1719
 
@@ -2194,8 +2196,12 @@ reads, a `timedelta` is converted from the SDK's duration at any depth too: a to
2194
2196
  `list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
2195
2197
  all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
2196
2198
  Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
2197
- change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
2198
- `datetime`, as before.
2199
+ change it in place. A naive `datetime` is written as UTC and read back as an aware UTC `datetime`.
2200
+ The instance keeps it naive until a call applies the row the server returns (see
2201
+ [After a write that returns the row](#after-a-write-that-returns-the-row)): after `save()` (since
2202
+ #261 with an explicit id too), `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
2203
+ `patch()` or an `atomic_*` helper, the field holds that aware UTC `datetime`, so compare it with
2204
+ aware values. `update()`, and `save(tx=)` in a buffered transaction, leave it naive.
2199
2205
 
2200
2206
  #### `Duration`
2201
2207
 
@@ -2318,7 +2324,23 @@ both lines.
2318
2324
  #### Precision and `Decimal`
2319
2325
 
2320
2326
  - `datetime`: to the microsecond. The SDK truncates the server's nanoseconds, so a stored
2321
- `d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`.
2327
+ `d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`. `update()` and `upsert()` rewrite the
2328
+ whole record, but a `datetime` you did not change (it still floors to the stored value) keeps
2329
+ the stored nanoseconds, on both lines and the embedded engine: a record whose `READONLY`
2330
+ datetimes are top-level fields can be updated after `get()` or `save()`, even when they hold
2331
+ nanoseconds ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). A
2332
+ datetime you changed is written as you set it, and a `READONLY` field still refuses it. So that
2333
+ the statement stays small whatever the data, only the top-level datetimes are sure to be kept,
2334
+ up to 32 per record. Below the top level (in a sub-model, a `list` or a `tuple`, down to three
2335
+ levels) a datetime is kept only while the values rebuilt to reach it fit in what the fields
2336
+ before it left of those 32, so it depends on the data: an `update()` that passes in a test can
2337
+ fail once a list of timestamped items before the sub-model grows. A datetime not kept, and one
2338
+ in a set (its items have no position to match a stored value by), is written as sent: a
2339
+ `READONLY` field holding one may refuse `update()`, so change such a record with `merge()`.
2340
+ SurrealDB 2.x also refuses, for now, `update()` and `upsert()` of an existing record that has
2341
+ a field with a non-optional `TYPE` and a `VALUE` clause the model does not write (a `Computed`
2342
+ field, such as a generated `updated: Computed[datetime]`): change it with `merge()` there
2343
+ ([#267](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/267)).
2322
2344
  - `timedelta`: floored to the microsecond on read (`1h30m1ns` reads `timedelta(seconds=5400)`).
2323
2345
  - `Duration`: exact, to the nanosecond.
2324
2346
  - `Decimal`: a value whose `str()` writes no exponent is sent as before. A value written with an
@@ -2381,22 +2403,40 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2381
2403
 
2382
2404
  #### After a write that returns the row
2383
2405
 
2384
- `save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
2385
- apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2386
- fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2387
- that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2388
- `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2389
- `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2390
- model's own validators included, and a sub-model field holds its model instance, not the row's
2391
- `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2392
- whole does not validate, each such field is validated on its own, except one that the model's own
2393
- validators could reshape (a `field_validator` on that field, a `model_validator`, a
2394
- `model_post_init`): that one, like a value that does not validate, is applied as received, so
2395
- these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2396
- (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2397
- `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2398
- stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2399
- top-level `date` and `set` fields while serialising them.
2406
+ `save()` (with or without an id, an edge's too), `refresh()`, `merge()`, `upsert()`, `patch()` and
2407
+ the `atomic_*` helpers apply the row the server returns to the instance. After `save()` the
2408
+ instance therefore holds what the record holds: the `server_fields` and computed fields, the
2409
+ sub-fields a `DEFAULT` filled (`prefs.at DEFAULT time::now()`), and the values the server coerced
2410
+ or rewrote (`VALUE string::lowercase($value)`), so a following `update()` writes them back
2411
+ unchanged ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). An id you
2412
+ gave stays as you gave it; an auto id is the server's `RecordID`. A buffered transaction (HTTP,
2413
+ SurrealDB 2.x, the embedded engine) returns no row before commit: there `save(tx=)` leaves the
2414
+ instance as it was, and `refresh()` after the commit reads the row.
2415
+
2416
+ The top-level `timedelta`, `Duration` and geometry fields (since v0.24.0, see
2417
+ [section 25](#25-geospatial-fields)) are converted on the way, and every other field gets the
2418
+ value a read gives (#261; before, only a field holding a sub-model, a geometry or a nested
2419
+ `timedelta` did): the row goes through the model's validation, the model's own validators
2420
+ included. A sub-model field holds its model instance, not the row's `dict`, with the ORM's
2421
+ durations, `timedelta`s, ranges and geometries inside; an enum field holds the enum, not its `str`
2422
+ or `int`; a `tuple`, set, `date` or `Range` field holds its declared type, not the SDK's `list`,
2423
+ midnight `datetime` or `Range`; a `float` field stored in a `decimal` column holds a `float`, not a
2424
+ `Decimal`; a `list[Duration]` holds the ORM's durations. When the row as a whole does not validate,
2425
+ each field is validated on its own, except one that the model's own validators could reshape (a
2426
+ `field_validator` on that field, a `model_validator`, a `model_post_init`): that one, like a value
2427
+ that does not validate, is applied as received, so these calls never fail on it. The `id` keeps
2428
+ the server's `RecordID`. A column the model does not declare goes where a read puts it: as the SDK
2429
+ reads it into `model_extra` under `extra="allow"`, nowhere otherwise. So a column holding a Pydantic
2430
+ `@computed_field` (`model_dump()` writes it) or named like a method (`json`) never replaces that
2431
+ attribute.
2432
+
2433
+ Writing such an instance back is safe, sub-models included: a following `update()` replaces the
2434
+ record with these values, as after `get()`. So a `float` field stored in a `decimal` column writes
2435
+ the float's rounding (`0.12345678901234567890` becomes `0.1234567890123457`: declare `Decimal` to
2436
+ keep every digit), and under `extra="allow"` the columns in `model_extra` are written back, not
2437
+ removed. An enum declared `(str, Enum)` or `(int, Enum)` holds the member, as after `get()`: it
2438
+ compares equal to its value, but `str()` and f-strings give `Color.RED`, not `red` (a `StrEnum` or
2439
+ an `IntEnum` gives the value), so use `.value` to build a key, a URL or a log line from it.
2400
2440
 
2401
2441
  #### Values the SDK cannot read
2402
2442
 
@@ -2442,9 +2482,8 @@ refused value raises `ValueError` before anything is sent.
2442
2482
 
2443
2483
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2444
2484
  `timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
2445
- `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2446
- validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2447
- top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
2485
+ `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; so
2486
+ does lite, every field but the `id` since #261, with top-level durations converted (see
2448
2487
  [After a write that returns the row](#after-a-write-that-returns-the-row)).
2449
2488
 
2450
2489
  ### 25. Geospatial fields
@@ -4256,14 +4295,13 @@ class Person(BaseSurrealModel):
4256
4295
  object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
4257
4296
  - `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
4258
4297
  still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
4259
- - `update()` fails on an instance holding a `READONLY` `datetime` field, after `get()` as after `save()`: Python keeps
4260
- microseconds, SurrealDB nanoseconds, and the server refuses the changed value. The generated class says so: change
4261
- such a record with `merge()`.
4262
- - A sub-field filled by a `DEFAULT` the model does not hold (`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a
4263
- `dict[str, Any]` field) stays `None` on the instance after `save()`, which reads back only `server_fields` and
4264
- computed fields. A following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
4265
- erases it when it is optional. The generated class says so: call `refresh()` after `save()` before an `update()`, or
4266
- change the record with `merge()`.
4298
+ - `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
4299
+ a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
4300
+ microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
4301
+ `READONLY` datetimes to the nanosecond, up to 32 per record; below the top level it keeps one only while the fields
4302
+ before it leave room, which depends on the data (see [Precision and `Decimal`](#precision-and-decimal)). The
4303
+ generated class says so, as does a class with more than 32 top-level fields that may hold a datetime: change such a
4304
+ record with `merge()`.
4267
4305
  - `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
4268
4306
  (SurrealDB 2.x accepts at most N items, 3.x exactly N).
4269
4307
  - `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
@@ -4486,7 +4524,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4486
4524
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4487
4525
  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
4488
4526
  otherwise. The full suite and every divergence below were re-verified on both new versions.
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.
4527
+ 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.
4490
4528
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4491
4529
 
4492
4530
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4605,6 +4643,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4605
4643
  | Schema introspection of a database removed while the connection is open | empty schema | `SurrealDbError` (the database does not exist) until the database is defined again | v0.30.0 |
4606
4644
  | DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
4607
4645
  | A regex with a backslash pair before a `/` (schema introspection) | `/a\\/b/` accepted (a backslash, then an escaped slash), `/\\/` refused: such a definition is a `SchemaIssue`, not read | `/\\/` accepted (an escaped backslash, then the closing slash), `/a\\/b/` refused: such a definition is a `SchemaIssue`, not read | v0.30.0 |
4646
+ | `save()` applies the returned row (explicit id, edges); `update()`/`upsert()` keep an unchanged stored `datetime` (nanoseconds) | stored row and read types (enums, sets…) after `save()`; a top-level `READONLY` datetime updates, a nested one may not; refused if a typed `VALUE` field is left out (#267) | as on 2.x (verified on 3.3.4 and 3.1.5), but a typed `VALUE` field left out is recomputed; `save(tx=)` in an interactive transaction applies the row too, a buffered one does not | v0.30.7 |
4608
4647
  | 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 |
4609
4648
 
4610
4649
  > **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.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.30.3"
3
+ version = "0.30.7"
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.3"
1
+ __version__ = "0.30.7"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -33,12 +33,14 @@ from .exceptions import (
33
33
  from .functions import build_call_statement, normalize_function_name, parse_function_parameters
34
34
  from .live import (
35
35
  LiveIterator,
36
+ cancellation_lost,
36
37
  close_all_subscribers,
37
38
  is_connection_failure,
38
39
  is_dead,
39
40
  mark_killed,
40
41
  open_stream,
41
42
  owner_of,
43
+ recv_task_of,
42
44
  release_subscribers,
43
45
  require_websocket,
44
46
  )
@@ -50,6 +52,10 @@ logger = logging.getLogger(__name__)
50
52
  # Strong references to fire-and-forget closes, which the event loop alone would let be collected.
51
53
  _BACKGROUND: set[asyncio.Task[Any]] = set()
52
54
 
55
+ # How long a KILL that failed on a transport error waits for the SDK's receive loop to end, before
56
+ # deciding the connection is still up (and the failure a real one).
57
+ _DROP_SETTLE_TIMEOUT = 1.0
58
+
53
59
 
54
60
  @lru_cache(maxsize=256)
55
61
  def _cached_type_adapter(return_type: Any) -> TypeAdapter[Any]:
@@ -2473,10 +2479,16 @@ class SurrealDBConnectionManager:
2473
2479
  client still cached on this loop — a stream started on a server, stopped after switching
2474
2480
  to the engine — receives the KILL; otherwise the call is the no-op above.
2475
2481
 
2482
+ A KILL caught by a drop — sent as the connection goes down, before the SDK has noticed —
2483
+ is not a refusal either: the live query died with the socket, so the call ends as it does
2484
+ on a dead client, and raises nothing.
2485
+
2476
2486
  :param query_uuid: the uuid of a running live query, e.g. ``stream.live_id``.
2477
2487
  :raises SurrealDbError: if the server refuses the kill for a reason other than an
2478
2488
  unknown uuid. The readers are released anyway, but the uuid is **not** recorded as
2479
2489
  dead — the subscription is still running, so a retry can re-attach to it.
2490
+ :raises asyncio.CancelledError: if the calling task is cancelled, even when the SDK
2491
+ reports the cancelled request as an ordinary error. The readers are released.
2480
2492
  """
2481
2493
  client = cls._cached_client()
2482
2494
  try:
@@ -2485,6 +2497,8 @@ class SurrealDBConnectionManager:
2485
2497
  # receive loop that died on a bad frame leaves the socket open, though, and the server
2486
2498
  # still running them: closing the transport is what ends them then.
2487
2499
  if client is None or is_dead(client):
2500
+ # Before any await: a resubscribe woken by the same drop must find the reader gone.
2501
+ release_subscribers(query_uuid)
2488
2502
  if client is not None:
2489
2503
  await cls._close_dead_socket(client)
2490
2504
  mark_killed(query_uuid)
@@ -2494,14 +2508,41 @@ class SurrealDBConnectionManager:
2494
2508
  try:
2495
2509
  await client.kill(query_uuid)
2496
2510
  except Exception as exc:
2497
- if not cls._is_unknown_live_query(exc):
2511
+ # Before any await: a resubscribe woken by the same drop must find the reader gone,
2512
+ # or it opens a connection for a subscription being torn down. Closing the socket
2513
+ # below yields the loop on Python 3.11, where `wait_for` always wraps a Task.
2514
+ release_subscribers(query_uuid)
2515
+ if cancellation_lost(exc):
2516
+ raise asyncio.CancelledError from exc # the SDK raised over the caller's cancellation
2517
+ if await cls._dropped_under_request(client, exc):
2518
+ # The server never answered: the connection went down with the request in flight.
2519
+ await cls._close_dead_socket(client)
2520
+ elif not cls._is_unknown_live_query(exc):
2498
2521
  raise SurrealDbError(f"Failed to kill live query {query_uuid}: {exc}") from exc
2499
2522
  mark_killed(query_uuid)
2500
2523
  finally:
2501
2524
  # In a `finally` so that every exit — success, failure, cancellation — wakes the
2502
- # readers; nothing else ever would.
2525
+ # readers; nothing else ever would. Idempotent after an early release above, and it
2526
+ # also wakes a reader that subscribed to the uuid while this call was awaiting.
2503
2527
  release_subscribers(query_uuid)
2504
2528
 
2529
+ @staticmethod
2530
+ async def _dropped_under_request(client: Any, exc: Exception) -> bool:
2531
+ """Whether a request on *client* failed with *exc* because its WebSocket dropped.
2532
+
2533
+ Decided on the client, never on the error alone. The SDK reports a request caught by a
2534
+ drop as a bare ``KeyError``: its receive loop ends, cancels the pending request and clears
2535
+ the pending-request map, so the request's own cleanup finds its id gone (surrealdb 2.0.0)
2536
+ — by then the receive task is done. A transport error can surface a moment before that
2537
+ loop has ended, so it gets a bounded wait to catch up; anything else is decided at once.
2538
+ """
2539
+ task = recv_task_of(client)
2540
+ if task is None:
2541
+ return False
2542
+ if not task.done() and is_connection_failure(exc, None):
2543
+ await asyncio.wait({task}, timeout=_DROP_SETTLE_TIMEOUT)
2544
+ return task.done()
2545
+
2505
2546
  @staticmethod
2506
2547
  def _is_unknown_live_query(exc: Exception) -> bool:
2507
2548
  """Whether *exc* is the server refusing to kill a live query it does not know.