surreal-orm-lite 0.30.5__tar.gz → 0.30.8__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.5 → surreal_orm_lite-0.30.8}/CHANGELOG.md +139 -0
  2. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/PKG-INFO +88 -44
  3. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/README.md +87 -43
  4. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/cache.py +21 -19
  7. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/changefeed.py +6 -6
  8. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_manager.py +33 -32
  9. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/define_parser.py +35 -34
  10. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/edge.py +8 -6
  11. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/embedded.py +9 -7
  12. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/functions.py +1 -1
  13. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/introspection.py +58 -27
  14. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/live.py +1 -1
  15. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_base.py +172 -140
  16. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_generator.py +150 -109
  17. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/query_set.py +44 -43
  18. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/routing.py +13 -13
  19. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/schema_state.py +2 -1
  20. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/subquery.py +27 -26
  21. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/database.py +1 -1
  22. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/time_travel.py +19 -18
  23. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/transaction.py +11 -4
  24. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/types.py +5 -5
  25. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/utils.py +146 -6
  26. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/.gitignore +0 -0
  27. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/LICENSE +0 -0
  28. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/Makefile +0 -0
  29. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/_sdk.py +0 -0
  30. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/aggregations.py +0 -0
  31. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/auth.py +0 -0
  32. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/concurrency.py +0 -0
  33. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_config.py +0 -0
  34. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/constants.py +0 -0
  35. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/decoding.py +0 -0
  36. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/encoding.py +0 -0
  37. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/enum.py +0 -0
  38. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/exceptions.py +0 -0
  39. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/geo.py +0 -0
  40. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_auth.py +0 -0
  41. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/py.typed +0 -0
  42. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/q.py +0 -0
  43. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/signals.py +0 -0
  44. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/surql_literal.py +0 -0
  45. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/__init__.py +0 -0
  46. {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/fixtures.py +0 -0
@@ -5,6 +5,145 @@ 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.8] - 2026-10-19
9
+
10
+ Follow-ups to the v0.30.0 schema introspection (#260): a connection lost while the schema is read
11
+ raises instead of becoming schema issues, a relation table is an edge whatever the case of its
12
+ `table_type`, and generated classes carry the change feed and permissions comments the v0.30.0
13
+ notes described. No new public API.
14
+
15
+ ### Fixed
16
+
17
+ - **A connection lost during `introspect()` raises** (#260). Every error of an `INFO FOR TABLE`
18
+ became a `SchemaIssue`, so a connection that dropped after `INFO FOR DB` turned every remaining
19
+ table into "could not be read": `introspect()` returned normally, and
20
+ `generate_models_from_db(path)` replaced a working module with one that listed those tables as
21
+ skipped. Only the server's answer to `INFO FOR TABLE` is an issue now; the transport's error, or
22
+ the ORM's, propagates unchanged before anything is written, so an existing file is left as it
23
+ was.
24
+ - **A relation table is an edge whatever the case of its `table_type`** (#260). The generator
25
+ compared `table_type` with exact case in two places and ignored case in a third: a hand-built
26
+ `TableState(table_type="RELATION")` gave a `BaseSurrealEdge` class that declared `in_` and `out`
27
+ again, and the module failed to import with a `TypeError`. States read by `DatabaseIntrospector`
28
+ hold `"relation"` and were not affected.
29
+ - **Generated classes comment their change feed and permissions** (#260), as the v0.30.0 notes
30
+ said: `# Changefeed: 1d INCLUDE ORIGINAL` and
31
+ `# Permissions: FOR select WHERE $auth.id = owner, FOR create, update FULL, FOR delete NONE`,
32
+ grouped the way SurrealDB renders them (`# Permissions: FULL` when `FULL` covers the four
33
+ operations). A table left at the default `PERMISSIONS NONE`, all four operations `NONE`, gets no
34
+ permissions comment. The database still applies both; the `SurrealConfigDict` keys for them
35
+ arrive with v0.31.0–v0.33.0. Unlike what those notes listed, `table_type` is not a comment: it
36
+ shows through the base class, `BaseSurrealEdge` for a relation table.
37
+
38
+ ### Changed
39
+
40
+ - **An `INFO FOR TABLE` refused after `INFO FOR DB` succeeded raises
41
+ `SurrealDbAuthenticationError`** (#260) instead of becoming a `SchemaIssue`: the session lost its
42
+ rights while the schema was read (for example a client closed and reopened anonymously), and the
43
+ table is not at fault. A refused `INFO FOR DB` raises the same error, as in v0.30.0.
44
+
45
+ ### Notes
46
+
47
+ - Docstrings and comments no longer cite internal design-note ids: they name the exception raised,
48
+ the case refused or the README section that documents it. README section 31 describes the new
49
+ class comments and which `INFO FOR TABLE` failures are schema issues.
50
+ - The linear-time tests of the definition parser keep the fastest of up to three timings, so a
51
+ pause of a shared CI runner cannot fail them.
52
+ - Same behaviour on SurrealDB 2.x, 3.x and the embedded engine. Server pins unchanged: tested
53
+ against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus 3.1.5 for backward
54
+ compatibility.
55
+
56
+ ## [0.30.7] - 2026-10-19
57
+
58
+ An instance stays in step with its stored row (#261): `save()` applies the whole row the server
59
+ returns, every call that applies a returned row validates it as a read does, and `update()` keeps
60
+ the stored nanoseconds of a datetime it did not change, so a record with a top-level `READONLY`
61
+ datetime can be updated. No new public API, but what an instance holds after a write changes for
62
+ every model: read **Changed** before upgrading.
63
+
64
+ ### Fixed
65
+
66
+ - **`update()` after `save()` or `get()` on a `READONLY` top-level `datetime`** is no longer
67
+ refused by the server (#261). SurrealDB stores nanoseconds and the SDK reads microseconds, so
68
+ `update()` wrote back a changed value. See item 5 under Changed.
69
+ - **Sub-fields a `DEFAULT` fills** (`prefs.at DEFAULT time::now()`) are on the instance right after
70
+ `save()` (explicit id, auto id, interactive transaction), so a following `update()` no longer
71
+ sends them as `NONE`, which the server refused for a required sub-field and which erased an
72
+ optional one (#261).
73
+ - **`tuple` and `set` fields** hold their declared type after `save()`, `upsert()`, `merge()` and
74
+ `patch()`, as after `get()` (item 2 under Changed), not the SDK's `list` (#261).
75
+ - **A returned column named like a Pydantic `@computed_field` or a model method** (`json`) no
76
+ longer replaces that attribute (#261). In 0.30.1, with a `@computed_field` (which `model_dump()`
77
+ writes), auto-id `save()`, `refresh()` and `merge()` raised `AttributeError` after the record was
78
+ stored.
79
+ - **`generate_models_from_db()`**: generated classes no longer carry the note about `DEFAULT`
80
+ sub-fields, and the `READONLY` `update()` note remains only for a datetime below the top level
81
+ or a top-level one past the 32nd (#261).
82
+ - **Buffered transactions**: a statement's parameters are renamed in one pass (#261). In 0.30.1,
83
+ `$a` next to a variable named `t0_a` was renamed twice and bound to `t0_a`'s value, and a
84
+ statement with thousands of bound values was slow to queue.
85
+
86
+ ```python
87
+ # DEFINE FIELD created ON event TYPE datetime DEFAULT time::now() READONLY;
88
+ event = await Event.objects().get("launch") # created read to the microsecond
89
+ event.title = "Launch day"
90
+ await event.update() # was refused ("readonly"); the stored created keeps its nanoseconds
91
+ ```
92
+
93
+ ### Changed
94
+
95
+ Each item was measured against 0.30.1 on SurrealDB 3.3.4, 2.7.0 and the embedded engine
96
+ (`mem://`) and holds on all three unless stated.
97
+
98
+ 1. **Explicit-id `save()`, an edge's `save()` and interactive `save(tx=)` apply the whole stored
99
+ row** (#261). In 0.30.1, explicit-id `save()` and interactive `save(tx=)` read back only the
100
+ `server_fields` and computed fields, and an edge's `save()` (either id) only its `id` and
101
+ `server_fields`: the instance kept the values passed in. Now a naive `datetime` becomes the
102
+ aware UTC `datetime` a read gives (compare it with aware values), a sub-model field holds a new
103
+ instance (not the object passed in), and values a `VALUE` clause rewrote or the server coerced
104
+ replace the ones sent (`VALUE string::lowercase($value)` turns `"AbC"` into `"abc"` on the
105
+ instance). Interactive transactions exist on SurrealDB 3.x over WebSocket only; a buffered
106
+ transaction (HTTP, 2.x, the embedded engine) still leaves the instance as it was.
107
+ 2. **Every call that applies the returned row validates it like a read** (#261): `save()` with
108
+ either id, an edge's `save()`, `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
109
+ `patch()` and the `atomic_*` helpers. An enum field holds the enum member, not the raw
110
+ `str`/`int` (a `str` or `int` enum still compares equal to its value, a plain `Enum` member no
111
+ longer does); `tuple`, `set`, `date` and `Range` fields hold their declared type instead of the
112
+ SDK's `list`, midnight `datetime` and `Range`; a `float` field stored in a `decimal` column holds
113
+ a `float`, not a `Decimal`; a `list[Duration]` holds the ORM's `Duration`s, not the SDK's. In
114
+ 0.30.1, `refresh()`, `merge()`, auto-id `save()`, `upsert()`, `patch()` and `atomic_*` kept the
115
+ SDK's values for these fields (explicit-id `save()` kept the values passed in).
116
+ 3. **The model's validators run on the returned row for every model** (#261). Field and model
117
+ validators (any mode) and `model_post_init` run once per call listed in item 2, on a validated
118
+ copy of the row, and their result is applied to every field. In 0.30.1 they ran only when the
119
+ row held a sub-model field, a nested `timedelta` field or a geometry field stored as a GeoJSON
120
+ object, and their result reached only those fields; otherwise they did not run at all. A
121
+ validator that is not idempotent is applied again, as on `get()`, and a following `update()`
122
+ writes that value back: with `label` validated as `v + "!"`, `Model(id="a", label="x")`,
123
+ `save()` then `update()` stored `x!` in 0.30.1 and stores `x!!` now; `merge()` then `update()`
124
+ gives the same difference.
125
+ 4. **Under `extra="allow"`, the returned row's undeclared columns go to `model_extra`** after the
126
+ calls listed in item 2, where a read puts them (0.30.1 dropped them), and `merge(refresh=False)`
127
+ with an undeclared key updates `model_extra` (#261).
128
+ 5. **`update()` and `upsert()` keep the stored nanoseconds of a datetime written back unchanged**
129
+ (one that still floors to the stored value at the microsecond), for every top-level datetime up
130
+ to 32 per record, so a record whose `READONLY` datetimes are top-level fields can be updated
131
+ after `get()` or `save()` (#261). Below the top level (a sub-model, a `list`, a `tuple`, a set)
132
+ this depends on the data: change such a record with `merge()`.
133
+
134
+ ### Notes
135
+
136
+ - SurrealDB 2.x still refuses `update()` and `upsert()` of an existing record that has a field
137
+ with a non-optional `TYPE` and a `VALUE` clause the model does not write, such as a generated
138
+ `updated: Computed[datetime]` (#267): change such a record with `merge()` there. 0.30.1 behaved
139
+ the same way before this release; SurrealDB 3.x recomputes the field. The v0.30.0 example
140
+ notebook changes its generated `NbPerson` with `merge()` for that reason.
141
+ - The README's "After a write that returns the row", "Precision and `Decimal`" and "What the
142
+ generator does not do" sections, and a new row of the 2.x vs 3.x behaviour table, describe these
143
+ changes.
144
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus
145
+ 3.1.5 for backward compatibility.
146
+
8
147
  ## [0.30.5] - 2026-10-19
9
148
 
10
149
  `SurrealDBConnectionManager.kill()` no longer reports a connection lost under the request as a
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.30.5
3
+ Version: 0.30.8
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
@@ -2247,8 +2247,12 @@ reads, a `timedelta` is converted from the SDK's duration at any depth too: a to
2247
2247
  `list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
2248
2248
  all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
2249
2249
  Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
2250
- change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
2251
- `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.
2252
2256
 
2253
2257
  #### `Duration`
2254
2258
 
@@ -2371,7 +2375,23 @@ both lines.
2371
2375
  #### Precision and `Decimal`
2372
2376
 
2373
2377
  - `datetime`: to the microsecond. The SDK truncates the server's nanoseconds, so a stored
2374
- `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)).
2375
2395
  - `timedelta`: floored to the microsecond on read (`1h30m1ns` reads `timedelta(seconds=5400)`).
2376
2396
  - `Duration`: exact, to the nanosecond.
2377
2397
  - `Decimal`: a value whose `str()` writes no exponent is sent as before. A value written with an
@@ -2434,22 +2454,40 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2434
2454
 
2435
2455
  #### After a write that returns the row
2436
2456
 
2437
- `save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
2438
- apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2439
- fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2440
- that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2441
- `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2442
- `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2443
- model's own validators included, and a sub-model field holds its model instance, not the row's
2444
- `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2445
- whole does not validate, each such field is validated on its own, except one that the model's own
2446
- validators could reshape (a `field_validator` on that field, a `model_validator`, a
2447
- `model_post_init`): that one, like a value that does not validate, is applied as received, so
2448
- these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2449
- (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2450
- `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2451
- stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2452
- 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.
2453
2491
 
2454
2492
  #### Values the SDK cannot read
2455
2493
 
@@ -2495,9 +2533,8 @@ refused value raises `ValueError` before anything is sent.
2495
2533
 
2496
2534
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2497
2535
  `timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
2498
- `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2499
- validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2500
- 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
2501
2538
  [After a write that returns the row](#after-a-write-that-returns-the-row)).
2502
2539
 
2503
2540
  ### 25. Geospatial fields
@@ -4150,11 +4187,14 @@ schema.issues # (): everything was read and parsed
4150
4187
  logging a state shows names and structure only: definition texts stay in their attributes, out of `repr()` and
4151
4188
  `str()`.
4152
4189
  - Nothing is guessed. A definition that cannot be parsed exactly, a section of an unexpected shape or an
4153
- `INFO FOR TABLE` that fails becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`, `table`, `message` and
4154
- `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()` does not raise for them.
4155
- An issue's message never quotes the definition, which may hold a secret.
4156
- - Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, `SurrealDbError` when
4157
- `INFO FOR DB` fails otherwise, and `SurrealDbNotFoundError` for a `tables=` name the database does not define.
4190
+ `INFO FOR TABLE` the server answers with an error becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`,
4191
+ `table`, `message` and `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
4192
+ does not raise for them. An issue's message never quotes the definition, which may hold a secret.
4193
+ - Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, or is refused an
4194
+ `INFO FOR TABLE` after `INFO FOR DB` succeeded (it lost its rights meanwhile); `SurrealDbError` when `INFO FOR DB`
4195
+ fails otherwise; and `SurrealDbNotFoundError` for a `tables=` name the database does not define. A connection lost
4196
+ during the read is not an issue: the transport's error (or the ORM's) propagates unchanged, so
4197
+ `generate_models_from_db()` never replaces a file with models of tables it could not read.
4158
4198
 
4159
4199
  ```python
4160
4200
  SurrealDBConnectionManager.add_connection("archive", url="mem://", namespace="shop", database="archive")
@@ -4229,8 +4269,10 @@ class Person(BaseSurrealModel):
4229
4269
  model declares `id: str | None = None` first, then one line per field, in codepoint order of the columns.
4230
4270
  - A class is named after its table in PascalCase, without singularisation (`game_tables` → `GameTables`); a name
4231
4271
  that is taken — a Python keyword, a name the module imports, another table's class — gets `Model` appended (`range`
4232
- → `RangeModel`). The table's comment, relation ends, view query, indexes and events are comments of its class, and
4233
- the module's header lists every table or field left out, with the reason.
4272
+ → `RangeModel`). The table's comment, relation ends, view query, change feed (`# Changefeed: 1d`), permissions
4273
+ (`# Permissions: FOR select WHERE …, FOR create, update FULL, FOR delete NONE`, left out when all four are `NONE`,
4274
+ a table's default), indexes and events are comments of its class, and the module's header lists every table or
4275
+ field left out, with the reason.
4234
4276
  - The source is safe to import: names, comments and expressions read from the database reach it only as escaped
4235
4277
  string literals, single-line ASCII comments and identifiers the generator builds, so a schema cannot inject code
4236
4278
  into it. It holds no timestamp, server address, namespace or database name, and no
@@ -4307,16 +4349,16 @@ class Person(BaseSurrealModel):
4307
4349
 
4308
4350
  - It reads no record: a `SCHEMALESS` table's model holds the fields the table declares (with `extra="allow"`), and an
4309
4351
  object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
4310
- - `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
4311
- still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
4312
- - `update()` fails on an instance holding a `READONLY` `datetime` field, after `get()` as after `save()`: Python keeps
4313
- microseconds, SurrealDB nanoseconds, and the server refuses the changed value. The generated class says so: change
4314
- such a record with `merge()`.
4315
- - A sub-field filled by a `DEFAULT` the model does not hold (`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a
4316
- `dict[str, Any]` field) stays `None` on the instance after `save()`, which reads back only `server_fields` and
4317
- computed fields. A following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
4318
- erases it when it is optional. The generated class says so: call `refresh()` after `save()` before an `update()`, or
4319
- change the record with `merge()`.
4352
+ - A field's `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and comment are not generated, and a
4353
+ table's permissions and change feed are only comments of its class: the database still applies them. `READONLY` is
4354
+ a trailing `# READONLY` comment: no field option exists for it.
4355
+ - `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
4356
+ a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
4357
+ microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
4358
+ `READONLY` datetimes to the nanosecond, up to 32 per record; below the top level it keeps one only while the fields
4359
+ before it leave room, which depends on the data (see [Precision and `Decimal`](#precision-and-decimal)). The
4360
+ generated class says so, as does a class with more than 32 top-level fields that may hold a datetime: change such a
4361
+ record with `merge()`.
4320
4362
  - `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
4321
4363
  (SurrealDB 2.x accepts at most N items, 3.x exactly N).
4322
4364
  - `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
@@ -4406,9 +4448,10 @@ reads, stores, logs or writes them.
4406
4448
  ORM's connection name, which routing, reconnects and the generated models' `connection=` key need (full ORM: an
4407
4449
  `HTTPConnection`).
4408
4450
  - **Generated models use comments** where the full ORM writes
4409
- `SurrealConfigDict(table_type=…, permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`:
4410
- those keys arrive in the lite's `SurrealConfigDict` with v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM:
4411
- `Field(readonly=True)`).
4451
+ `SurrealConfigDict(permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`
4452
+ (`# Permissions: …`, `# Changefeed: …`, `# View: AS …`, `# IN … OUT … ENFORCED`), and the base class where it writes
4453
+ `table_type=` (`BaseSurrealEdge` for a relation table): those keys arrive in the lite's `SurrealConfigDict` with
4454
+ v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM: `Field(readonly=True)`).
4412
4455
  - **`RecordID` instead of `ForeignKey`/`ReferencesField`**; no `VectorField` or `Encrypted`; `computed()` instead
4413
4456
  of `Computed()`; `Duration`, `UUID`, `Decimal` and the geometry classes instead of `str`, `dict` and `float`;
4414
4457
  nested fields become sub-models (full ORM: dotted attribute lines).
@@ -4539,7 +4582,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4539
4582
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4540
4583
  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
4541
4584
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4542
- 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.
4585
+ 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.
4543
4586
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4544
4587
 
4545
4588
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4658,6 +4701,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4658
4701
  | 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 |
4659
4702
  | DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
4660
4703
  | 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 |
4704
+ | `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 |
4661
4705
  | 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 |
4662
4706
 
4663
4707
  > **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.
@@ -2196,8 +2196,12 @@ reads, a `timedelta` is converted from the SDK's duration at any depth too: a to
2196
2196
  `list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
2197
2197
  all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
2198
2198
  Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
2199
- change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
2200
- `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.
2201
2205
 
2202
2206
  #### `Duration`
2203
2207
 
@@ -2320,7 +2324,23 @@ both lines.
2320
2324
  #### Precision and `Decimal`
2321
2325
 
2322
2326
  - `datetime`: to the microsecond. The SDK truncates the server's nanoseconds, so a stored
2323
- `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)).
2324
2344
  - `timedelta`: floored to the microsecond on read (`1h30m1ns` reads `timedelta(seconds=5400)`).
2325
2345
  - `Duration`: exact, to the nanosecond.
2326
2346
  - `Decimal`: a value whose `str()` writes no exponent is sent as before. A value written with an
@@ -2383,22 +2403,40 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2383
2403
 
2384
2404
  #### After a write that returns the row
2385
2405
 
2386
- `save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
2387
- apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2388
- fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2389
- that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2390
- `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2391
- `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2392
- model's own validators included, and a sub-model field holds its model instance, not the row's
2393
- `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2394
- whole does not validate, each such field is validated on its own, except one that the model's own
2395
- validators could reshape (a `field_validator` on that field, a `model_validator`, a
2396
- `model_post_init`): that one, like a value that does not validate, is applied as received, so
2397
- these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2398
- (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2399
- `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2400
- stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2401
- 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.
2402
2440
 
2403
2441
  #### Values the SDK cannot read
2404
2442
 
@@ -2444,9 +2482,8 @@ refused value raises `ValueError` before anything is sent.
2444
2482
 
2445
2483
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2446
2484
  `timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
2447
- `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2448
- validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2449
- 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
2450
2487
  [After a write that returns the row](#after-a-write-that-returns-the-row)).
2451
2488
 
2452
2489
  ### 25. Geospatial fields
@@ -4099,11 +4136,14 @@ schema.issues # (): everything was read and parsed
4099
4136
  logging a state shows names and structure only: definition texts stay in their attributes, out of `repr()` and
4100
4137
  `str()`.
4101
4138
  - Nothing is guessed. A definition that cannot be parsed exactly, a section of an unexpected shape or an
4102
- `INFO FOR TABLE` that fails becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`, `table`, `message` and
4103
- `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()` does not raise for them.
4104
- An issue's message never quotes the definition, which may hold a secret.
4105
- - Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, `SurrealDbError` when
4106
- `INFO FOR DB` fails otherwise, and `SurrealDbNotFoundError` for a `tables=` name the database does not define.
4139
+ `INFO FOR TABLE` the server answers with an error becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`,
4140
+ `table`, `message` and `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
4141
+ does not raise for them. An issue's message never quotes the definition, which may hold a secret.
4142
+ - Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, or is refused an
4143
+ `INFO FOR TABLE` after `INFO FOR DB` succeeded (it lost its rights meanwhile); `SurrealDbError` when `INFO FOR DB`
4144
+ fails otherwise; and `SurrealDbNotFoundError` for a `tables=` name the database does not define. A connection lost
4145
+ during the read is not an issue: the transport's error (or the ORM's) propagates unchanged, so
4146
+ `generate_models_from_db()` never replaces a file with models of tables it could not read.
4107
4147
 
4108
4148
  ```python
4109
4149
  SurrealDBConnectionManager.add_connection("archive", url="mem://", namespace="shop", database="archive")
@@ -4178,8 +4218,10 @@ class Person(BaseSurrealModel):
4178
4218
  model declares `id: str | None = None` first, then one line per field, in codepoint order of the columns.
4179
4219
  - A class is named after its table in PascalCase, without singularisation (`game_tables` → `GameTables`); a name
4180
4220
  that is taken — a Python keyword, a name the module imports, another table's class — gets `Model` appended (`range`
4181
- → `RangeModel`). The table's comment, relation ends, view query, indexes and events are comments of its class, and
4182
- the module's header lists every table or field left out, with the reason.
4221
+ → `RangeModel`). The table's comment, relation ends, view query, change feed (`# Changefeed: 1d`), permissions
4222
+ (`# Permissions: FOR select WHERE …, FOR create, update FULL, FOR delete NONE`, left out when all four are `NONE`,
4223
+ a table's default), indexes and events are comments of its class, and the module's header lists every table or
4224
+ field left out, with the reason.
4183
4225
  - The source is safe to import: names, comments and expressions read from the database reach it only as escaped
4184
4226
  string literals, single-line ASCII comments and identifiers the generator builds, so a schema cannot inject code
4185
4227
  into it. It holds no timestamp, server address, namespace or database name, and no
@@ -4256,16 +4298,16 @@ class Person(BaseSurrealModel):
4256
4298
 
4257
4299
  - It reads no record: a `SCHEMALESS` table's model holds the fields the table declares (with `extra="allow"`), and an
4258
4300
  object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
4259
- - `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
4260
- still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
4261
- - `update()` fails on an instance holding a `READONLY` `datetime` field, after `get()` as after `save()`: Python keeps
4262
- microseconds, SurrealDB nanoseconds, and the server refuses the changed value. The generated class says so: change
4263
- such a record with `merge()`.
4264
- - A sub-field filled by a `DEFAULT` the model does not hold (`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a
4265
- `dict[str, Any]` field) stays `None` on the instance after `save()`, which reads back only `server_fields` and
4266
- computed fields. A following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
4267
- erases it when it is optional. The generated class says so: call `refresh()` after `save()` before an `update()`, or
4268
- change the record with `merge()`.
4301
+ - A field's `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and comment are not generated, and a
4302
+ table's permissions and change feed are only comments of its class: the database still applies them. `READONLY` is
4303
+ a trailing `# READONLY` comment: no field option exists for it.
4304
+ - `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
4305
+ a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
4306
+ microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
4307
+ `READONLY` datetimes to the nanosecond, up to 32 per record; below the top level it keeps one only while the fields
4308
+ before it leave room, which depends on the data (see [Precision and `Decimal`](#precision-and-decimal)). The
4309
+ generated class says so, as does a class with more than 32 top-level fields that may hold a datetime: change such a
4310
+ record with `merge()`.
4269
4311
  - `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
4270
4312
  (SurrealDB 2.x accepts at most N items, 3.x exactly N).
4271
4313
  - `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
@@ -4355,9 +4397,10 @@ reads, stores, logs or writes them.
4355
4397
  ORM's connection name, which routing, reconnects and the generated models' `connection=` key need (full ORM: an
4356
4398
  `HTTPConnection`).
4357
4399
  - **Generated models use comments** where the full ORM writes
4358
- `SurrealConfigDict(table_type=…, permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`:
4359
- those keys arrive in the lite's `SurrealConfigDict` with v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM:
4360
- `Field(readonly=True)`).
4400
+ `SurrealConfigDict(permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`
4401
+ (`# Permissions: …`, `# Changefeed: …`, `# View: AS …`, `# IN … OUT … ENFORCED`), and the base class where it writes
4402
+ `table_type=` (`BaseSurrealEdge` for a relation table): those keys arrive in the lite's `SurrealConfigDict` with
4403
+ v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM: `Field(readonly=True)`).
4361
4404
  - **`RecordID` instead of `ForeignKey`/`ReferencesField`**; no `VectorField` or `Encrypted`; `computed()` instead
4362
4405
  of `Computed()`; `Duration`, `UUID`, `Decimal` and the geometry classes instead of `str`, `dict` and `float`;
4363
4406
  nested fields become sub-models (full ORM: dotted attribute lines).
@@ -4488,7 +4531,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4488
4531
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4489
4532
  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
4490
4533
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4491
- 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.
4534
+ 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.
4492
4535
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4493
4536
 
4494
4537
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4607,6 +4650,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4607
4650
  | 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 |
4608
4651
  | DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
4609
4652
  | 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 |
4653
+ | `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 |
4610
4654
  | 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 |
4611
4655
 
4612
4656
  > **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.5"
3
+ version = "0.30.8"
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"