surreal-orm-lite 0.24.3__tar.gz → 0.25.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.24.3 → surreal_orm_lite-0.25.0}/CHANGELOG.md +144 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/PKG-INFO +336 -21
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/README.md +335 -20
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/_sdk.py +14 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/changefeed.py +10 -1
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/connection_manager.py +640 -84
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/embedded.py +124 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/live.py +7 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_auth.py +279 -26
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/query_set.py +6 -3
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/__init__.py +28 -0
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/database.py +59 -0
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/fixtures.py +139 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/utils.py +3 -2
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/.gitignore +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/LICENSE +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/Makefile +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,150 @@ 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.25.0] - 2026-10-15
|
|
9
|
+
|
|
10
|
+
Embedded test engine: the ORM also runs on the official SDK's in-process SurrealDB engine
|
|
11
|
+
(`mem://`, `surrealkv://<path>`), with no server and no Docker, and the new
|
|
12
|
+
`surreal_orm_lite.testing` module adds `embedded_database()` and the full SurrealDB-ORM's
|
|
13
|
+
`SurrealFixture` / `@fixture`. The same models and queries run unchanged against a server. The
|
|
14
|
+
third minor of Tier 2.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **Embedded URLs.** With
|
|
19
|
+
`SurrealDBConnectionManager.set_connection(url="mem://", namespace=…, database=…)`, every ORM
|
|
20
|
+
call runs in-process: CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields,
|
|
21
|
+
upsert and patch, server values, computed fields, stored functions, buffered transactions,
|
|
22
|
+
change feeds and authentication. The SDK sends `mem://`, `memory://`,
|
|
23
|
+
`surrealkv://<path>`, `surrealkv+versioned://<path>` and `file://<path>` (a SurrealKV store) to
|
|
24
|
+
its engine; the ORM asks the SDK's own URL parser and keeps no list of schemes. `user` and
|
|
25
|
+
`password` are optional on an embedded URL and never sent: the engine's anonymous session is the
|
|
26
|
+
in-process owner. They are kept, so one configuration switches between a server and `mem://` by
|
|
27
|
+
its URL alone:
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
|
|
31
|
+
|
|
32
|
+
SurrealDBConnectionManager.set_connection(url="mem://", namespace="app", database="app")
|
|
33
|
+
|
|
34
|
+
class Note(BaseSurrealModel):
|
|
35
|
+
id: str | None = None
|
|
36
|
+
title: str
|
|
37
|
+
|
|
38
|
+
await Note(id="docs", title="Write the docs").save()
|
|
39
|
+
assert await Note.objects().count() == 1
|
|
40
|
+
assert SurrealDBConnectionManager.is_embedded()
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- **`SurrealDBConnectionManager.is_embedded()`**: whether the configured URL addresses the
|
|
44
|
+
in-process engine, for code that must run on both kinds of connection.
|
|
45
|
+
- **One engine per process.** The manager opens the engine on the first call and hands it to every
|
|
46
|
+
event loop and thread, so they all see the same database; concurrent first calls open exactly
|
|
47
|
+
one. A namespace or database change resets the shared session and selects the new pair on the
|
|
48
|
+
same engine, with no data lost; a new URL closes the old engine. Closing
|
|
49
|
+
(`close_connection()`, `close_all_connections()`, `unset_connection()`, `reconnect()`, the exit
|
|
50
|
+
of `async with SurrealDBConnectionManager():`) discards a `mem://` database, and a
|
|
51
|
+
`surrealkv://` one reopens with its data. `validate_connection()` never discards it. Server
|
|
52
|
+
clients are untouched while an embedded URL is configured: `close_connection()`, `reconnect()`
|
|
53
|
+
and the `async with` exit then close only the engine, so a server client keeps its live queries
|
|
54
|
+
and its identity, even one signed in with `store=False`, and `is_connected()` stays true on its
|
|
55
|
+
event loop; `close_all_connections()` and `unset_connection()` close it too. An event loop whose
|
|
56
|
+
server connection dropped while signed in with `store=False` still raises once the server URL is
|
|
57
|
+
set back with `set_url()`, or after an `embedded_database()` block: neither closing the engine
|
|
58
|
+
nor an identity set on it ends that state. `set_connection()` does: a new configuration is a
|
|
59
|
+
choice of identity.
|
|
60
|
+
- **Clear errors, before any request, for what the engine cannot do**: live queries (`live()`,
|
|
61
|
+
`watch()`, `subscribe_live()`: read the table's change feed with `changes()` instead),
|
|
62
|
+
`changes(since=<datetime>)` (pass a cursor or `since=None`), and `AuthenticatedUserMixin` calls
|
|
63
|
+
with `bind=False` and `ephemeral_client()` (the engine has a single session per database). Each
|
|
64
|
+
raises `SurrealDbError`.
|
|
65
|
+
- **Authentication on the engine.** `signin()`, `signup()`, `authenticate()` and `invalidate()`
|
|
66
|
+
work with the engine's record access methods and `DEFINE USER`s, and record users and table
|
|
67
|
+
`PERMISSIONS` apply as on a server. A sign-in changes the session of the whole process (every
|
|
68
|
+
event loop and thread); `invalidate()` and a namespace or database change return it to the
|
|
69
|
+
in-process owner and end the stored session. Model auth with `bind=True` signs that session in,
|
|
70
|
+
one call at a time with the connection-level calls (the last one wins), and a failed call puts
|
|
71
|
+
the previous session back, with one exception, as on a server: when `signup()` or `signin()`
|
|
72
|
+
succeeded but the record does not fit the model, the session stays signed in as that record
|
|
73
|
+
(the error says so). `refresh()` cannot succeed on the engine: its SurrealQL does not parse
|
|
74
|
+
`WITH REFRESH`.
|
|
75
|
+
- **`surreal_orm_lite.testing`**, a new module that does not import pytest:
|
|
76
|
+
- `embedded_database(url="mem://", *, namespace="test", database="test")` runs a block against
|
|
77
|
+
an isolated in-process database, yields the block's SDK client (valid inside the block only),
|
|
78
|
+
then puts the previous connection back: its settings, stored session and engine. Blocks nest;
|
|
79
|
+
`surrealkv://<path>` gives an on-disk database. A server URL raises `ValueError`.
|
|
80
|
+
- `SurrealFixture` and `@fixture`, with the full SurrealDB-ORM's names: `load()` saves a fresh
|
|
81
|
+
copy of each declared instance in declaration order, yields them typed as the fixture class,
|
|
82
|
+
and deletes them on exit. It works on any connection, a server or the engine. Unlike the full
|
|
83
|
+
ORM, an explicit `id` is kept, a save that fails or is cancelled mid-load deletes the copies
|
|
84
|
+
already saved, `@fixture` raises `TypeError` on a class that is not a `SurrealFixture`
|
|
85
|
+
subclass, and `load()` raises `ValueError` on an undecorated subclass of a fixture that
|
|
86
|
+
declares instances of its own (the full ORM loads only the parent's).
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
from surreal_orm_lite.testing import SurrealFixture, embedded_database, fixture
|
|
90
|
+
|
|
91
|
+
@fixture
|
|
92
|
+
class UserFixtures(SurrealFixture):
|
|
93
|
+
alice = User(name="Alice", role="admin")
|
|
94
|
+
bob = User(id="bob", name="Bob", role="player") # an explicit id is kept
|
|
95
|
+
|
|
96
|
+
async with embedded_database(): # a fresh, empty in-memory database
|
|
97
|
+
async with UserFixtures.load() as fixtures:
|
|
98
|
+
admins = await User.objects().filter(role="admin").exec()
|
|
99
|
+
assert [admin.name for admin in admins] == ["Alice"]
|
|
100
|
+
assert await User.objects().count() == 0 # alice and bob are deleted
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- README section 26, "Embedded engine and test fixtures" (in-process databases and the embedded
|
|
104
|
+
URL table, one engine per process, what the engine does not do, its SurrealQL line, identity,
|
|
105
|
+
test fixtures with a pytest recipe, a note for users of the full SurrealDB-ORM), and a new
|
|
106
|
+
behaviour table, "ORM behaviour: the embedded engine"; example notebook
|
|
107
|
+
`examples/v0.25.0_embedded_test_engine.ipynb`.
|
|
108
|
+
|
|
109
|
+
### Changed
|
|
110
|
+
|
|
111
|
+
- `set_connection()`: `user`, `password`, `namespace` and `database` default to `None`, in the same
|
|
112
|
+
positional order. `is_connection_set()` needs the user and password for a server URL only.
|
|
113
|
+
- A URL the installed SDK refuses (`rocksdb://`, a typo) is still accepted by `set_connection()`;
|
|
114
|
+
the first ORM call now raises a `SurrealDbConnectionError` that quotes the SDK, before anything
|
|
115
|
+
is opened, instead of "Connection not been set." or "Can't connect to the database.". For
|
|
116
|
+
`rocksdb://` it points to #233.
|
|
117
|
+
- The DDL helpers (`define_computed_fields()`, `define_access()`) raise their usual
|
|
118
|
+
`SurrealDbError` for a statement the embedded engine cannot parse, which SDK 2.0.0 reports as a
|
|
119
|
+
bare `RuntimeError`.
|
|
120
|
+
- The `SurrealDbError` of an `AuthenticatedUserMixin` call whose record does not fit the model
|
|
121
|
+
(since v0.17.0) has a new text, on every path, the server lines included: it says whether the
|
|
122
|
+
shared session kept its previous identity or is now signed in as that record (for `refresh()`,
|
|
123
|
+
also that the refresh token passed in is spent and whether the new pair is kept), and it names
|
|
124
|
+
the fields that do not fit and Pydantic's error codes (`nickname: missing; prefs: int_parsing`),
|
|
125
|
+
and quotes nothing from the record: no value, and no key the model does not declare (listed as
|
|
126
|
+
`(undeclared field)`). The Pydantic `ValidationError` is its `__context__` instead of its
|
|
127
|
+
`__cause__`.
|
|
128
|
+
|
|
129
|
+
### Notes
|
|
130
|
+
|
|
131
|
+
- **The engine is SurrealDB core 2.3.10**, bundled with the surrealdb SDK 2.0.0 base wheel (no
|
|
132
|
+
new dependency, every supported Python version): write 2.x SurrealQL in raw queries and computed
|
|
133
|
+
fields, and expect the 2.x column of the behaviour table. `client.version()` reports the SDK's
|
|
134
|
+
version (`surrealdb-2.0.0`). Transactions are buffered, and parse errors in raw queries are a bare
|
|
135
|
+
`RuntimeError`. The SDK 3.0 line bundles a 3.x engine in the `surrealdb[embedded]` extra (#205).
|
|
136
|
+
- **`rocksdb://` is not yet supported by the official SDK** (#233): the ORM relays the SDK's
|
|
137
|
+
refusal and will accept the scheme with no change once a released SDK does. A bare `memory` (no
|
|
138
|
+
`://`) is refused by SDK 2.0.0: write `memory://`. `surrealkv+versioned://` behaves as
|
|
139
|
+
`surrealkv://` until time travel (v0.26.0).
|
|
140
|
+
- **With the surrealdb SDK 2.x, closing does not stop an in-process engine**: a client obtained
|
|
141
|
+
before `close_connection()` or inside an `embedded_database()` block is still a running
|
|
142
|
+
database. Do not use it after the close, drop it (`del client`) before reopening the same
|
|
143
|
+
`surrealkv://` path, and never open one path from two processes.
|
|
144
|
+
- A fresh engine raises a retryable write conflict when several writes run concurrently on a table
|
|
145
|
+
that does not exist yet: define the table first, or use `@retry_on_conflict()`.
|
|
146
|
+
- The v0.24.3 read hook (#235) also applies to the embedded engine's client: zero durations and
|
|
147
|
+
degenerate geometries read as on a server. A `<set>[…]` is stored as an array there, as on 2.x.
|
|
148
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5
|
|
149
|
+
for backward compatibility; the embedded tests run in every CI job. `ModelFactory` and
|
|
150
|
+
`Faker` come in v0.39.0.
|
|
151
|
+
|
|
8
152
|
## [0.24.3] - 2026-10-15
|
|
9
153
|
|
|
10
154
|
The clients the ORM opens now read the values the surrealdb SDK 2.0.0 cannot decode (zero
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.25.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
|
|
@@ -72,12 +72,12 @@ This ORM is designed to:
|
|
|
72
72
|
|
|
73
73
|
## Requirements
|
|
74
74
|
|
|
75
|
-
| Dependency | Version
|
|
76
|
-
| ------------ |
|
|
77
|
-
| Python | 3.11+ (tested on 3.11 to 3.15)
|
|
78
|
-
| SurrealDB | 2.6.x / 2.7.x or 3.2.x / 3.3.x
|
|
79
|
-
| Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0
|
|
80
|
-
| Pydantic | >=2.13.4
|
|
75
|
+
| Dependency | Version |
|
|
76
|
+
| ------------ | ------------------------------------------------------------ |
|
|
77
|
+
| Python | 3.11+ (tested on 3.11 to 3.15) |
|
|
78
|
+
| SurrealDB | 2.6.x / 2.7.x or 3.2.x / 3.3.x, or the SDK's embedded engine |
|
|
79
|
+
| Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0 |
|
|
80
|
+
| Pydantic | >=2.13.4 |
|
|
81
81
|
|
|
82
82
|
> **Note**: As of v0.7.0, Surreal ORM Lite targets the SurrealDB Python SDK 2.x (`surrealdb[pydantic]>=2.0.0,<3.0.0`), which supports the SurrealDB 3.x protocol. It is tested against SurrealDB **v2.7.0** and **v3.3.4**; up to v0.19.0 the pins were v2.6.5 and v3.2.4. The 2.x line behaves identically on 2.7.0, and 3.3.0 differs from 3.2.4 in one server behaviour, listed in the behaviour table. SurrealDB 3.1.x is no longer a supported line as of v0.14.0 — the suite is still run against 3.1.5 as a backward-compatibility check, but a regression there does not block a release.
|
|
83
83
|
|
|
@@ -222,6 +222,7 @@ results = await User.objects().query(
|
|
|
222
222
|
| Custom table name | ✅ |
|
|
223
223
|
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range) | ✅ |
|
|
224
224
|
| Geospatial fields (nearby, distance, spatial lookups) | ✅ |
|
|
225
|
+
| Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
|
|
225
226
|
|
|
226
227
|
### Supported Filter Lookups
|
|
227
228
|
|
|
@@ -2288,8 +2289,11 @@ flattens the SDK's `Duration(0)` into an object, like any SDK value there
|
|
|
2288
2289
|
([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
|
|
2289
2290
|
|
|
2290
2291
|
The hook is installed only while the installed SDK cannot decode these values, and only on the
|
|
2291
|
-
ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`)
|
|
2292
|
-
|
|
2292
|
+
ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`), the embedded
|
|
2293
|
+
engine's included (see [Embedded engine and test fixtures](#26-embedded-engine-and-test-fixtures)):
|
|
2294
|
+
there a zero duration and a degenerate geometry read as on a server, and `<set>[…]` is stored as an
|
|
2295
|
+
array, as on 2.x. An `AsyncSurreal` client the application builds itself keeps the SDK's behaviour
|
|
2296
|
+
and fails on them.
|
|
2293
2297
|
A later SDK reads zero durations and native sets itself
|
|
2294
2298
|
([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
|
|
2295
2299
|
leaves them to it.
|
|
@@ -2682,6 +2686,282 @@ rewrites the whole row.
|
|
|
2682
2686
|
from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
|
|
2683
2687
|
`surreal_orm_lite.fields` module.
|
|
2684
2688
|
|
|
2689
|
+
### 26. Embedded engine and test fixtures
|
|
2690
|
+
|
|
2691
|
+
Since v0.25.0 the ORM also runs on the official SDK's **in-process** SurrealDB engine: no server
|
|
2692
|
+
and no Docker, the database lives inside your Python process. It suits tests, notebooks and
|
|
2693
|
+
small tools, and the same models and queries run unchanged against a server. The
|
|
2694
|
+
`surreal_orm_lite.testing` module adds the test helpers: `embedded_database()` (an isolated
|
|
2695
|
+
database per block) and the full SurrealDB-ORM's `SurrealFixture` / `@fixture`.
|
|
2696
|
+
|
|
2697
|
+
#### In-process databases
|
|
2698
|
+
|
|
2699
|
+
```python
|
|
2700
|
+
from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
|
|
2701
|
+
|
|
2702
|
+
SurrealDBConnectionManager.set_connection(url="mem://", namespace="app", database="app")
|
|
2703
|
+
|
|
2704
|
+
class Note(BaseSurrealModel):
|
|
2705
|
+
id: str | None = None
|
|
2706
|
+
title: str
|
|
2707
|
+
done: bool = False
|
|
2708
|
+
|
|
2709
|
+
await Note(id="docs", title="Write the docs").save()
|
|
2710
|
+
assert await Note.objects().count() == 1
|
|
2711
|
+
assert SurrealDBConnectionManager.is_embedded()
|
|
2712
|
+
```
|
|
2713
|
+
|
|
2714
|
+
Same models, no server: the first ORM call opens the engine. `user` and `password` are optional
|
|
2715
|
+
on an embedded URL and **never sent** — the engine has no system user on a fresh database, and
|
|
2716
|
+
its anonymous session is the in-process owner (see
|
|
2717
|
+
[Identity on the embedded engine](#identity-on-the-embedded-engine)). They are kept, so one
|
|
2718
|
+
configuration switches between a server and `mem://` by its URL alone.
|
|
2719
|
+
`SurrealDBConnectionManager.is_embedded()` tells code that must run on both kinds of connection
|
|
2720
|
+
which one is configured.
|
|
2721
|
+
|
|
2722
|
+
| Embedded URL | surreal-orm-lite (official SDK 2.0.0) | Full SurrealDB-ORM |
|
|
2723
|
+
| ------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------ |
|
|
2724
|
+
| `mem://`, `memory://` | ✅ in memory, gone when the connection closes | ❌ (HTTP/WebSocket only) |
|
|
2725
|
+
| `surrealkv://<path>` | ✅ on disk (SurrealKV) | ❌ |
|
|
2726
|
+
| `surrealkv+versioned://<path>` | ✅ on disk; behaves as `surrealkv://` until time travel (v0.26.0) | ❌ |
|
|
2727
|
+
| `file://<path>` | ✅ a **SurrealKV** store, not the RocksDB store `file://` means for the SurrealDB server | ❌ |
|
|
2728
|
+
| `rocksdb://<path>` | ❌ not yet supported by the official SDK (#233): the ORM raises the SDK's refusal | ❌ |
|
|
2729
|
+
|
|
2730
|
+
A bare `memory` (no `://`) is refused by SDK 2.0.0 and accepted by the SDK 3.0 line; write
|
|
2731
|
+
`memory://`. The engine is SurrealDB core **2.3.10**, bundled with SDK 2.0.0 — not the 2.x and
|
|
2732
|
+
3.x server lines the ORM is tested against (see below). surreal-orm-lite keeps no list of
|
|
2733
|
+
embedded schemes: the SDK decides, so `rocksdb://` will work with no ORM change once a released
|
|
2734
|
+
SDK accepts it ([#233](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/233)).
|
|
2735
|
+
|
|
2736
|
+
A URL the installed SDK refuses is accepted by `set_connection()` and reported by the first ORM
|
|
2737
|
+
call, before anything is opened, with a `SurrealDbConnectionError` that quotes the SDK:
|
|
2738
|
+
|
|
2739
|
+
```python
|
|
2740
|
+
from surreal_orm_lite import SurrealDbConnectionError
|
|
2741
|
+
|
|
2742
|
+
SurrealDBConnectionManager.set_connection(url="rocksdb://app.db", namespace="app", database="app")
|
|
2743
|
+
try:
|
|
2744
|
+
await Note.objects().count()
|
|
2745
|
+
except SurrealDbConnectionError as error:
|
|
2746
|
+
print(error)
|
|
2747
|
+
# The installed surrealdb SDK cannot open 'rocksdb://app.db': 'rocksdb' is not a valid UrlScheme.
|
|
2748
|
+
# The URL schemes it accepts are: file, http, https, mem, memory, surrealkv, surrealkv+versioned,
|
|
2749
|
+
# ws, wss. Embedded RocksDB (rocksdb://) is not supported by the official SDK yet: see
|
|
2750
|
+
# https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/233.
|
|
2751
|
+
|
|
2752
|
+
# Back to mem://: the same in-memory database as above, which only a close discards.
|
|
2753
|
+
SurrealDBConnectionManager.set_connection(url="mem://", namespace="app", database="app")
|
|
2754
|
+
```
|
|
2755
|
+
|
|
2756
|
+
#### One engine per process
|
|
2757
|
+
|
|
2758
|
+
A server client is bound to the event loop it connected on, so the manager keeps one per loop
|
|
2759
|
+
(see [Connections and event loops](#connections-and-event-loops)). The engine is not: the
|
|
2760
|
+
manager keeps **one engine for the whole process**, opened on the first call and handed to every
|
|
2761
|
+
event loop and thread, so they all see the same database. Concurrent first calls open exactly
|
|
2762
|
+
one engine.
|
|
2763
|
+
|
|
2764
|
+
```python
|
|
2765
|
+
import asyncio
|
|
2766
|
+
|
|
2767
|
+
async def count_notes() -> int:
|
|
2768
|
+
return await Note.objects().count()
|
|
2769
|
+
|
|
2770
|
+
# Another event loop, on another thread: the same engine, the same data.
|
|
2771
|
+
assert await asyncio.to_thread(lambda: asyncio.run(count_notes())) == 1
|
|
2772
|
+
|
|
2773
|
+
await SurrealDBConnectionManager.close_connection() # the in-memory database is discarded
|
|
2774
|
+
assert await Note.objects().count() == 0 # a new, empty one
|
|
2775
|
+
```
|
|
2776
|
+
|
|
2777
|
+
- **Namespace and database** are a selection on that engine. After a change (`set_connection()`,
|
|
2778
|
+
`set_namespace()`, `set_database()`), the next call resets the shared session on the same
|
|
2779
|
+
engine — nothing is lost — and selects the new pair; a stored session ends (see
|
|
2780
|
+
[Identity](#identity-on-the-embedded-engine)). A new **URL** closes the old engine and opens
|
|
2781
|
+
the new one.
|
|
2782
|
+
- **Closing** — `close_connection()` (from any loop), `close_all_connections()`,
|
|
2783
|
+
`unset_connection()`, `reconnect()` and the exit of `async with SurrealDBConnectionManager():`
|
|
2784
|
+
— closes the engine: a `mem://` database is discarded with it, and the next call opens a new,
|
|
2785
|
+
empty one; a `surrealkv://` or `file://` database reopens with its data.
|
|
2786
|
+
- **`validate_connection()`** opens the engine if needed and never discards it, so the
|
|
2787
|
+
`set_*(..., reconnect=True)` setters keep a `mem://` database.
|
|
2788
|
+
- **Server clients are untouched** while an embedded URL is configured, and are used again when
|
|
2789
|
+
a server URL is configured back. `close_connection()`, `reconnect()` and the exit of
|
|
2790
|
+
`async with SurrealDBConnectionManager():` close only the engine then: a server client keeps
|
|
2791
|
+
its live queries and its identity, even one signed in with `store=False`, and
|
|
2792
|
+
`is_connected()` stays `True` on an event loop that keeps one. An event loop whose server
|
|
2793
|
+
connection dropped while signed in with `store=False`
|
|
2794
|
+
([section 21](#21-live-queries-real-time-notifications)) still raises once the server URL is
|
|
2795
|
+
set back with `set_url()`, or after an `embedded_database()` block: closing the engine, or
|
|
2796
|
+
setting an identity on it (`signin()`, `signup()`, `authenticate()`, `invalidate()`, model auth
|
|
2797
|
+
with `bind=True`), does not end that state. `set_connection()` does: a new configuration is a
|
|
2798
|
+
choice of identity. `close_all_connections()` and `unset_connection()` close the server
|
|
2799
|
+
clients too.
|
|
2800
|
+
|
|
2801
|
+
With the surrealdb SDK 2.x, closing does not stop an in-process engine: a client you obtained
|
|
2802
|
+
before `close_connection()` (or inside an `embedded_database()` block) is still a running
|
|
2803
|
+
database. Do not use it after the close, and drop it (`del client`) before reopening the same
|
|
2804
|
+
`surrealkv://` path: two engines on one path miss each other's writes. Never open one path from
|
|
2805
|
+
two processes.
|
|
2806
|
+
|
|
2807
|
+
#### What the embedded engine does not do
|
|
2808
|
+
|
|
2809
|
+
Each of these raises a clear ORM error up front, never an SDK `AttributeError` or an engine
|
|
2810
|
+
error:
|
|
2811
|
+
|
|
2812
|
+
- **Live queries** (`live()`, `watch()`, `subscribe_live()`): the engine has no notification
|
|
2813
|
+
channel. Read the table's change feed instead (`Model.objects().changes()`,
|
|
2814
|
+
[section 22](#22-change-feeds-changes)), which works from now and from a cursor.
|
|
2815
|
+
- **`changes(since=<datetime>)`**: the SDK 2.x engine keeps no timestamps for change-feed
|
|
2816
|
+
positions; pass a cursor (`ChangeModelStream.cursor`) or `since=None`.
|
|
2817
|
+
- **Model auth needs `bind=True`**: the engine has a single session per database, so
|
|
2818
|
+
`AuthenticatedUserMixin` calls with `bind=False` (a session of their own) and
|
|
2819
|
+
`ephemeral_client()` are refused.
|
|
2820
|
+
- **`rocksdb://`**: refused by the SDK
|
|
2821
|
+
([#233](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/233)), see above.
|
|
2822
|
+
|
|
2823
|
+
And two differences that raise nothing:
|
|
2824
|
+
|
|
2825
|
+
- **Transactions are buffered**: the SDK refuses interactive transactions on the engine, so
|
|
2826
|
+
`transaction()` picks the buffered strategy, as on HTTP ([section 11](#11-transactions-atomic-all-or-nothing)).
|
|
2827
|
+
- **Parse errors are a bare `RuntimeError`** with SDK 2.0.0 (a server raises the SDK's error
|
|
2828
|
+
classes). The DDL helpers (`define_computed_fields()`, `define_access()`) raise their usual
|
|
2829
|
+
`SurrealDbError`.
|
|
2830
|
+
|
|
2831
|
+
```python
|
|
2832
|
+
from surreal_orm_lite import SurrealDbError
|
|
2833
|
+
|
|
2834
|
+
try:
|
|
2835
|
+
async with Note.objects().live() as stream:
|
|
2836
|
+
pass
|
|
2837
|
+
except SurrealDbError as error:
|
|
2838
|
+
print(error)
|
|
2839
|
+
# Live queries need a WebSocket server connection (ws:// or wss://): the embedded engine ('mem://')
|
|
2840
|
+
# has no notification channel to deliver them. Read the table's change feed with
|
|
2841
|
+
# Model.objects().changes() instead, or connect to a server.
|
|
2842
|
+
```
|
|
2843
|
+
|
|
2844
|
+
#### Its SurrealQL is the 2.x line
|
|
2845
|
+
|
|
2846
|
+
SDK 2.0.0 bundles the SurrealDB **2.3.10** engine: write 2.x SurrealQL in raw queries and
|
|
2847
|
+
computed fields (`type::is::string`, not 3.x's `type::is_string`; no `DEFINE FIELD … COMPUTED`),
|
|
2848
|
+
and expect the 2.x column of the
|
|
2849
|
+
[behaviour table](#orm-behaviour-surrealdb-2x-vs-3x) — a table that does not exist reads as
|
|
2850
|
+
`[]`. `client.version()` reports the SDK's version (`surrealdb-2.0.0`), not the engine's. The SDK
|
|
2851
|
+
3.0 line bundles a 3.x engine
|
|
2852
|
+
([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)).
|
|
2853
|
+
|
|
2854
|
+
#### Identity on the embedded engine
|
|
2855
|
+
|
|
2856
|
+
- The **anonymous session is the in-process owner**: full access (DDL, writes), and
|
|
2857
|
+
`info()` returns `None`.
|
|
2858
|
+
- `signin()` / `signup()` / `authenticate()` ([section 18](#18-authentication-signin--signup--info--invalidate))
|
|
2859
|
+
work with the engine's record access methods and `DEFINE USER`s, and record users and table
|
|
2860
|
+
`PERMISSIONS` apply as on a server. A sign-in changes the session of the **whole process**:
|
|
2861
|
+
every event loop and thread shares the engine's single session.
|
|
2862
|
+
- `invalidate()` returns to the in-process owner: a configured user, if any, is never signed in.
|
|
2863
|
+
- A namespace/database change returns the session to the owner and **ends** the stored session:
|
|
2864
|
+
a token belongs to the database it was issued for, and replaying it would move the session
|
|
2865
|
+
back there.
|
|
2866
|
+
- Model auth with `bind=True` ([section 19](#19-model-level-authentication-authenticatedusermixin))
|
|
2867
|
+
signs that single session in, one call at a time: concurrent `bind=True` calls, and the
|
|
2868
|
+
connection-level `signin()` / `signup()` / `authenticate()` / `invalidate()` that hold the
|
|
2869
|
+
same session, are serialised (each `bind=True` call reads back its own record and adopts its
|
|
2870
|
+
own token) and the last one wins. A failed `bind=True` puts the previous session back, with
|
|
2871
|
+
one exception, as on a server: when `signup()` or `signin()` succeeded but the record does not
|
|
2872
|
+
fit the model, the session stays signed in as that record (the error says so). `refresh()`
|
|
2873
|
+
cannot succeed on the engine: its SurrealQL does not parse `WITH REFRESH`.
|
|
2874
|
+
|
|
2875
|
+
```python
|
|
2876
|
+
assert await SurrealDBConnectionManager.info() is None # anonymous: the in-process owner
|
|
2877
|
+
```
|
|
2878
|
+
|
|
2879
|
+
#### Test fixtures
|
|
2880
|
+
|
|
2881
|
+
`embedded_database()` runs a block against an isolated in-memory database (`mem://` by default,
|
|
2882
|
+
namespace and database `test`), then puts the previous connection back: its settings, stored
|
|
2883
|
+
session and engine. Blocks nest. It yields the block's SDK client for raw SurrealQL and DDL,
|
|
2884
|
+
valid **inside the block only**. Pass `surrealkv://<path>` for an on-disk database (with pytest,
|
|
2885
|
+
under `tmp_path`).
|
|
2886
|
+
|
|
2887
|
+
`SurrealFixture` and `@fixture` declare model instances as test data: `load()` saves a fresh
|
|
2888
|
+
copy of each, in declaration order, yields them, and deletes them on exit. They work on any
|
|
2889
|
+
connection, a server or the engine.
|
|
2890
|
+
|
|
2891
|
+
```python
|
|
2892
|
+
from surreal_orm_lite.testing import SurrealFixture, embedded_database, fixture
|
|
2893
|
+
|
|
2894
|
+
class User(BaseSurrealModel):
|
|
2895
|
+
id: str | None = None
|
|
2896
|
+
name: str
|
|
2897
|
+
role: str = "player"
|
|
2898
|
+
|
|
2899
|
+
@fixture
|
|
2900
|
+
class UserFixtures(SurrealFixture):
|
|
2901
|
+
alice = User(name="Alice", role="admin")
|
|
2902
|
+
bob = User(id="bob", name="Bob", role="player") # an explicit id is kept
|
|
2903
|
+
|
|
2904
|
+
async with embedded_database(): # a fresh, empty in-memory database
|
|
2905
|
+
async with UserFixtures.load() as fixtures:
|
|
2906
|
+
assert fixtures.alice.get_id() is not None
|
|
2907
|
+
admins = await User.objects().filter(role="admin").exec()
|
|
2908
|
+
assert [admin.name for admin in admins] == ["Alice"]
|
|
2909
|
+
assert await User.objects().count() == 0 # alice and bob are deleted
|
|
2910
|
+
# the in-memory database is gone; the previous connection is back
|
|
2911
|
+
```
|
|
2912
|
+
|
|
2913
|
+
With pytest and pytest-asyncio, one fresh in-memory database per test:
|
|
2914
|
+
|
|
2915
|
+
```python
|
|
2916
|
+
import pytest_asyncio
|
|
2917
|
+
from surreal_orm_lite.testing import embedded_database
|
|
2918
|
+
|
|
2919
|
+
@pytest_asyncio.fixture
|
|
2920
|
+
async def surreal_db():
|
|
2921
|
+
async with embedded_database():
|
|
2922
|
+
yield
|
|
2923
|
+
|
|
2924
|
+
@pytest_asyncio.fixture
|
|
2925
|
+
async def users(surreal_db):
|
|
2926
|
+
async with UserFixtures.load() as fixtures:
|
|
2927
|
+
yield fixtures
|
|
2928
|
+
```
|
|
2929
|
+
|
|
2930
|
+
`surreal_db` yields nothing, so no test keeps a client past its block; a test that needs raw
|
|
2931
|
+
SurrealQL calls `await SurrealDBConnectionManager.get_client()`. It works whatever loop scope
|
|
2932
|
+
pytest-asyncio gives the fixture and the test: there is one engine per process.
|
|
2933
|
+
|
|
2934
|
+
A fresh engine raises a retryable write conflict when several writes run concurrently on a table
|
|
2935
|
+
that does not exist yet: define the tables your test writes to concurrently first
|
|
2936
|
+
(`DEFINE TABLE`), or run those writes in a function decorated with `@retry_on_conflict()`
|
|
2937
|
+
([section 14](#14-optimistic-concurrency-retry_on_conflict)).
|
|
2938
|
+
|
|
2939
|
+
```python
|
|
2940
|
+
import asyncio
|
|
2941
|
+
|
|
2942
|
+
async with embedded_database() as client:
|
|
2943
|
+
await client.query("DEFINE TABLE User SCHEMALESS;") # before the concurrent first writes
|
|
2944
|
+
await asyncio.gather(*(User(name=f"user {n}").save() for n in range(20)))
|
|
2945
|
+
assert await User.objects().count() == 20
|
|
2946
|
+
```
|
|
2947
|
+
|
|
2948
|
+
#### Coming from the full SurrealDB-ORM
|
|
2949
|
+
|
|
2950
|
+
- **The full ORM has no embedded engine**: it connects over HTTP/WebSocket only (see the
|
|
2951
|
+
[embedded URL table](#in-process-databases)).
|
|
2952
|
+
- **`surreal_orm_lite.testing` mirrors `surreal_orm.testing`** for `SurrealFixture` and
|
|
2953
|
+
`fixture`: the same names, the same declarations, `load()` as an async context manager.
|
|
2954
|
+
- **`load()` keeps an explicit `id`** where the full ORM resets it to `None`, so a fixture can
|
|
2955
|
+
name its records (and an edge its endpoints). It also **cleans up** when a save fails or is
|
|
2956
|
+
cancelled mid-load: the instances already saved are deleted before the error propagates.
|
|
2957
|
+
- **`@fixture` raises `TypeError`** on a class that is not a `SurrealFixture` subclass (the full
|
|
2958
|
+
ORM accepts any class), and `load()` raises `ValueError` on an undecorated subclass of a
|
|
2959
|
+
fixture that declares instances of its own (the full ORM loads only the parent's).
|
|
2960
|
+
- **`load()` is typed** to yield the fixture class, so `fixtures.alice` has its model's type
|
|
2961
|
+
(the full ORM yields `Any`).
|
|
2962
|
+
- **Lite additions**: `SurrealDBConnectionManager.is_embedded()` and `embedded_database()`.
|
|
2963
|
+
- **`ModelFactory` and `Faker`** come in v0.39.0.
|
|
2964
|
+
|
|
2685
2965
|
---
|
|
2686
2966
|
|
|
2687
2967
|
## Configuration Options
|
|
@@ -2765,6 +3045,11 @@ socket is released when the loop is finalised.
|
|
|
2765
3045
|
|
|
2766
3046
|
Long-lived single-loop applications are unaffected: one loop, one connection, as before.
|
|
2767
3047
|
|
|
3048
|
+
An embedded URL is the exception: the engine runs in this process and is not bound to a loop, so
|
|
3049
|
+
the manager keeps one client for the whole process ([section 26](#26-embedded-engine-and-test-fixtures)).
|
|
3050
|
+
While it is configured, `close_connection()` closes that client only, not the loop's server client:
|
|
3051
|
+
`is_connected()` stays `True` on a loop that keeps one.
|
|
3052
|
+
|
|
2768
3053
|
---
|
|
2769
3054
|
|
|
2770
3055
|
## Compatibility
|
|
@@ -2773,15 +3058,16 @@ As of v0.7.0, Surreal ORM Lite uses `surrealdb[pydantic]>=2.0.0,<3.0.0` (Surreal
|
|
|
2773
3058
|
|
|
2774
3059
|
**Compatibility advantage over the full ORM**: ORM-lite runs on **both** SurrealDB **2.x (2.6 / 2.7) and 3.x (3.2 / 3.3)**, while the full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) (custom SDK) targets **3.x only**. Lite stays usable on existing 2.6.x deployments without forcing a server upgrade.
|
|
2775
3060
|
|
|
2776
|
-
| SurrealDB Version
|
|
2777
|
-
|
|
|
2778
|
-
| 3.3.4
|
|
2779
|
-
| 2.7.0
|
|
2780
|
-
|
|
|
2781
|
-
| 2.
|
|
2782
|
-
|
|
|
2783
|
-
| 3.
|
|
2784
|
-
|
|
|
3061
|
+
| SurrealDB Version | SDK Version | Status |
|
|
3062
|
+
| -------------------------------------------------- | ----------- | ------------------------------------ |
|
|
3063
|
+
| 3.3.4 | 2.0 | ✅ Tested |
|
|
3064
|
+
| 2.7.0 | 2.0 | ✅ Tested |
|
|
3065
|
+
| Embedded engine (SDK 2.0.0: SurrealDB 2.3.10 core) | 2.0 | ✅ Tested (in-process) |
|
|
3066
|
+
| 3.2.4 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
|
|
3067
|
+
| 2.6.5 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
|
|
3068
|
+
| 3.3.x / 3.2.x / 2.7.x / 2.6.x | 2.0 | ✅ Compatible |
|
|
3069
|
+
| 3.1.5 | 2.0 | ⚠️ Backward-compat only |
|
|
3070
|
+
| < 2.6 or > 3.3 | — | ⚠️ Not guaranteed |
|
|
2785
3071
|
|
|
2786
3072
|
### ORM behaviour: SurrealDB 2.x vs 3.x
|
|
2787
3073
|
|
|
@@ -2791,6 +3077,7 @@ listed behave the same on both lines. The 2.x column was measured on 2.6.5 and h
|
|
|
2791
3077
|
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
|
|
2792
3078
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
2793
3079
|
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.
|
|
3080
|
+
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
2794
3081
|
|
|
2795
3082
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
2796
3083
|
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
|
|
@@ -2889,6 +3176,32 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
|
|
|
2889
3176
|
|
|
2890
3177
|
> **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.
|
|
2891
3178
|
|
|
3179
|
+
### ORM behaviour: the embedded engine
|
|
3180
|
+
|
|
3181
|
+
The official SDK's in-process engine ([section 26](#26-embedded-engine-and-test-fixtures)) is a
|
|
3182
|
+
line of its own: SurrealDB core 2.3.10, bundled with SDK 2.0.0. Rows measured with SDK 2.0.0 on
|
|
3183
|
+
`mem://`, and on the 2.7.0 and 3.3.4 servers. Capabilities not listed behave as on a 2.x server.
|
|
3184
|
+
|
|
3185
|
+
| ORM capability | Embedded engine (SDK 2.0.0) | Servers (2.x and 3.x) | Since |
|
|
3186
|
+
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
|
|
3187
|
+
| Connection and credentials (`set_connection()`) | URL, namespace and database; `user` and `password` optional, kept and never sent | every setting required; the configured user signs in on each new connection | v0.25.0 |
|
|
3188
|
+
| URLs the SDK refuses (`rocksdb://`, a typo) | `SurrealDbConnectionError` quoting the SDK (naming #233 for `rocksdb://`), before anything is opened | n/a | v0.25.0 |
|
|
3189
|
+
| Clients | one for the whole process, shared by every event loop and thread | one per event loop | v0.25.0 |
|
|
3190
|
+
| Namespace/database change | the next call resets the session to the owner and selects the new pair on the same engine (no data lost); the stored session ends | taken by the next connection | v0.25.0 |
|
|
3191
|
+
| Closing (`close_connection()`, `unset_connection()`, `reconnect()`) | `mem://` discarded, `surrealkv://` reopened with its data; with SDK 2.x a client kept after the close is still a running engine; `close_connection()` and `reconnect()` leave the server clients open (`is_connected()` stays true on a loop with one) | the connection closes | v0.25.0 |
|
|
3192
|
+
| SurrealQL line | 2.x (SurrealDB 2.3.10 core); `client.version()` reports the SDK (`surrealdb-2.0.0`) | the server's | v0.25.0 |
|
|
3193
|
+
| `transaction()` | buffered | interactive on WebSocket and SurrealDB 3.x, else buffered | v0.25.0 |
|
|
3194
|
+
| Concurrent first writes to a table that does not exist yet | retryable conflict, a few % per batch of 20: define the table first | rare on 2.x, none measured on 3.x | v0.25.0 |
|
|
3195
|
+
| Live queries (`live()`, `watch()`, `subscribe_live()`) | `SurrealDbError` before any request: use change feeds | WebSocket only | v0.25.0 |
|
|
3196
|
+
| Change feeds (`changes()`) | from now and from a cursor; `since=<datetime>` refused (`SurrealDbError`) | from now, a cursor or a datetime | v0.25.0 |
|
|
3197
|
+
| Model auth (`AuthenticatedUserMixin`) | `bind=True` only, on the shared session, one call at a time with connection-level auth calls (the last one wins); a failure restores the previous session, except a record that does not fit the model after a successful `signup()` or `signin()`: the session stays signed in as it, as on a server (`refresh()` cannot succeed: no `WITH REFRESH`) | a session of its own; `bind=True` also adopts the token | v0.25.0 |
|
|
3198
|
+
| `ephemeral_client()` | `SurrealDbError`: the engine has a single session per database | an anonymous throwaway client | v0.25.0 |
|
|
3199
|
+
| Anonymous session | the in-process owner (full access); `info()` returns `None` | not used by the ORM (the configured user signs in); an anonymous `info()` raises `SurrealDbAuthenticationError` | v0.25.0 |
|
|
3200
|
+
| `invalidate()` | back to the in-process owner | signs in again as the configured user | v0.25.0 |
|
|
3201
|
+
| Reading a table that does not exist | `[]`, raw queries included (as on 2.x) | the ORM reads `[]`; a raw query on 3.x raises `NotFoundError` | v0.25.0 |
|
|
3202
|
+
| Parse errors | bare `RuntimeError` (the DDL helpers raise `SurrealDbError`) | the SDK's error classes | v0.25.0 |
|
|
3203
|
+
| 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 |
|
|
3204
|
+
|
|
2892
3205
|
---
|
|
2893
3206
|
|
|
2894
3207
|
## Contributing
|
|
@@ -2926,7 +3239,8 @@ Contributions are welcome! Please:
|
|
|
2926
3239
|
| v0.22.0 | Tier 1 — Native typed relations | ✅ Released |
|
|
2927
3240
|
| v0.23.0 | Rich field types | ✅ Released |
|
|
2928
3241
|
| v0.24.0 | Geospatial fields | ✅ Released |
|
|
2929
|
-
| v0.25.0
|
|
3242
|
+
| v0.25.0 | Embedded test engine | ✅ Released |
|
|
3243
|
+
| v0.26.0 – v0.29.0 | Tier 2 — Extended (time travel, subqueries) | 📋 Planned |
|
|
2930
3244
|
| v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
|
|
2931
3245
|
| v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
|
|
2932
3246
|
| v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
|
|
@@ -2945,7 +3259,7 @@ This project prioritizes **stability and compatibility** with the official Surre
|
|
|
2945
3259
|
|
|
2946
3260
|
Both projects target the same feature set; the difference is **how** (official SDK vs custom
|
|
2947
3261
|
SDK) and **server support**. Everything below is on the lite roadmap via the official SDK 2.0
|
|
2948
|
-
— only the custom-SDK internals stay exclusive to the full ORM.
|
|
3262
|
+
— only the custom-SDK internals stay exclusive to the full ORM; the official SDK's in-process engine (section 26) is lite-only.
|
|
2949
3263
|
|
|
2950
3264
|
| Feature | ORM-lite (official SDK) | ORM (custom SDK) |
|
|
2951
3265
|
| ----------------------------- | --------------------------------------------------------------------- | -------------------------------- |
|
|
@@ -2975,6 +3289,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
2975
3289
|
| Native typed relations | ✅ v0.22.0 (typed edge models; relation DDL in v0.33.0) | ✅ DDL only (TableType.RELATION) |
|
|
2976
3290
|
| Rich field types | ✅ v0.23.0 | ✅ |
|
|
2977
3291
|
| Geospatial Fields | ✅ v0.24.0 | ✅ |
|
|
3292
|
+
| Embedded engine | ✅ v0.25.0 (mem://, surrealkv://; rocksdb:// #233) | ❌ (HTTP/WebSocket only) |
|
|
2978
3293
|
| Subqueries & Query Cache | v0.27 – v0.28 | ✅ |
|
|
2979
3294
|
| Multi-database | v0.29.0 | ✅ |
|
|
2980
3295
|
| Schema Introspection | v0.30.0 | ✅ |
|
|
@@ -2984,7 +3299,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
2984
3299
|
| Vector Search (KNN/HNSW) | v0.35.0 | ✅ |
|
|
2985
3300
|
| Hybrid Search (RRF) | v0.36.0 | ✅ |
|
|
2986
3301
|
| Migrations & CLI | v0.37 – v0.38 | ✅ |
|
|
2987
|
-
| Test Fixtures & Factories | v0.39.0
|
|
3302
|
+
| Test Fixtures & Factories | ✅ v0.25.0 SurrealFixture; factories v0.39.0 | ✅ |
|
|
2988
3303
|
| Retry, Logging, Metrics | v0.40.0 | ✅ |
|
|
2989
3304
|
| Connection Pool | post-GA (tentative) | ✅ |
|
|
2990
3305
|
| Custom SDK / CBOR Protocol | ❌ never | ✅ |
|