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.
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/CHANGELOG.md +139 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/PKG-INFO +88 -44
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/README.md +87 -43
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/pyproject.toml +1 -1
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/cache.py +21 -19
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/changefeed.py +6 -6
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_manager.py +33 -32
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/define_parser.py +35 -34
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/edge.py +8 -6
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/embedded.py +9 -7
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/functions.py +1 -1
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/introspection.py +58 -27
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/live.py +1 -1
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_base.py +172 -140
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_generator.py +150 -109
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/query_set.py +44 -43
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/routing.py +13 -13
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/schema_state.py +2 -1
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/subquery.py +27 -26
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/database.py +1 -1
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/time_travel.py +19 -18
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/transaction.py +11 -4
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/types.py +5 -5
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/utils.py +146 -6
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/.gitignore +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/LICENSE +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/Makefile +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.30.5 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {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.
|
|
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`
|
|
2251
|
-
|
|
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
|
|
2438
|
-
apply the row the server returns to the instance.
|
|
2439
|
-
|
|
2440
|
-
|
|
2441
|
-
|
|
2442
|
-
|
|
2443
|
-
|
|
2444
|
-
|
|
2445
|
-
|
|
2446
|
-
|
|
2447
|
-
|
|
2448
|
-
|
|
2449
|
-
|
|
2450
|
-
`
|
|
2451
|
-
|
|
2452
|
-
|
|
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;
|
|
2499
|
-
|
|
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`
|
|
4154
|
-
`statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
|
|
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`,
|
|
4157
|
-
`INFO FOR
|
|
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,
|
|
4233
|
-
|
|
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
|
|
4311
|
-
|
|
4312
|
-
|
|
4313
|
-
|
|
4314
|
-
|
|
4315
|
-
|
|
4316
|
-
`
|
|
4317
|
-
|
|
4318
|
-
|
|
4319
|
-
|
|
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(
|
|
4410
|
-
|
|
4411
|
-
`
|
|
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`
|
|
2200
|
-
|
|
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
|
|
2387
|
-
apply the row the server returns to the instance.
|
|
2388
|
-
|
|
2389
|
-
|
|
2390
|
-
|
|
2391
|
-
|
|
2392
|
-
|
|
2393
|
-
|
|
2394
|
-
|
|
2395
|
-
|
|
2396
|
-
|
|
2397
|
-
|
|
2398
|
-
|
|
2399
|
-
`
|
|
2400
|
-
|
|
2401
|
-
|
|
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;
|
|
2448
|
-
|
|
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`
|
|
4103
|
-
`statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
|
|
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`,
|
|
4106
|
-
`INFO FOR
|
|
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,
|
|
4182
|
-
|
|
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
|
|
4260
|
-
|
|
4261
|
-
|
|
4262
|
-
|
|
4263
|
-
|
|
4264
|
-
|
|
4265
|
-
`
|
|
4266
|
-
|
|
4267
|
-
|
|
4268
|
-
|
|
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(
|
|
4359
|
-
|
|
4360
|
-
`
|
|
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.
|