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.
Files changed (37) hide show
  1. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/CHANGELOG.md +144 -0
  2. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/PKG-INFO +336 -21
  3. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/README.md +335 -20
  4. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/_sdk.py +14 -0
  7. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/changefeed.py +10 -1
  8. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/connection_manager.py +640 -84
  9. surreal_orm_lite-0.25.0/src/surreal_orm_lite/embedded.py +124 -0
  10. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/live.py +7 -0
  11. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_auth.py +279 -26
  12. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/query_set.py +6 -3
  13. surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/__init__.py +28 -0
  14. surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/database.py +59 -0
  15. surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/fixtures.py +139 -0
  16. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/utils.py +3 -2
  17. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/.gitignore +0 -0
  18. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/LICENSE +0 -0
  19. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/Makefile +0 -0
  20. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/aggregations.py +0 -0
  21. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/auth.py +0 -0
  22. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/concurrency.py +0 -0
  23. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/constants.py +0 -0
  24. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/decoding.py +0 -0
  25. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/edge.py +0 -0
  26. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/encoding.py +0 -0
  27. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/enum.py +0 -0
  28. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/exceptions.py +0 -0
  29. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/functions.py +0 -0
  30. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/geo.py +0 -0
  31. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_base.py +0 -0
  32. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/py.typed +0 -0
  33. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/q.py +0 -0
  34. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/signals.py +0 -0
  35. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  36. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/transaction.py +0 -0
  37. {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.24.3
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()`). An
2292
- `AsyncSurreal` client the application builds itself keeps the SDK's behaviour and fails on them.
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 | SDK Version | Status |
2777
- | ----------------------------- | ----------- | ------------------------------------ |
2778
- | 3.3.4 | 2.0 | ✅ Tested |
2779
- | 2.7.0 | 2.0 | ✅ Tested |
2780
- | 3.2.4 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
2781
- | 2.6.5 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
2782
- | 3.3.x / 3.2.x / 2.7.x / 2.6.x | 2.0 | ✅ Compatible |
2783
- | 3.1.5 | 2.0 | ⚠️ Backward-compat only |
2784
- | < 2.6 or > 3.3 | — | ⚠️ Not guaranteed |
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 – v0.29.0 | Tier 2 — Extended (embedded, subqueries) | 📋 Planned |
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 | ✅ |