surreal-orm-lite 0.30.8__tar.gz → 0.31.0__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.8 → surreal_orm_lite-0.31.0}/CHANGELOG.md +164 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/PKG-INFO +299 -22
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/README.md +298 -21
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/__init__.py +5 -1
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/connection_manager.py +327 -19
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/define_parser.py +120 -12
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/model_base.py +147 -1
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/routing.py +6 -4
- surreal_orm_lite-0.31.0/src/surreal_orm_lite/schema.py +437 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/schema_state.py +11 -2
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/utils.py +94 -4
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/.gitignore +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/LICENSE +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/Makefile +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/introspection.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/model_generator.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/subquery.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.30.8 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,170 @@ 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.31.0] - 2026-10-19
|
|
9
|
+
|
|
10
|
+
Server-side events and DDL helpers: the ORM writes and applies `DEFINE EVENT` and
|
|
11
|
+
`DEFINE FUNCTION` statements from Python. Events are declared on the model, next to its fields,
|
|
12
|
+
and applied idempotently; stored functions are defined for `call_function()` to call. The same
|
|
13
|
+
code runs on SurrealDB 2.x, 3.x and the embedded engine; asynchronous events and `$input` are 3.x
|
|
14
|
+
only. The second minor of Tier 3.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **`Event(name, *, then, when=None, async_mode=False, retry=None, max_depth=None, comment=None)`**
|
|
19
|
+
and **`SurrealConfigDict(events=[...])`**: a model declares its server-side events, which
|
|
20
|
+
SurrealDB runs on every `CREATE`, `UPDATE` and `DELETE` of the table, whoever writes it (the
|
|
21
|
+
ORM, a raw query or another client). `Model.event_ddl()` renders their `DEFINE EVENT` statements
|
|
22
|
+
without a connection, `await Model.define_events()` applies them on the model's connection
|
|
23
|
+
(`DEFINE EVENT OVERWRITE`: run it at start-up) and returns them, and
|
|
24
|
+
`await Model.remove_event("name")` removes one by name, declared or not. `overwrite=False` writes
|
|
25
|
+
`IF NOT EXISTS`, `missing_ok=False` raises `SurrealDbNotFoundError` for a missing event, and
|
|
26
|
+
`Model.get_events()` lists the declared events. A subclass inherits `events` unless it sets its
|
|
27
|
+
own, and typed edges take events too.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
class Account(BaseSurrealModel):
|
|
31
|
+
model_config = SurrealConfigDict(
|
|
32
|
+
table_name="account",
|
|
33
|
+
events=[
|
|
34
|
+
Event(
|
|
35
|
+
"email_audit",
|
|
36
|
+
when="$event = 'UPDATE' AND $before.email != $after.email",
|
|
37
|
+
then="CREATE audit_log SET account = $value.id, old = $before.email, new = $after.email",
|
|
38
|
+
),
|
|
39
|
+
Event(
|
|
40
|
+
"no_negative_balance",
|
|
41
|
+
when="$event != 'DELETE' AND $after.balance < 0",
|
|
42
|
+
then="THROW 'balance cannot be negative'",
|
|
43
|
+
),
|
|
44
|
+
],
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
id: str | None = None
|
|
48
|
+
email: str
|
|
49
|
+
balance: int = 0
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
Account.event_ddl() # the DEFINE EVENT statements, no connection needed
|
|
53
|
+
await Account.define_events() # idempotent
|
|
54
|
+
await Account(id="ada", email="ada@example.com", balance=-5).save() # InternalError: refused
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- **`SurrealDBConnectionManager.define_event(event, table)`** and
|
|
58
|
+
**`remove_event(event, table)`** apply an `Event` to any table, with or without a model, on the
|
|
59
|
+
current connection (the `using()` block's, else `"default"`); `event.ddl(table)` renders the
|
|
60
|
+
statement. The `then` clause is always written as a block (`THEN { … }`), so several statements,
|
|
61
|
+
`LET` and `THROW` work on both lines.
|
|
62
|
+
- **Asynchronous events (SurrealDB 3.x)**: `Event(..., async_mode=True, retry=3, max_depth=2)`
|
|
63
|
+
writes `ASYNC RETRY 3 MAXDEPTH 2`. Such an event runs after the write's transaction commits, so
|
|
64
|
+
it does not hold the write up. On SurrealDB 2.x and the embedded engine, which cannot parse
|
|
65
|
+
`ASYNC`, every applier raises `SurrealDbError` before sending any DDL, and no event of the call
|
|
66
|
+
is defined; `event.ddl()` renders an asynchronous event on any line.
|
|
67
|
+
- **`SurrealDBConnectionManager.define_function(function, body, *, parameters=None, ...)`**,
|
|
68
|
+
**`remove_function(function)`** and the pure **`function_ddl()`** (exported from
|
|
69
|
+
`surreal_orm_lite`): stored functions defined from Python, named as `call_function()` names them
|
|
70
|
+
(`"greet"`, `"fn::greet"`, `"fn::billing::total"`). `parameters` maps each parameter name to its
|
|
71
|
+
SurrealQL kind in declaration order, the order of `call_function()`'s positional `args`;
|
|
72
|
+
`returns` is the result's kind, `permissions` is `"FULL"`, `"NONE"` or `"WHERE <condition>"`,
|
|
73
|
+
and `comment=` and `overwrite=` work as for events.
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
await SurrealDBConnectionManager.define_function(
|
|
77
|
+
"fn::greet",
|
|
78
|
+
"RETURN string::concat('Hello, ', $name, '!');",
|
|
79
|
+
parameters={"name": "string"},
|
|
80
|
+
returns="string",
|
|
81
|
+
)
|
|
82
|
+
await SurrealDBConnectionManager.call_function("fn::greet", ["Ada"]) # 'Hello, Ada!'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
- **Every applier takes `tx=`** and returns the statement it applied (`define_events()`: the
|
|
86
|
+
list). A refusal raises
|
|
87
|
+
`SurrealDbAuthenticationError` when the session may not define (a `VIEWER`, a record user, an
|
|
88
|
+
anonymous session), `SurrealDbNotFoundError` for a removal of a missing definition with
|
|
89
|
+
`missing_ok=False`, and `SurrealDbError` otherwise
|
|
90
|
+
(`Can't apply event definition: 'email_audit' on table 'account' -> …`). Without `tx=`, a
|
|
91
|
+
refusal names the event and its table, or the function, never the statement, whose `when`,
|
|
92
|
+
`then` or body may hold a secret, and gives the server's reason without its excerpt of the
|
|
93
|
+
statement. A buffered transaction (SurrealDB 2.x, HTTP, the embedded engine) only queues the
|
|
94
|
+
statement, so a refusal comes back when the block commits, as the transaction's own error, never
|
|
95
|
+
as `SurrealDbAuthenticationError` or `SurrealDbNotFoundError`, `missing_ok=False` included. When
|
|
96
|
+
a definition is applied in a transaction (`tx=`), an error raised when the transaction ends can
|
|
97
|
+
still carry the server's message, statement excerpt included (#278). `define_events()` applies
|
|
98
|
+
one statement per event and stops at the first refusal: pass `tx=` for all or nothing. A `tx=`
|
|
99
|
+
of another connection raises `SurrealDbError` before any request.
|
|
100
|
+
- README section 32, "Server-side events and stored functions (`Event`, `define_events()`,
|
|
101
|
+
`define_function()`)" (declaring events on a model, events without a model, asynchronous events,
|
|
102
|
+
stored functions, transactions and connections, SurrealDB 2.x and 3.x, security, a note for users
|
|
103
|
+
of the full SurrealDB-ORM), a features row, seven rows in the 2.x/3.x behaviour table and one in
|
|
104
|
+
the embedded-engine table, the comparison and roadmap rows, and the example notebook
|
|
105
|
+
`examples/v0.31.0_events_ddl_helpers.ipynb`. Section 17's example declares its function with
|
|
106
|
+
`define_function()`.
|
|
107
|
+
|
|
108
|
+
### Changed
|
|
109
|
+
|
|
110
|
+
- **`EventState` gains `async_mode`, `retry` and `max_depth`** (keyword-only, after `comment`;
|
|
111
|
+
`False`, `None` and `None` by default), and **`DatabaseIntrospector` reads SurrealDB 3.x
|
|
112
|
+
`ASYNC` events**: 0.30.x reported such an event as a `SchemaIssue`. SurrealDB 3.x renders
|
|
113
|
+
`RETRY` and `MAXDEPTH` with every `ASYNC`, so an event defined without them reads back
|
|
114
|
+
`retry=1, max_depth=3`.
|
|
115
|
+
- **`call_function(params=)` follows a redefinition made with `define_function()` or
|
|
116
|
+
`remove_function()` at once**: both drop the function's cached signature on every connection of
|
|
117
|
+
this process to the same namespace and database, whatever its URL (an admin connection applying
|
|
118
|
+
the DDL over `http://` and the application's `ws://` connection alike), so even a reorder of the
|
|
119
|
+
same parameter names is picked up. A signature read that such a drop, or
|
|
120
|
+
`clear_function_signature_cache()`, overtakes is read again rather than cached. A function
|
|
121
|
+
redefined with raw DDL or from another process still needs `clear_function_signature_cache()`.
|
|
122
|
+
|
|
123
|
+
### Notes
|
|
124
|
+
|
|
125
|
+
- **Names are validated and quoted, comments escaped**: event, table, parameter and function names
|
|
126
|
+
are checked as identifiers before any request, event and table names are written in backticks
|
|
127
|
+
(`update` or `delete` work as event names), and a comment is an escaped string literal. A
|
|
128
|
+
parameter name SurrealDB defines itself (`auth`, `session`, `this`, …) is refused.
|
|
129
|
+
- **Expressions are trusted application code, never user input.** `when`, `then`, function
|
|
130
|
+
bodies, kinds and permission conditions are written into the statement as given, since SurrealDB
|
|
131
|
+
takes no bound parameter in a definition. Their structural check (strings terminated, brackets
|
|
132
|
+
balanced, no NUL, no SurrealQL comment marker outside a literal, every `/` read as an operator,
|
|
133
|
+
no `;` outside brackets where one expression is expected) catches mistakes — unbalanced
|
|
134
|
+
brackets, a comment that would swallow the clauses the ORM appends, a second statement where one
|
|
135
|
+
expression is expected — and is not an injection defence. To use a value, read it from the
|
|
136
|
+
record (`$after.email`) or from a `DEFINE PARAM`. Every refusal is a `TypeError` or a
|
|
137
|
+
`ValueError` raised before any request. An `Event`'s `repr()` leaves out `when` and `then`, and
|
|
138
|
+
a refusal the server returns to a call without `tx=` names the event or the function, never its
|
|
139
|
+
statement (with `tx=`, see #278).
|
|
140
|
+
- **Kinds are written in canonical form**: `none | int` and `option<int>` are both written
|
|
141
|
+
`option<int>`, and a kind the ORM cannot read raises `ValueError` rather than being rewritten.
|
|
142
|
+
- **SurrealDB 2.x and 3.x**: `ASYNC` events are 3.x only (refused before any DDL elsewhere);
|
|
143
|
+
`$input` holds the fields the write sent on 3.x and is `NONE` on 2.x and the embedded engine; a
|
|
144
|
+
write that changes nothing fires no event, except on 3.x an `UPSERT` (the ORM's `upsert()` of an
|
|
145
|
+
unchanged record), which fires one `UPDATE` event; read back, each line renders event and
|
|
146
|
+
function definitions its own way (README section 32 and the 2.x/3.x table).
|
|
147
|
+
- **A write an event refuses** (a `THROW`, an error in `then`) raises the SDK's `InternalError`,
|
|
148
|
+
as any server refusal of a write does, and nothing is written. Every applier takes `tx=`, and
|
|
149
|
+
events work inside `transaction()` like any other statement.
|
|
150
|
+
- **Query cache, live queries and signals**: the query cache forgets the tables the ORM itself
|
|
151
|
+
writes, not the rows an event writes, so do not cache reads of a table events write, or call
|
|
152
|
+
`QueryCache.invalidate(Model)` after the write. Live queries see those rows. Applying DDL and the
|
|
153
|
+
rows events write fire no ORM signal.
|
|
154
|
+
- **Applying a definition needs a privileged system user** (root, or a namespace or database
|
|
155
|
+
`OWNER` or `EDITOR`): run `define_events()` and `define_function()` at start-up or deployment.
|
|
156
|
+
- **Differences from the full SurrealDB-ORM**: events are declared in
|
|
157
|
+
`SurrealConfigDict(events=[...])` rather than a `class Meta`, and the lite's `Event` adds
|
|
158
|
+
`max_depth=`; `then` is written `THEN { … }` where the full ORM writes `THEN (…)`, in which `LET`
|
|
159
|
+
and `THROW` fail; names are quoted and comments escaped with a backslash; `define_function()`
|
|
160
|
+
has no full-ORM equivalent (the full ORM uses `RawSQL`).
|
|
161
|
+
- **Deferred**: the migration operations (`DefineEvent`, `RemoveEvent`, a function operation) and
|
|
162
|
+
the removal of events a model no longer declares come with v0.37.0 (migrations):
|
|
163
|
+
`define_events()` leaves such an event defined until `remove_event()` removes it.
|
|
164
|
+
`generate_models_from_db()` lists a table's events in a class comment, not as `events=[...]`.
|
|
165
|
+
- The `SurrealConfigDict` keys that generated classes stand in for with comments (`table_type`,
|
|
166
|
+
`permissions`, `changefeed`, `view_query`, `relation_in`, `relation_out`, `enforced`), which the
|
|
167
|
+
0.30.0 and 0.30.8 notes placed in v0.31.0–v0.33.0, are not part of this release: README section
|
|
168
|
+
31 now places them in v0.32.0–v0.34.0.
|
|
169
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
|
|
170
|
+
plus 3.1.5 for backward compatibility.
|
|
171
|
+
|
|
8
172
|
## [0.30.8] - 2026-10-19
|
|
9
173
|
|
|
10
174
|
Follow-ups to the v0.30.0 schema introspection (#260): a connection lost while the schema is read
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.31.0
|
|
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
|
|
@@ -265,6 +265,7 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
|
|
|
265
265
|
| Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
|
|
266
266
|
| Multiple databases (named connections, `using()`) | ✅ |
|
|
267
267
|
| Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
|
|
268
|
+
| Server-side events & function DDL (`Event`, `define_function()`) | ✅ |
|
|
268
269
|
|
|
269
270
|
### Supported Filter Lookups
|
|
270
271
|
|
|
@@ -1037,14 +1038,15 @@ query parameters**, never formatted into the statement.
|
|
|
1037
1038
|
```python
|
|
1038
1039
|
from surreal_orm_lite import SurrealDBConnectionManager
|
|
1039
1040
|
|
|
1040
|
-
# Declare it once (
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
""",
|
|
1041
|
+
# Declare it once: define_function() writes DEFINE FUNCTION OVERWRITE (section 32)
|
|
1042
|
+
await SurrealDBConnectionManager.define_function(
|
|
1043
|
+
"fn::acquire_lock",
|
|
1044
|
+
"""
|
|
1045
|
+
UPSERT type::record("lock:⟨" + $table_id + "⟩") SET holder = $pod_id, ttl = $ttl;
|
|
1046
|
+
RETURN { acquired: true, holder: $pod_id };
|
|
1047
|
+
""",
|
|
1048
|
+
parameters={"table_id": "string", "pod_id": "string", "ttl": "int"},
|
|
1049
|
+
)
|
|
1048
1050
|
|
|
1049
1051
|
# Positional — SurrealQL's own calling convention
|
|
1050
1052
|
lock = await SurrealDBConnectionManager.call_function(
|
|
@@ -1123,15 +1125,20 @@ at call time and surfaces at commit as `SurrealDbError`.
|
|
|
1123
1125
|
> without them `type::record("lock:" + $id)` truncates an id containing a hyphen (`"table-1"`
|
|
1124
1126
|
> becomes `table`) on 3.x and is rejected outright on 2.6.x.
|
|
1125
1127
|
|
|
1126
|
-
Signature caching is transparent
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
`
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
`
|
|
1128
|
+
Signature caching is transparent. `define_function()` and `remove_function()`
|
|
1129
|
+
([section 32](#32-server-side-events-and-stored-functions-event-define_events-define_function)) drop the function's
|
|
1130
|
+
cached signature themselves, on every connection of this process to the same namespace and database, whatever its URL
|
|
1131
|
+
(`ws://` or `http://`, with or without `/rpc`, `localhost` or `127.0.0.1`), so the next call sees a redefinition made
|
|
1132
|
+
through them at once, even one that only changes the order of the same parameter names, and even on another connection
|
|
1133
|
+
than the one that applied the DDL. For a function redefined out of band — with raw DDL
|
|
1134
|
+
(`client.query("DEFINE FUNCTION …")`) or from another process — two helpers are available, both on the current
|
|
1135
|
+
connection: `SurrealDBConnectionManager.clear_function_signature_cache()` and `function_signature_cache_size()`. The
|
|
1136
|
+
cache is keyed by URL, namespace and database, so `set_url()`, `set_namespace()` and `set_database()` cannot serve a
|
|
1137
|
+
signature read elsewhere; it is cleared outright by `set_connection()` and `unset_connection()`. After an out-of-band
|
|
1138
|
+
redefinition, a signature whose parameter _names_ changed self-heals on its own — but one with the **same names in a
|
|
1139
|
+
different order** cannot be detected, since `params=` is a mapping and carries no order to compare against: call
|
|
1140
|
+
`clear_function_signature_cache()` on each connection that calls the function, or `params=` keeps binding in the stale
|
|
1141
|
+
order.
|
|
1135
1142
|
|
|
1136
1143
|
---
|
|
1137
1144
|
|
|
@@ -4451,7 +4458,7 @@ reads, stores, logs or writes them.
|
|
|
4451
4458
|
`SurrealConfigDict(permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`
|
|
4452
4459
|
(`# Permissions: …`, `# Changefeed: …`, `# View: AS …`, `# IN … OUT … ENFORCED`), and the base class where it writes
|
|
4453
4460
|
`table_type=` (`BaseSurrealEdge` for a relation table): those keys arrive in the lite's `SurrealConfigDict` with
|
|
4454
|
-
v0.
|
|
4461
|
+
v0.32.0–v0.34.0. `READONLY` is a comment too (full ORM: `Field(readonly=True)`).
|
|
4455
4462
|
- **`RecordID` instead of `ForeignKey`/`ReferencesField`**; no `VectorField` or `Encrypted`; `computed()` instead
|
|
4456
4463
|
of `Computed()`; `Duration`, `UUID`, `Decimal` and the geometry classes instead of `str`, `dict` and `float`;
|
|
4457
4464
|
nested fields become sub-models (full ORM: dotted attribute lines).
|
|
@@ -4460,6 +4467,266 @@ reads, stores, logs or writes them.
|
|
|
4460
4467
|
- **`overwrite=False` added**: `generate_models_from_db(path)` replaces an existing file as the full ORM does, here
|
|
4461
4468
|
atomically; `overwrite=False` refuses it with `FileExistsError`.
|
|
4462
4469
|
|
|
4470
|
+
### 32. Server-side events and stored functions (`Event`, `define_events()`, `define_function()`)
|
|
4471
|
+
|
|
4472
|
+
Since v0.31.0 the ORM defines two kinds of objects that SurrealDB runs itself. An **event** runs SurrealQL inside
|
|
4473
|
+
the database whenever a record of its table is created, updated or deleted, whoever writes it — the ORM, a raw query
|
|
4474
|
+
or another client: an audit row, a guard that refuses a write, a message for an outbox. A **stored function**
|
|
4475
|
+
(`fn::…`) is SurrealQL that `call_function()` calls ([section 17](#17-stored-functions-call_function)). Events are
|
|
4476
|
+
declared next to the model, in `SurrealConfigDict(events=[…])`; the ORM writes their `DEFINE EVENT` statements with
|
|
4477
|
+
quoted names and expressions checked for mistakes, applies them idempotently, and section 31's introspection reads
|
|
4478
|
+
them back ([section 31](#31-schema-introspection-databaseintrospector-generate_models_from_db)). The same code runs on
|
|
4479
|
+
SurrealDB 2.x, 3.x and the embedded engine; asynchronous events and `$input` are 3.x only. The examples assume a
|
|
4480
|
+
configured connection: they run as written on the embedded engine (`mem://`), a 2.x core, which is why the
|
|
4481
|
+
asynchronous example prints a refusal.
|
|
4482
|
+
|
|
4483
|
+
#### Declaring events on a model
|
|
4484
|
+
|
|
4485
|
+
```python
|
|
4486
|
+
from surrealdb import ServerError
|
|
4487
|
+
|
|
4488
|
+
from surreal_orm_lite import BaseSurrealModel, Event, SurrealConfigDict, SurrealDBConnectionManager
|
|
4489
|
+
|
|
4490
|
+
|
|
4491
|
+
class Account(BaseSurrealModel):
|
|
4492
|
+
model_config = SurrealConfigDict(
|
|
4493
|
+
table_name="account",
|
|
4494
|
+
events=[
|
|
4495
|
+
Event(
|
|
4496
|
+
"email_audit",
|
|
4497
|
+
when="$event = 'UPDATE' AND $before.email != $after.email",
|
|
4498
|
+
then="CREATE audit_log SET account = $value.id, old = $before.email, new = $after.email",
|
|
4499
|
+
comment="Keeps every e-mail change",
|
|
4500
|
+
),
|
|
4501
|
+
Event(
|
|
4502
|
+
"no_negative_balance",
|
|
4503
|
+
when="$event != 'DELETE' AND $after.balance < 0",
|
|
4504
|
+
then="THROW 'balance cannot be negative'",
|
|
4505
|
+
),
|
|
4506
|
+
],
|
|
4507
|
+
)
|
|
4508
|
+
|
|
4509
|
+
id: str | None = None
|
|
4510
|
+
email: str
|
|
4511
|
+
balance: int = 0
|
|
4512
|
+
|
|
4513
|
+
|
|
4514
|
+
for statement in Account.event_ddl():
|
|
4515
|
+
print(statement)
|
|
4516
|
+
# DEFINE EVENT OVERWRITE `email_audit` ON `account` WHEN $event = 'UPDATE' AND $before.email != $after.email THEN { CREATE audit_log SET account = $value.id, old = $before.email, new = $after.email } COMMENT 'Keeps every e-mail change';
|
|
4517
|
+
# DEFINE EVENT OVERWRITE `no_negative_balance` ON `account` WHEN $event != 'DELETE' AND $after.balance < 0 THEN { THROW 'balance cannot be negative' };
|
|
4518
|
+
|
|
4519
|
+
await Account.define_events() # idempotent (OVERWRITE): run it at start-up
|
|
4520
|
+
|
|
4521
|
+
account = Account(id="ada", email="ada@old.example", balance=10)
|
|
4522
|
+
await account.save()
|
|
4523
|
+
await account.merge(email="ada@new.example")
|
|
4524
|
+
client = await SurrealDBConnectionManager.get_client()
|
|
4525
|
+
print(await client.query("SELECT old, new FROM audit_log;", {}))
|
|
4526
|
+
# [{'new': 'ada@new.example', 'old': 'ada@old.example'}]
|
|
4527
|
+
|
|
4528
|
+
try:
|
|
4529
|
+
await account.merge(balance=-5)
|
|
4530
|
+
except ServerError as exc: # the event refused the write: nothing changed
|
|
4531
|
+
print(type(exc).__name__)
|
|
4532
|
+
# InternalError
|
|
4533
|
+
```
|
|
4534
|
+
|
|
4535
|
+
- `then` is the SurrealQL the event runs: one statement, or several separated by `;`. The ORM always writes it as a
|
|
4536
|
+
block (`{ … }`), so several statements, `LET` and `THROW` work on both lines. `when` is one expression; left out,
|
|
4537
|
+
the event runs on every write (SurrealDB reads it back as `WHEN true`).
|
|
4538
|
+
- Inside the event, `$event` is `'CREATE'`, `'UPDATE'` or `'DELETE'`; `$before` and `$after` are the record before
|
|
4539
|
+
and after the write (`NONE` before a create and after a delete), `$value` is the record (as it was, for a delete),
|
|
4540
|
+
and on SurrealDB 3.x `$input` holds the fields the write sent. Expressions name **columns**: a field declared with
|
|
4541
|
+
`Field(alias=…)` is read by its alias.
|
|
4542
|
+
- A guard on `$after` names `$event != 'DELETE'`, as `no_negative_balance` does: after a delete `$after.balance` is
|
|
4543
|
+
`NONE`, and `NONE < 0` is true, so without it the guard would refuse every delete.
|
|
4544
|
+
- Event and table names are written quoted, so `update` or `delete` work as event names; a comment is written as an
|
|
4545
|
+
escaped string literal.
|
|
4546
|
+
- `define_events()` writes `DEFINE EVENT OVERWRITE`: it is idempotent, so run it at start-up or deployment.
|
|
4547
|
+
`overwrite=False` writes `IF NOT EXISTS` instead and keeps an event already defined. It applies one statement per
|
|
4548
|
+
event and stops at the first refusal, the earlier events staying defined: pass `tx=` for all or nothing. It returns
|
|
4549
|
+
the statements it applied, which `event_ddl()` renders without a connection.
|
|
4550
|
+
- `Account.remove_event("email_audit")` removes one event (`REMOVE EVENT IF EXISTS`; with `missing_ok=False` an
|
|
4551
|
+
event that does not exist raises `SurrealDbNotFoundError`). An event the model no longer declares stays defined
|
|
4552
|
+
until it is removed: `define_events()` does not compare the database with the model (that comes with migrations,
|
|
4553
|
+
v0.37.0).
|
|
4554
|
+
- A subclass inherits `events` and defines them on its own table, unless it sets its own (`events=[]` for none).
|
|
4555
|
+
Typed edges (`BaseSurrealEdge`) take events too: they fire on the edge table. Defining an event on a table that
|
|
4556
|
+
does not exist creates the table, `SCHEMALESS`.
|
|
4557
|
+
- A write that an event refuses (a `THROW`, or an error in `then`) raises the SDK's `InternalError`, and nothing is
|
|
4558
|
+
written. The rows an event writes are written by the server: they fire no ORM signal.
|
|
4559
|
+
|
|
4560
|
+
#### Events without a model
|
|
4561
|
+
|
|
4562
|
+
```python
|
|
4563
|
+
stock_guard = Event(
|
|
4564
|
+
"stock_guard", when="$event != 'DELETE' AND $after.stock < 0", then="THROW 'stock cannot go below zero'"
|
|
4565
|
+
)
|
|
4566
|
+
print(await SurrealDBConnectionManager.define_event(stock_guard, "product"))
|
|
4567
|
+
# DEFINE EVENT OVERWRITE `stock_guard` ON `product` WHEN $event != 'DELETE' AND $after.stock < 0 THEN { THROW 'stock cannot go below zero' };
|
|
4568
|
+
|
|
4569
|
+
await SurrealDBConnectionManager.remove_event("stock_guard", "product")
|
|
4570
|
+
await Account.remove_event("no_negative_balance") # declared or not: removal is by name
|
|
4571
|
+
```
|
|
4572
|
+
|
|
4573
|
+
- `SurrealDBConnectionManager.define_event(event, table)` applies an `Event` to any table and returns its statement;
|
|
4574
|
+
`remove_event(event, table)` removes one by name. Both run on the current connection (the `using()` block's, else
|
|
4575
|
+
`"default"`) and take `overwrite=` or `missing_ok=`, and `tx=`, as the model's methods do.
|
|
4576
|
+
- `event.ddl(table)` renders the statement without a connection (`overwrite=False` for `IF NOT EXISTS`).
|
|
4577
|
+
- An `Event` is frozen, hashable and compared by value; its `repr()` leaves out `when` and `then`, which may hold a
|
|
4578
|
+
secret such as a webhook token. Without `tx=`, a refusal leaves them out too: it names the event and its table,
|
|
4579
|
+
never the statement (`Can't apply event definition: 'stock_guard' on table 'product' -> …`), and gives the server's
|
|
4580
|
+
reason without its excerpt of the statement (a parse error keeps its line and column). With `tx=`, see
|
|
4581
|
+
[Transactions, connections and the query cache](#transactions-connections-and-the-query-cache).
|
|
4582
|
+
|
|
4583
|
+
#### Asynchronous events (SurrealDB 3.x)
|
|
4584
|
+
|
|
4585
|
+
```python
|
|
4586
|
+
from surreal_orm_lite import SurrealDbError
|
|
4587
|
+
|
|
4588
|
+
notify = Event(
|
|
4589
|
+
"notify_shipping",
|
|
4590
|
+
when="$event = 'CREATE'",
|
|
4591
|
+
then="CREATE outbox SET shipment = $value.id, at = time::now()",
|
|
4592
|
+
async_mode=True,
|
|
4593
|
+
retry=3,
|
|
4594
|
+
)
|
|
4595
|
+
print(notify.ddl("shipment"))
|
|
4596
|
+
# DEFINE EVENT OVERWRITE `notify_shipping` ON `shipment` ASYNC RETRY 3 WHEN $event = 'CREATE' THEN { CREATE outbox SET shipment = $value.id, at = time::now() };
|
|
4597
|
+
|
|
4598
|
+
try:
|
|
4599
|
+
await SurrealDBConnectionManager.define_event(notify, "shipment")
|
|
4600
|
+
except SurrealDbError as exc: # the embedded engine is a 2.x core, like a SurrealDB 2.x server
|
|
4601
|
+
print(exc)
|
|
4602
|
+
# ASYNC events need SurrealDB 3.x, and this connection runs the embedded engine (a SurrealDB 2.x core): 'notify_shipping' cannot be defined with async_mode=True. Drop async_mode, retry and max_depth, or connect to a SurrealDB 3.x server. Nothing was defined.
|
|
4603
|
+
```
|
|
4604
|
+
|
|
4605
|
+
- On SurrealDB 3.x an event with `async_mode=True` (`ASYNC`) runs after the write's transaction commits, never for a
|
|
4606
|
+
cancelled one, so it does not hold the write up, and a failing body does not refuse the write (its own writes are
|
|
4607
|
+
rolled back). Its row appears a few milliseconds after the commit: wait for it rather than reading it right after
|
|
4608
|
+
the write.
|
|
4609
|
+
- `retry` (`RETRY`) is how many times SurrealDB retries a failing body, 1 by default, and `max_depth` (`MAXDEPTH`) how
|
|
4610
|
+
deep a chain of asynchronous events may go, 3 by default; both take `0` to `65535` and need `async_mode=True`. Read
|
|
4611
|
+
back, an asynchronous event has `async_mode`, `retry` and `max_depth` set on its `EventState`, the defaults filled
|
|
4612
|
+
in.
|
|
4613
|
+
- On SurrealDB 2.x and the embedded engine, which cannot parse `ASYNC`, the ORM raises `SurrealDbError` before
|
|
4614
|
+
sending anything: no event of the call is defined. `event.ddl()` renders an asynchronous event on any line.
|
|
4615
|
+
|
|
4616
|
+
#### Stored functions: `define_function()`
|
|
4617
|
+
|
|
4618
|
+
```python
|
|
4619
|
+
await SurrealDBConnectionManager.define_function(
|
|
4620
|
+
"fn::greet",
|
|
4621
|
+
"RETURN string::concat('Hello, ', $name, '!');",
|
|
4622
|
+
parameters={"name": "string"},
|
|
4623
|
+
returns="string",
|
|
4624
|
+
comment="Says hello",
|
|
4625
|
+
)
|
|
4626
|
+
print(await SurrealDBConnectionManager.call_function("fn::greet", ["Ada"]))
|
|
4627
|
+
# Hello, Ada!
|
|
4628
|
+
|
|
4629
|
+
await SurrealDBConnectionManager.define_function(
|
|
4630
|
+
"fn::greet",
|
|
4631
|
+
"RETURN string::concat($greeting, ', ', $name, '!');",
|
|
4632
|
+
parameters={"greeting": "string", "name": "string"},
|
|
4633
|
+
returns="string",
|
|
4634
|
+
)
|
|
4635
|
+
print(await SurrealDBConnectionManager.call_function("fn::greet", params={"name": "Ada", "greeting": "Hi"}))
|
|
4636
|
+
# Hi, Ada!
|
|
4637
|
+
|
|
4638
|
+
await SurrealDBConnectionManager.remove_function("fn::greet")
|
|
4639
|
+
```
|
|
4640
|
+
|
|
4641
|
+
- `define_function()` runs on the current connection and names the function as `call_function()` does: `"greet"`,
|
|
4642
|
+
`"fn::greet"` or `"fn::billing::total"`. The body is always written as a block; `RETURN` gives the result.
|
|
4643
|
+
- `parameters` maps each parameter name, without the `$`, to its SurrealQL kind, in declaration order, which is the
|
|
4644
|
+
order of `call_function()`'s positional `args`. A name SurrealDB defines itself (`auth`, `session`, `this` …) is
|
|
4645
|
+
refused. Kinds are SurrealQL text, written in canonical form: `option<int>` is written `option<int>`, and so is
|
|
4646
|
+
`none | int`. A kind the ORM cannot read raises `ValueError`: it is never rewritten silently. `returns` is the
|
|
4647
|
+
result's kind.
|
|
4648
|
+
- `permissions` is `"FULL"`, `"NONE"` or `"WHERE <condition>"`, in any case; left out, SurrealDB applies `FULL`.
|
|
4649
|
+
- `call_function()` follows a redefinition at once: `define_function()` and `remove_function()` drop the signature
|
|
4650
|
+
`params=` had cached, even when only the order of the parameters changed, on every connection of this process to
|
|
4651
|
+
the same namespace and database, whatever its URL — the admin connection a `using()` block applies the DDL on and
|
|
4652
|
+
the application's connection alike, one over `http://` and the other over `ws://` included. A function redefined
|
|
4653
|
+
with raw DDL or from another process still needs `clear_function_signature_cache()` on each connection that calls
|
|
4654
|
+
it ([section 17](#17-stored-functions-call_function)).
|
|
4655
|
+
- `remove_function("fn::greet")` writes `REMOVE FUNCTION IF EXISTS`; with `missing_ok=False` a function that does not
|
|
4656
|
+
exist raises `SurrealDbNotFoundError`. `overwrite=False` writes `IF NOT EXISTS` and keeps the function already
|
|
4657
|
+
defined.
|
|
4658
|
+
- `function_ddl()` takes the same arguments, without `tx=`, and returns the statement without applying it. Without
|
|
4659
|
+
`tx=`, a body the server refuses raises `SurrealDbError` (`Can't apply function definition: 'fn::greet' -> …`),
|
|
4660
|
+
which names the function, never its body.
|
|
4661
|
+
|
|
4662
|
+
#### Transactions, connections and the query cache
|
|
4663
|
+
|
|
4664
|
+
- Every method that applies DDL takes `tx=`. In a buffered transaction (SurrealDB 2.x, HTTP, the embedded engine)
|
|
4665
|
+
the statements are applied at commit, and an event defined in the block fires for the block's later writes; in an
|
|
4666
|
+
interactive one (WebSocket and SurrealDB 3.x) they are applied in the transaction, whose own writes fire the event.
|
|
4667
|
+
Either way, a block that raises leaves nothing defined, and nothing is visible outside the block until it commits.
|
|
4668
|
+
- Inside the transaction that defines a function, call it with positional `args`: `params=` reads the signature from
|
|
4669
|
+
the committed schema.
|
|
4670
|
+
- A model's methods run on the model's connection (its `connection` key, or the `using()` block's); the manager's
|
|
4671
|
+
methods on the current connection. A `tx=` of another connection raises `SurrealDbError` before any request.
|
|
4672
|
+
- Defining needs a system user allowed to do it: root, or a namespace or database `OWNER` or `EDITOR`. On a server,
|
|
4673
|
+
a `VIEWER`, a record user or an anonymous session gets `SurrealDbAuthenticationError`. A buffered transaction
|
|
4674
|
+
(SurrealDB 2.x, HTTP, the embedded engine) only queues the statement, so a refusal comes back when the block
|
|
4675
|
+
commits, as the transaction's own error, never as `SurrealDbAuthenticationError` or `SurrealDbNotFoundError`,
|
|
4676
|
+
`missing_ok=False` included. When a definition is applied in a transaction (`tx=`), an error raised when the
|
|
4677
|
+
transaction ends can still carry the server's message, statement excerpt included ([#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)).
|
|
4678
|
+
- Live queries see the rows an event writes (`watch()` on their table). The query cache
|
|
4679
|
+
([section 29](#29-query-cache-cache-querycache)) does not: it forgets the tables the ORM itself writes, so a cached
|
|
4680
|
+
read of a table that events write stays as it was until its time to live runs out. Do not cache such reads, or call
|
|
4681
|
+
`QueryCache.invalidate(Model)` after the write.
|
|
4682
|
+
- Applying DDL fires no signal, and neither do the rows events write.
|
|
4683
|
+
|
|
4684
|
+
#### SurrealDB 2.x and 3.x
|
|
4685
|
+
|
|
4686
|
+
- Asynchronous events (`ASYNC`) are 3.x only: on SurrealDB 2.x and the embedded engine the ORM raises
|
|
4687
|
+
`SurrealDbError` before any DDL.
|
|
4688
|
+
- `$input` holds the fields the write sent on 3.x (`{ name: 'a' }` for `SET name = 'a'`); it is `NONE` on 2.x and
|
|
4689
|
+
the embedded engine.
|
|
4690
|
+
- A write that changes nothing fires no event, except on 3.x an `UPSERT` — the ORM's `upsert()` of an unchanged
|
|
4691
|
+
record — which fires one `UPDATE` event.
|
|
4692
|
+
- Read back (section 31), each line renders the definitions its own way: on 3.x a block is one line and a single
|
|
4693
|
+
statement loses its `;`, on 2.x a block of several statements spans several lines; an optional parameter reads
|
|
4694
|
+
`none | int` on 3.x and `option<int>` on 2.x. The [2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x) lists the
|
|
4695
|
+
differences.
|
|
4696
|
+
|
|
4697
|
+
#### Security
|
|
4698
|
+
|
|
4699
|
+
Event, table and parameter names are checked as identifiers before any request, and event and table names are
|
|
4700
|
+
written quoted; a comment is written as an escaped string literal. Expressions — `when`, `then`, function bodies,
|
|
4701
|
+
kinds and permission conditions — are written into the statement as they are, since SurrealDB takes no bound
|
|
4702
|
+
parameter in a definition. Before any request the ORM checks their structure: string literals and quoted identifiers
|
|
4703
|
+
terminated, brackets balanced, no NUL character, no SurrealQL comment marker (`--`, `#`, `//`, `/* */`) outside a
|
|
4704
|
+
literal, and no `;` outside brackets where one expression is expected (`when`, a permission condition). It reads
|
|
4705
|
+
every `/` as an operator, so a regex literal whose pattern holds an unbalanced bracket, a quote or a comment marker
|
|
4706
|
+
is refused. The check catches mistakes — unbalanced brackets, a comment that would
|
|
4707
|
+
swallow the clauses the ORM appends, a second statement where one expression is expected — and is not an injection
|
|
4708
|
+
defence: expressions are trusted application code, never user input. To use a value, read it from the record
|
|
4709
|
+
(`$after.email`) or from a `DEFINE PARAM`, never format it into the text. Kinds are parsed and written in canonical
|
|
4710
|
+
form. An `Event`'s `repr()` leaves out its expressions, and a refusal raised without `tx=` names the event or the
|
|
4711
|
+
function, never its statement; with `tx=`, an error raised when the transaction ends can still carry the server's
|
|
4712
|
+
message, statement excerpt included ([#278](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/278)). Applying a definition needs a privileged system user: run
|
|
4713
|
+
`define_events()` and `define_function()` at start-up or deployment, not on a record user's session.
|
|
4714
|
+
|
|
4715
|
+
#### Coming from the full SurrealDB-ORM
|
|
4716
|
+
|
|
4717
|
+
- **`DefineEvent(name, table, when, then, comment)`** becomes `Event(name, when=…, then=…, comment=…).ddl(table)` to
|
|
4718
|
+
render it, or `await SurrealDBConnectionManager.define_event(event, table)` to apply it; `RemoveEvent(name, table)`
|
|
4719
|
+
becomes `await SurrealDBConnectionManager.remove_event(event, table)`, whose first parameter is named `event`.
|
|
4720
|
+
- **The documented `Event(…, async_mode=True, retry=3)`** is the lite's `Event`, with `max_depth=` added, declared in
|
|
4721
|
+
`model_config = SurrealConfigDict(events=[…])` rather than in a `class Meta`.
|
|
4722
|
+
- **`then` is a block**: the ORM writes `THEN { … }` where the full ORM writes `THEN (…)`, in which `LET` and `THROW`
|
|
4723
|
+
fail (SurrealDB 2.x refuses the definition, 3.x every write to the table).
|
|
4724
|
+
- **Names are quoted, and comments escaped with a backslash** (full ORM: names as written, and a quote doubled as
|
|
4725
|
+
`''`, which SurrealDB refuses).
|
|
4726
|
+
- **`define_function()` has no full-ORM equivalent**: the full ORM declares a function with `RawSQL`.
|
|
4727
|
+
- **The migration operations** (`DefineEvent`, `RemoveEvent`, `RawSQL`) and the removal of the events a model no
|
|
4728
|
+
longer declares **come with migrations (v0.37.0)**.
|
|
4729
|
+
|
|
4463
4730
|
---
|
|
4464
4731
|
|
|
4465
4732
|
## Configuration Options
|
|
@@ -4582,7 +4849,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4582
4849
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4583
4850
|
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
|
|
4584
4851
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
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.
|
|
4852
|
+
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
|
|
4586
4853
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4587
4854
|
|
|
4588
4855
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4702,6 +4969,13 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4702
4969
|
| DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
|
|
4703
4970
|
| 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
4971
|
| `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 |
|
|
4972
|
+
| Server-side events (`define_events()`, `define_event()`, `remove_event()`) | same on both lines: defined, fired on `CREATE`, `UPDATE` and `DELETE`, `WHEN` honoured; `$event`, `$before`, `$after`, `$value` alike | the same; names are quoted, so `update` or `delete` work as event names (3.x refuses them bare) | v0.31.0 |
|
|
4973
|
+
| Asynchronous events (`Event(async_mode=True, retry=…, max_depth=…)`) | `SurrealDbError` before any DDL: 2.x cannot parse `ASYNC` | run after the write's transaction commits, never for a cancelled one; read back with `async_mode`, `retry`, `max_depth` | v0.31.0 |
|
|
4974
|
+
| `$input` in an event | `NONE` | the fields the write sent (`{ name: 'a' }` for `SET name = 'a'`) | v0.31.0 |
|
|
4975
|
+
| A write that changes nothing, on a table with an event | fires no event | fires no event, except an `UPSERT` (the ORM's `upsert()`): one `UPDATE` event | v0.31.0 |
|
|
4976
|
+
| An event whose `THEN` fails (a `THROW`, an error) | the write is refused; the SDK's `InternalError` (`An error occurred: …` for a `THROW`, the bare cause otherwise) | the write is refused; the SDK's `InternalError` (`Error while processing event <name>: …`) | v0.31.0 |
|
|
4977
|
+
| Event and function definitions read back (`EventState`, `FunctionState`) | a block on several lines, each statement ending with `;`; `option<T>` parameters as written | a block on one line, no `;` after a single statement; optional parameters rendered with `none` first | v0.31.0 |
|
|
4978
|
+
| `define_function()`, `remove_function()` and `call_function()` | same on both lines: the next `call_function()` sees a redefinition on every connection of this process to the same namespace and database, whatever its URL | the same | v0.31.0 |
|
|
4705
4979
|
| 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 |
|
|
4706
4980
|
|
|
4707
4981
|
> **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.
|
|
@@ -4734,6 +5008,7 @@ Capabilities not listed behave as on a 2.x server.
|
|
|
4734
5008
|
| Time travel (`as_of()`) | `surrealkv+versioned://` only (`?versioned=true` is ignored by SDK 2.0.0); any other URL → `SurrealDbError` before any request; `fetch()` refused (2.x core) | versioned storage required (see the 2.x/3.x table) | v0.26.0 |
|
|
4735
5009
|
| Several connections (`add_connection()`) | `mem://`: each name is a database of its own; an on-disk store (`surrealkv://`, `file://`) is open under one name at a time — a second name raises `SurrealDbConnectionError` | each name opens its own clients; two databases on one server are isolated | v0.29.0 |
|
|
4736
5010
|
| Schema introspection (`DatabaseIntrospector`) | reads like a 2.x server (core 2.3.10): same state and same generated model types as on the servers; the anonymous owner session may run `INFO`; `COUNT` indexes cannot be defined | need a system user (root, namespace or database user) | v0.30.0 |
|
|
5011
|
+
| Server-side events and stored functions (v0.31.0) | as on a 2.x server: `$input` is `NONE`; `Event(async_mode=True)` raises `SurrealDbError` before any DDL | `ASYNC` events on 3.x | v0.31.0 |
|
|
4737
5012
|
| Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
|
|
4738
5013
|
|
|
4739
5014
|
---
|
|
@@ -4779,7 +5054,8 @@ Contributions are welcome! Please:
|
|
|
4779
5054
|
| v0.28.0 | Query cache | ✅ Released |
|
|
4780
5055
|
| v0.29.0 | Tier 2 — Multi-database | ✅ Released |
|
|
4781
5056
|
| v0.30.0 | Tier 3 — Schema introspection | ✅ Released |
|
|
4782
|
-
| v0.31.0
|
|
5057
|
+
| v0.31.0 | Tier 3 — Server-side events and DDL helpers | ✅ Released |
|
|
5058
|
+
| v0.32.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
|
|
4783
5059
|
| v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
|
|
4784
5060
|
| v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
|
|
4785
5061
|
|
|
@@ -4833,7 +5109,8 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
4833
5109
|
| Query Cache | ✅ v0.28.0 (`cache()`, `QueryCache`) | ✅ |
|
|
4834
5110
|
| Multi-database | ✅ v0.29.0 (`add_connection()`, `using()`) | ✅ |
|
|
4835
5111
|
| Schema Introspection | ✅ v0.30.0 (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
|
|
4836
|
-
| DEFINE EVENT | v0.31.0
|
|
5112
|
+
| DEFINE EVENT | ✅ v0.31.0 (`Event`, `define_events()`, `ASYNC` on 3.x) | ✅ migrations (`DefineEvent`) |
|
|
5113
|
+
| `define_function()` (DDL) | ✅ v0.31.0 | ❌ |
|
|
4837
5114
|
| Materialized views | v0.32.0 | ✅ |
|
|
4838
5115
|
| Full-Text Search | v0.34.0 | ✅ |
|
|
4839
5116
|
| Vector Search (KNN/HNSW) | v0.35.0 | ✅ |
|