surreal-orm-lite 0.40.2__tar.gz → 0.50.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.40.2 → surreal_orm_lite-0.50.0}/CHANGELOG.md +49 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/PKG-INFO +98 -82
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/README.md +94 -80
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/docs/README.md +25 -8
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/pyproject.toml +7 -2
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/__init__.py +1 -1
- surreal_orm_lite-0.50.0/src/surreal_orm_lite/_client.py +460 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/_sdk.py +78 -21
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/changefeed.py +7 -6
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cli/commands.py +2 -2
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/connection_manager.py +465 -120
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/decoding.py +136 -177
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/edge.py +3 -2
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/embedded.py +23 -4
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/encoding.py +48 -40
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/geo.py +4 -4
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/introspection.py +20 -10
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/live.py +61 -23
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/__init__.py +2 -1
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/executor.py +200 -23
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/render.py +55 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_auth.py +14 -4
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_base.py +40 -37
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/query_set.py +114 -57
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/schema.py +10 -9
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/schema_state.py +4 -1
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/search.py +8 -6
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/subquery.py +55 -4
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/surql_literal.py +8 -22
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/database.py +14 -9
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/pytest_plugin.py +6 -3
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/time_travel.py +3 -2
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/transaction.py +13 -9
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/types.py +13 -6
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/utils.py +11 -15
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/.gitignore +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/LICENSE +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/Makefile +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cli/__init__.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cli/__main__.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/define_parser.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/hybrid.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/autodetect.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/compare.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/constants.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/generator.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/introspector.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/loader.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/migration.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/operations.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/state.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_ddl.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_generator.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/factories.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.40.2 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/vector.py +0 -0
|
@@ -5,6 +5,55 @@ 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.50.0] - 2026-11-07
|
|
9
|
+
|
|
10
|
+
Official SDK 3.0 and SurrealDB 4.x. The ORM's minor series now follows the SDK's major: `0.50.x` is the SDK 3.0
|
|
11
|
+
line, `0.40.x` the SDK 2.0 line (deprecated, security fixes only). The ORM supports the SurrealDB versions the SDK
|
|
12
|
+
supports. See [the migration note](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrating-to-0.50.md).
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **SurrealDB 4.x support**, next to 2.x and 3.x (tested on 2.7.0, 3.3.5 and 4.0.0); CI runs the three lines and
|
|
17
|
+
watches the 4.x line daily. A server outside the SDK's range is refused at connect time with
|
|
18
|
+
`SurrealDbConnectionError`.
|
|
19
|
+
- **`surreal-orm-lite[embedded]`**, the optional extra that brings the SDK 3.0 in-process engine (a SurrealDB 4.0
|
|
20
|
+
core) for `mem://` and `surrealkv://`.
|
|
21
|
+
- **`FieldChangeRefusedError`** and `SchemaState.compatibility`: migrations refuse a field change that SurrealDB
|
|
22
|
+
4.x rejects on a populated `SCHEMAFULL` table, and point to a `RawSQL` replacement.
|
|
23
|
+
- Native sets read as `set`, zero durations read natively and datetimes keep their nanoseconds
|
|
24
|
+
(`PreciseDatetime`).
|
|
25
|
+
|
|
26
|
+
### Changed
|
|
27
|
+
|
|
28
|
+
- **BREAKING: depends on `surrealdb[pydantic]>=3.0.0,<4.0.0`** (it was `>=2.0.0,<3.0.0`). Every SDK call goes
|
|
29
|
+
through one internal frontier that normalises NULL to `None`, sets, datetimes and results.
|
|
30
|
+
- **BREAKING: `raw_query()` and `QuerySet.query()` return the rows of every statement**, in order, as the full
|
|
31
|
+
SurrealDB-ORM does. A failing later statement now raises; the multi-statement `UserWarning` is gone.
|
|
32
|
+
- **`first()` returns the smallest matching id** on SurrealDB 3.x and 4.x (`ORDER BY id`).
|
|
33
|
+
- The embedded engine moved to the SDK 3.0 engine (SurrealDB 4.0 core) behind the `embedded` extra; without it,
|
|
34
|
+
opening `mem://` raises `SurrealDbConnectionError` naming the extra.
|
|
35
|
+
- Live queries follow SDK 3.0's `subscribe_live()` and hide its queue sentinels behind the ORM feed.
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- `QuerySet.query()` no longer hides a cancelled transaction: on SurrealDB 3.x and 4.x a `BEGIN … COMMIT` whose
|
|
40
|
+
statement reads a missing table raises `SurrealDbError` (the server cancelled it, its writes did not run) instead
|
|
41
|
+
of returning `[]`; 2.x reads the missing table as empty and commits.
|
|
42
|
+
- A retired client refuses its next request instead of reconnecting anonymously.
|
|
43
|
+
- An HTTP refusal is the server's answer, not a lost connection.
|
|
44
|
+
- Introspection reads the SurrealDB 4.x `INFO` shapes; an HNSW search next to a subquery sends its `LET`s first on
|
|
45
|
+
4.x; the embedded owner's sign-in payload is encoded at the boundary; a `datetime.replace()` built on Python 3.11
|
|
46
|
+
is sent to the microsecond.
|
|
47
|
+
|
|
48
|
+
### Notes
|
|
49
|
+
|
|
50
|
+
- Staying on the SDK 2.0 for now? Pin the deprecated `0.40.x` line, which receives security fixes only, with
|
|
51
|
+
`pip install "surreal-orm-lite<0.50"`, and plan the move to `0.50.x` with the migration note.
|
|
52
|
+
- Behaviour that differs between 2.x, 3.x and 4.x is listed in the
|
|
53
|
+
[compatibility guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md).
|
|
54
|
+
- Not in this version: the SDK's own reconnection and token handling (v0.51.0, #422) and `MigrateRows` (v0.56.0,
|
|
55
|
+
#427).
|
|
56
|
+
|
|
8
57
|
## [0.40.2] - 2026-11-03
|
|
9
58
|
|
|
10
59
|
Follow-up of the review of the model factories (v0.40.0). No new public API.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.50.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
|
|
@@ -46,22 +46,24 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
|
46
46
|
Classifier: Typing :: Typed
|
|
47
47
|
Requires-Python: >=3.11
|
|
48
48
|
Requires-Dist: pydantic>=2.13.4
|
|
49
|
-
Requires-Dist: surrealdb[pydantic]<
|
|
49
|
+
Requires-Dist: surrealdb[pydantic]<4.0.0,>=3.0.0
|
|
50
|
+
Provides-Extra: embedded
|
|
51
|
+
Requires-Dist: surrealdb[embedded]<4.0.0,>=3.0.0; extra == 'embedded'
|
|
50
52
|
Description-Content-Type: text/markdown
|
|
51
53
|
|
|
52
54
|
# Surreal ORM Lite
|
|
53
55
|
|
|
54
56
|

|
|
55
|
-

|
|
56
|
-

|
|
58
|
+

|
|
57
59
|

|
|
58
60
|
[](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
|
|
59
61
|
|
|
60
62
|
**Surreal ORM Lite** is a lightweight, Django-style ORM for [SurrealDB](https://surrealdb.com/) that uses the **official SurrealDB Python SDK**. It provides a simple and intuitive interface for database operations with full async support and Pydantic validation.
|
|
61
63
|
|
|
62
|
-
- **Official SDK only**: built on `surrealdb[pydantic]
|
|
63
|
-
- **
|
|
64
|
-
(`mem://`, `surrealkv
|
|
64
|
+
- **Official SDK only**: built on `surrealdb[pydantic]` 3.0, no custom protocol, few dependencies.
|
|
65
|
+
- **Three server lines**: the same code runs on SurrealDB **2.x, 3.x and 4.x**, and on the SDK's in-process engine
|
|
66
|
+
(`mem://`, `surrealkv://`, with the `[embedded]` extra) for tests and notebooks.
|
|
65
67
|
- **Django-style queries**: `filter(age__gte=18)`, `Q` objects, `order_by("-age")`, aggregations, subqueries.
|
|
66
68
|
- **SurrealDB-native**: graph relations and typed edges, live queries, change feeds, time travel, full-text, vector
|
|
67
69
|
and hybrid search, events, views and schema DDL.
|
|
@@ -79,14 +81,16 @@ Description-Content-Type: text/markdown
|
|
|
79
81
|
pip install surreal-orm-lite
|
|
80
82
|
# or
|
|
81
83
|
uv add surreal-orm-lite
|
|
84
|
+
# with the SDK's in-process engine (mem://, surrealkv://) and the testing helpers
|
|
85
|
+
pip install "surreal-orm-lite[embedded]"
|
|
82
86
|
```
|
|
83
87
|
|
|
84
|
-
| Dependency | Version
|
|
85
|
-
| ------------ |
|
|
86
|
-
| Python | 3.11+ (tested on 3.11 to 3.15)
|
|
87
|
-
| SurrealDB | 2.
|
|
88
|
-
| Official SDK | surrealdb[pydantic]>=
|
|
89
|
-
| Pydantic | >=2.13.4
|
|
88
|
+
| Dependency | Version |
|
|
89
|
+
| ------------ | ----------------------------------------------------------------------------------------- |
|
|
90
|
+
| Python | 3.11+ (tested on 3.11 to 3.15) |
|
|
91
|
+
| SurrealDB | 2.x / 3.x / 4.x (2.6, 2.7, 3.2, 3.3, 4.0), or the SDK's embedded engine with `[embedded]` |
|
|
92
|
+
| Official SDK | surrealdb[pydantic]>=3.0.0,<4.0.0 |
|
|
93
|
+
| Pydantic | >=2.13.4 |
|
|
90
94
|
|
|
91
95
|
## Quick start
|
|
92
96
|
|
|
@@ -150,14 +154,14 @@ lists every QuerySet method and filter lookup.
|
|
|
150
154
|
| [Migrations](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrations.md) | `makemigrations()`, operations, `MigrationExecutor` |
|
|
151
155
|
| [Command line](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/cli.md) | `surreal-orm-lite`: migrate, rollback, inspectdb, schemadiff, shell |
|
|
152
156
|
| [Testing](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/testing.md) | `ModelFactory`, `Faker` and the pytest plugin |
|
|
153
|
-
| [Compatibility](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) | Tested versions and every behaviour that differs between SurrealDB 2.x, 3.x and the embedded engine
|
|
157
|
+
| [Compatibility](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) | Tested versions and every behaviour that differs between SurrealDB 2.x, 3.x, 4.x and the embedded engine |
|
|
154
158
|
|
|
155
159
|
The [documentation index](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md) lists every section of the guides.
|
|
156
160
|
|
|
157
161
|
## Using with AI assistants
|
|
158
162
|
|
|
159
163
|
The [guide for AI coding assistants](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ai/CLAUDE.md)
|
|
160
|
-
gives an assistant such as Claude Code the idioms, the 2.x/3.x differences and the common mistakes in one page,
|
|
164
|
+
gives an assistant such as Claude Code the idioms, the 2.x/3.x/4.x differences and the common mistakes in one page,
|
|
161
165
|
each example checked by the test suite. Download it into your project, then add the line `@docs/surreal-orm-lite.md`
|
|
162
166
|
to your `CLAUDE.md` to import it:
|
|
163
167
|
|
|
@@ -170,81 +174,92 @@ find every guide listed there.
|
|
|
170
174
|
|
|
171
175
|
## Features
|
|
172
176
|
|
|
173
|
-
| Feature
|
|
174
|
-
|
|
|
175
|
-
| Async/await support
|
|
176
|
-
| Pydantic validation
|
|
177
|
-
| CRUD operations
|
|
178
|
-
| QuerySet with filters
|
|
179
|
-
| Django-style lookups
|
|
180
|
-
| Custom primary keys
|
|
181
|
-
| HTTP connections
|
|
182
|
-
| WebSocket connections
|
|
183
|
-
| Aggregations
|
|
184
|
-
| GROUP BY
|
|
185
|
-
| Model Signals
|
|
186
|
-
| Raw SurrealQL queries
|
|
187
|
-
| Q Objects (OR/AND/NOT)
|
|
188
|
-
| Parameterized filters
|
|
189
|
-
| Bulk operations
|
|
190
|
-
| `-field` ordering
|
|
191
|
-
| Relations & Graph
|
|
192
|
-
| FETCH clause
|
|
193
|
-
| Transactions (`tx=`)
|
|
194
|
-
| upsert / get_or_create
|
|
195
|
-
| patch / atomic ops
|
|
196
|
-
| Retry on conflict
|
|
197
|
-
| Server-side functions
|
|
198
|
-
| Computed fields
|
|
199
|
-
| Stored `fn::` calls
|
|
200
|
-
| JWT / record auth
|
|
201
|
-
| Model-level auth mixin
|
|
202
|
-
| Field aliases & DX
|
|
203
|
-
| Live queries (raw)
|
|
204
|
-
| Typed live queries
|
|
205
|
-
| Live auto-resubscribe
|
|
206
|
-
| Change feeds (CDC)
|
|
207
|
-
| Typed edges (`insert_relation`)
|
|
208
|
-
| Custom table name
|
|
209
|
-
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range)
|
|
210
|
-
| Geospatial fields (nearby, distance, spatial lookups)
|
|
211
|
-
| Embedded engine (mem://, surrealkv://) & test fixtures
|
|
212
|
-
| Time travel (`as_of()`, versioned storage)
|
|
213
|
-
| Subqueries (`Subquery`, a QuerySet as a filter value)
|
|
214
|
-
| Query cache (`cache()`, TTL, invalidated by ORM writes)
|
|
215
|
-
| Multiple databases (named connections, `using()`)
|
|
216
|
-
| Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`)
|
|
217
|
-
| Server-side events & function DDL (`Event`, `define_function()`)
|
|
218
|
-
| Materialized views (`view_query`, `define_view()`, read-only)
|
|
219
|
-
| Relation constraints (`relation_in`, `define_relation()`, `TYPE RELATION`)
|
|
220
|
-
| Model table DDL (`define_table()`, `schema_mode`, `permissions`)
|
|
221
|
-
| Full-text search (`search()`, BM25 score and highlights)
|
|
222
|
-
| Vector search (`similar_to()`, KNN, HNSW indexes)
|
|
223
|
-
| Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion)
|
|
224
|
-
| Migrations (makemigrations / migrate / rollback)
|
|
225
|
-
| Command line (`surreal-orm-lite`: migrations, inspectdb, shell)
|
|
226
|
-
| Test data factories (`ModelFactory`, `Faker`) & pytest plugin
|
|
177
|
+
| Feature | Status |
|
|
178
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
179
|
+
| Async/await support | ✅ |
|
|
180
|
+
| Pydantic validation | ✅ |
|
|
181
|
+
| CRUD operations | ✅ |
|
|
182
|
+
| QuerySet with filters | ✅ |
|
|
183
|
+
| Django-style lookups | ✅ |
|
|
184
|
+
| Custom primary keys | ✅ |
|
|
185
|
+
| HTTP connections | ✅ |
|
|
186
|
+
| WebSocket connections | ✅ |
|
|
187
|
+
| Aggregations | ✅ |
|
|
188
|
+
| GROUP BY | ✅ |
|
|
189
|
+
| Model Signals | ✅ |
|
|
190
|
+
| Raw SurrealQL queries | ✅ |
|
|
191
|
+
| Q Objects (OR/AND/NOT) | ✅ |
|
|
192
|
+
| Parameterized filters | ✅ |
|
|
193
|
+
| Bulk operations | ✅ |
|
|
194
|
+
| `-field` ordering | ✅ |
|
|
195
|
+
| Relations & Graph | ✅ |
|
|
196
|
+
| FETCH clause | ✅ |
|
|
197
|
+
| Transactions (`tx=`) | ✅ |
|
|
198
|
+
| upsert / get_or_create | ✅ |
|
|
199
|
+
| patch / atomic ops | ✅ |
|
|
200
|
+
| Retry on conflict | ✅ |
|
|
201
|
+
| Server-side functions | ✅ |
|
|
202
|
+
| Computed fields | ✅ |
|
|
203
|
+
| Stored `fn::` calls | ✅ |
|
|
204
|
+
| JWT / record auth | ✅ |
|
|
205
|
+
| Model-level auth mixin | ✅ |
|
|
206
|
+
| Field aliases & DX | ✅ |
|
|
207
|
+
| Live queries (raw) | ✅ |
|
|
208
|
+
| Typed live queries | ✅ |
|
|
209
|
+
| Live auto-resubscribe | ✅ |
|
|
210
|
+
| Change feeds (CDC) | ✅ |
|
|
211
|
+
| Typed edges (`insert_relation`) | ✅ |
|
|
212
|
+
| Custom table name | ✅ |
|
|
213
|
+
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range) | ✅ |
|
|
214
|
+
| Geospatial fields (nearby, distance, spatial lookups) | ✅ |
|
|
215
|
+
| Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
|
|
216
|
+
| Time travel (`as_of()`, versioned storage) | ✅ |
|
|
217
|
+
| Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
|
|
218
|
+
| Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
|
|
219
|
+
| Multiple databases (named connections, `using()`) | ✅ |
|
|
220
|
+
| Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
|
|
221
|
+
| Server-side events & function DDL (`Event`, `define_function()`) | ✅ |
|
|
222
|
+
| Materialized views (`view_query`, `define_view()`, read-only) | ✅ |
|
|
223
|
+
| Relation constraints (`relation_in`, `define_relation()`, `TYPE RELATION`) | ✅ |
|
|
224
|
+
| Model table DDL (`define_table()`, `schema_mode`, `permissions`) | ✅ |
|
|
225
|
+
| Full-text search (`search()`, BM25 score and highlights) | ✅ |
|
|
226
|
+
| Vector search (`similar_to()`, KNN, HNSW indexes) | ✅ |
|
|
227
|
+
| Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion) | ✅ |
|
|
228
|
+
| Migrations (makemigrations / migrate / rollback) | ✅ |
|
|
229
|
+
| Command line (`surreal-orm-lite`: migrations, inspectdb, shell) | ✅ |
|
|
230
|
+
| Test data factories (`ModelFactory`, `Faker`) & pytest plugin | ✅ |
|
|
231
|
+
| Official SDK 3.0 & SurrealDB 4.x ([migration note](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrating-to-0.50.md)) | ✅ |
|
|
227
232
|
|
|
228
233
|
## Supported versions
|
|
229
234
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
3.
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
and the
|
|
235
|
+
| ORM version | Official SDK | SurrealDB lines | Status |
|
|
236
|
+
| ----------- | ----------------------------------- | --------------- | ------------------------------- |
|
|
237
|
+
| `0.50.x` | `surrealdb[pydantic]>=3.0.0,<4.0.0` | 2.x, 3.x, 4.x | current |
|
|
238
|
+
| `0.40.x` | `surrealdb[pydantic]>=2.0.0,<3.0.0` | 2.x, 3.x | deprecated, security fixes only |
|
|
239
|
+
|
|
240
|
+
The ORM's minor series follows the SDK major, and the ORM supports exactly the SurrealDB versions the SDK supports,
|
|
241
|
+
from the ORM version that adopts that SDK. It is tested against SurrealDB **v2.7.0**, **v3.3.5** and **v4.0.0**, and
|
|
242
|
+
on the SDK's in-process engine (a SurrealDB 4.0 core); SurrealDB 3.1.5 is run as a backward-compatibility check. A
|
|
243
|
+
few capabilities rely on server features introduced in SurrealDB 3.x: on 2.x the ORM degrades gracefully or says so
|
|
244
|
+
before sending anything. The [compatibility guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) lists every tested version and every
|
|
245
|
+
difference between the three lines and the embedded engine.
|
|
246
|
+
|
|
247
|
+
**Upgrading from 0.40.x**: 0.50.0 moves to the official SDK 3.0, so multi-statement raw queries, the client of
|
|
248
|
+
`get_client()`, the order of `first()` and the embedded engine change; the
|
|
249
|
+
[migration note](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrating-to-0.50.md) shows each change. To stay on SDK 2.0, pin
|
|
250
|
+
`pip install "surreal-orm-lite<0.50"`.
|
|
236
251
|
|
|
237
252
|
## SurrealDB-ORM-lite vs SurrealDB-ORM
|
|
238
253
|
|
|
239
254
|
This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. The full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) uses a custom SDK for advanced features.
|
|
240
255
|
|
|
241
256
|
Both projects target the same feature set; the difference is **how** (official SDK vs custom
|
|
242
|
-
SDK) and **server support**. Everything below is on the lite roadmap via the official SDK
|
|
257
|
+
SDK) and **server support**. Everything below is on the lite roadmap via the official SDK 3.0
|
|
243
258
|
— only the custom-SDK internals stay exclusive to the full ORM; the official SDK's in-process engine (section 26) is lite-only.
|
|
244
259
|
|
|
245
260
|
| Feature | ORM-lite (official SDK) | ORM (custom SDK) |
|
|
246
261
|
| ----------------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
|
|
247
|
-
| Supported SurrealDB | **2.6/2.7 + 3.2/3.3**
|
|
262
|
+
| Supported SurrealDB | **2.6/2.7 + 3.2/3.3 + 4.0** | 3.x only |
|
|
248
263
|
| CRUD & QuerySet | ✅ | ✅ |
|
|
249
264
|
| Aggregations & GROUP BY | ✅ | ✅ |
|
|
250
265
|
| Model Signals | ✅ | ✅ |
|
|
@@ -286,12 +301,12 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
286
301
|
| Hybrid Search (RRF) | ✅ v0.37.0 (`hybrid_search()`) | ✅ |
|
|
287
302
|
| Migrations & CLI | ✅ v0.38.0 (migrations), ✅ v0.39.0 (CLI) | ✅ |
|
|
288
303
|
| Test Fixtures & Factories | ✅ v0.25.0 SurrealFixture; ✅ v0.40.0 factories | ✅ |
|
|
289
|
-
| Retry, Logging, Metrics | v0.
|
|
304
|
+
| Retry, Logging, Metrics | v0.51.0 (reconnect), v0.59.0 (logging, metrics) | ✅ |
|
|
290
305
|
| Connection Pool | post-GA (tentative) | ✅ |
|
|
291
306
|
| Custom SDK / CBOR Protocol | ❌ never | ✅ |
|
|
292
307
|
|
|
293
308
|
**Choose ORM-lite** if you want the official SDK, minimal dependencies, support for SurrealDB
|
|
294
|
-
2.x (2.6 / 2.7)
|
|
309
|
+
2.x (2.6 / 2.7), 3.x (3.2 / 3.3) **and** 4.x (4.0), and a full feature roadmap built entirely on the official SDK.
|
|
295
310
|
|
|
296
311
|
**Choose ORM** if you need the custom-SDK internals (CBOR protocol, native connection pool)
|
|
297
312
|
or those features available today rather than on the roadmap.
|
|
@@ -301,9 +316,10 @@ or those features available today rather than on the roadmap.
|
|
|
301
316
|
|
|
302
317
|
## Project status
|
|
303
318
|
|
|
304
|
-
Surreal ORM Lite is in **alpha** (0.x): every Tier 1 to Tier 3 feature of the roadmap has shipped, and
|
|
305
|
-
|
|
306
|
-
|
|
319
|
+
Surreal ORM Lite is in **alpha** (0.x): every Tier 1 to Tier 3 feature of the roadmap has shipped, and v0.50.0 moved
|
|
320
|
+
it to the official SDK 3.0 and SurrealDB 4.x. The SDK 3.0 features come next, v0.51.0 to v0.58.0, then the **beta**
|
|
321
|
+
phase (API freeze and hardening) in v0.59.0, on the way to GA as v3.0.0, numbered after the official SDK 3.0. The
|
|
322
|
+
[release overview](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md#roadmap) lists every release, and
|
|
307
323
|
[docs/ROADMAP.md](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ROADMAP.md) details each one.
|
|
308
324
|
|
|
309
325
|
## Contributing
|
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
# Surreal ORM Lite
|
|
2
2
|
|
|
3
3
|

|
|
4
|
-

|
|
5
|
-

|
|
5
|
+

|
|
6
6
|

|
|
7
7
|
[](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
|
|
8
8
|
|
|
9
9
|
**Surreal ORM Lite** is a lightweight, Django-style ORM for [SurrealDB](https://surrealdb.com/) that uses the **official SurrealDB Python SDK**. It provides a simple and intuitive interface for database operations with full async support and Pydantic validation.
|
|
10
10
|
|
|
11
|
-
- **Official SDK only**: built on `surrealdb[pydantic]
|
|
12
|
-
- **
|
|
13
|
-
(`mem://`, `surrealkv
|
|
11
|
+
- **Official SDK only**: built on `surrealdb[pydantic]` 3.0, no custom protocol, few dependencies.
|
|
12
|
+
- **Three server lines**: the same code runs on SurrealDB **2.x, 3.x and 4.x**, and on the SDK's in-process engine
|
|
13
|
+
(`mem://`, `surrealkv://`, with the `[embedded]` extra) for tests and notebooks.
|
|
14
14
|
- **Django-style queries**: `filter(age__gte=18)`, `Q` objects, `order_by("-age")`, aggregations, subqueries.
|
|
15
15
|
- **SurrealDB-native**: graph relations and typed edges, live queries, change feeds, time travel, full-text, vector
|
|
16
16
|
and hybrid search, events, views and schema DDL.
|
|
@@ -28,14 +28,16 @@
|
|
|
28
28
|
pip install surreal-orm-lite
|
|
29
29
|
# or
|
|
30
30
|
uv add surreal-orm-lite
|
|
31
|
+
# with the SDK's in-process engine (mem://, surrealkv://) and the testing helpers
|
|
32
|
+
pip install "surreal-orm-lite[embedded]"
|
|
31
33
|
```
|
|
32
34
|
|
|
33
|
-
| Dependency | Version
|
|
34
|
-
| ------------ |
|
|
35
|
-
| Python | 3.11+ (tested on 3.11 to 3.15)
|
|
36
|
-
| SurrealDB | 2.
|
|
37
|
-
| Official SDK | surrealdb[pydantic]>=
|
|
38
|
-
| Pydantic | >=2.13.4
|
|
35
|
+
| Dependency | Version |
|
|
36
|
+
| ------------ | ----------------------------------------------------------------------------------------- |
|
|
37
|
+
| Python | 3.11+ (tested on 3.11 to 3.15) |
|
|
38
|
+
| SurrealDB | 2.x / 3.x / 4.x (2.6, 2.7, 3.2, 3.3, 4.0), or the SDK's embedded engine with `[embedded]` |
|
|
39
|
+
| Official SDK | surrealdb[pydantic]>=3.0.0,<4.0.0 |
|
|
40
|
+
| Pydantic | >=2.13.4 |
|
|
39
41
|
|
|
40
42
|
## Quick start
|
|
41
43
|
|
|
@@ -99,14 +101,14 @@ lists every QuerySet method and filter lookup.
|
|
|
99
101
|
| [Migrations](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrations.md) | `makemigrations()`, operations, `MigrationExecutor` |
|
|
100
102
|
| [Command line](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/cli.md) | `surreal-orm-lite`: migrate, rollback, inspectdb, schemadiff, shell |
|
|
101
103
|
| [Testing](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/testing.md) | `ModelFactory`, `Faker` and the pytest plugin |
|
|
102
|
-
| [Compatibility](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) | Tested versions and every behaviour that differs between SurrealDB 2.x, 3.x and the embedded engine
|
|
104
|
+
| [Compatibility](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) | Tested versions and every behaviour that differs between SurrealDB 2.x, 3.x, 4.x and the embedded engine |
|
|
103
105
|
|
|
104
106
|
The [documentation index](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md) lists every section of the guides.
|
|
105
107
|
|
|
106
108
|
## Using with AI assistants
|
|
107
109
|
|
|
108
110
|
The [guide for AI coding assistants](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ai/CLAUDE.md)
|
|
109
|
-
gives an assistant such as Claude Code the idioms, the 2.x/3.x differences and the common mistakes in one page,
|
|
111
|
+
gives an assistant such as Claude Code the idioms, the 2.x/3.x/4.x differences and the common mistakes in one page,
|
|
110
112
|
each example checked by the test suite. Download it into your project, then add the line `@docs/surreal-orm-lite.md`
|
|
111
113
|
to your `CLAUDE.md` to import it:
|
|
112
114
|
|
|
@@ -119,81 +121,92 @@ find every guide listed there.
|
|
|
119
121
|
|
|
120
122
|
## Features
|
|
121
123
|
|
|
122
|
-
| Feature
|
|
123
|
-
|
|
|
124
|
-
| Async/await support
|
|
125
|
-
| Pydantic validation
|
|
126
|
-
| CRUD operations
|
|
127
|
-
| QuerySet with filters
|
|
128
|
-
| Django-style lookups
|
|
129
|
-
| Custom primary keys
|
|
130
|
-
| HTTP connections
|
|
131
|
-
| WebSocket connections
|
|
132
|
-
| Aggregations
|
|
133
|
-
| GROUP BY
|
|
134
|
-
| Model Signals
|
|
135
|
-
| Raw SurrealQL queries
|
|
136
|
-
| Q Objects (OR/AND/NOT)
|
|
137
|
-
| Parameterized filters
|
|
138
|
-
| Bulk operations
|
|
139
|
-
| `-field` ordering
|
|
140
|
-
| Relations & Graph
|
|
141
|
-
| FETCH clause
|
|
142
|
-
| Transactions (`tx=`)
|
|
143
|
-
| upsert / get_or_create
|
|
144
|
-
| patch / atomic ops
|
|
145
|
-
| Retry on conflict
|
|
146
|
-
| Server-side functions
|
|
147
|
-
| Computed fields
|
|
148
|
-
| Stored `fn::` calls
|
|
149
|
-
| JWT / record auth
|
|
150
|
-
| Model-level auth mixin
|
|
151
|
-
| Field aliases & DX
|
|
152
|
-
| Live queries (raw)
|
|
153
|
-
| Typed live queries
|
|
154
|
-
| Live auto-resubscribe
|
|
155
|
-
| Change feeds (CDC)
|
|
156
|
-
| Typed edges (`insert_relation`)
|
|
157
|
-
| Custom table name
|
|
158
|
-
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range)
|
|
159
|
-
| Geospatial fields (nearby, distance, spatial lookups)
|
|
160
|
-
| Embedded engine (mem://, surrealkv://) & test fixtures
|
|
161
|
-
| Time travel (`as_of()`, versioned storage)
|
|
162
|
-
| Subqueries (`Subquery`, a QuerySet as a filter value)
|
|
163
|
-
| Query cache (`cache()`, TTL, invalidated by ORM writes)
|
|
164
|
-
| Multiple databases (named connections, `using()`)
|
|
165
|
-
| Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`)
|
|
166
|
-
| Server-side events & function DDL (`Event`, `define_function()`)
|
|
167
|
-
| Materialized views (`view_query`, `define_view()`, read-only)
|
|
168
|
-
| Relation constraints (`relation_in`, `define_relation()`, `TYPE RELATION`)
|
|
169
|
-
| Model table DDL (`define_table()`, `schema_mode`, `permissions`)
|
|
170
|
-
| Full-text search (`search()`, BM25 score and highlights)
|
|
171
|
-
| Vector search (`similar_to()`, KNN, HNSW indexes)
|
|
172
|
-
| Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion)
|
|
173
|
-
| Migrations (makemigrations / migrate / rollback)
|
|
174
|
-
| Command line (`surreal-orm-lite`: migrations, inspectdb, shell)
|
|
175
|
-
| Test data factories (`ModelFactory`, `Faker`) & pytest plugin
|
|
124
|
+
| Feature | Status |
|
|
125
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
126
|
+
| Async/await support | ✅ |
|
|
127
|
+
| Pydantic validation | ✅ |
|
|
128
|
+
| CRUD operations | ✅ |
|
|
129
|
+
| QuerySet with filters | ✅ |
|
|
130
|
+
| Django-style lookups | ✅ |
|
|
131
|
+
| Custom primary keys | ✅ |
|
|
132
|
+
| HTTP connections | ✅ |
|
|
133
|
+
| WebSocket connections | ✅ |
|
|
134
|
+
| Aggregations | ✅ |
|
|
135
|
+
| GROUP BY | ✅ |
|
|
136
|
+
| Model Signals | ✅ |
|
|
137
|
+
| Raw SurrealQL queries | ✅ |
|
|
138
|
+
| Q Objects (OR/AND/NOT) | ✅ |
|
|
139
|
+
| Parameterized filters | ✅ |
|
|
140
|
+
| Bulk operations | ✅ |
|
|
141
|
+
| `-field` ordering | ✅ |
|
|
142
|
+
| Relations & Graph | ✅ |
|
|
143
|
+
| FETCH clause | ✅ |
|
|
144
|
+
| Transactions (`tx=`) | ✅ |
|
|
145
|
+
| upsert / get_or_create | ✅ |
|
|
146
|
+
| patch / atomic ops | ✅ |
|
|
147
|
+
| Retry on conflict | ✅ |
|
|
148
|
+
| Server-side functions | ✅ |
|
|
149
|
+
| Computed fields | ✅ |
|
|
150
|
+
| Stored `fn::` calls | ✅ |
|
|
151
|
+
| JWT / record auth | ✅ |
|
|
152
|
+
| Model-level auth mixin | ✅ |
|
|
153
|
+
| Field aliases & DX | ✅ |
|
|
154
|
+
| Live queries (raw) | ✅ |
|
|
155
|
+
| Typed live queries | ✅ |
|
|
156
|
+
| Live auto-resubscribe | ✅ |
|
|
157
|
+
| Change feeds (CDC) | ✅ |
|
|
158
|
+
| Typed edges (`insert_relation`) | ✅ |
|
|
159
|
+
| Custom table name | ✅ |
|
|
160
|
+
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range) | ✅ |
|
|
161
|
+
| Geospatial fields (nearby, distance, spatial lookups) | ✅ |
|
|
162
|
+
| Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
|
|
163
|
+
| Time travel (`as_of()`, versioned storage) | ✅ |
|
|
164
|
+
| Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
|
|
165
|
+
| Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
|
|
166
|
+
| Multiple databases (named connections, `using()`) | ✅ |
|
|
167
|
+
| Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
|
|
168
|
+
| Server-side events & function DDL (`Event`, `define_function()`) | ✅ |
|
|
169
|
+
| Materialized views (`view_query`, `define_view()`, read-only) | ✅ |
|
|
170
|
+
| Relation constraints (`relation_in`, `define_relation()`, `TYPE RELATION`) | ✅ |
|
|
171
|
+
| Model table DDL (`define_table()`, `schema_mode`, `permissions`) | ✅ |
|
|
172
|
+
| Full-text search (`search()`, BM25 score and highlights) | ✅ |
|
|
173
|
+
| Vector search (`similar_to()`, KNN, HNSW indexes) | ✅ |
|
|
174
|
+
| Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion) | ✅ |
|
|
175
|
+
| Migrations (makemigrations / migrate / rollback) | ✅ |
|
|
176
|
+
| Command line (`surreal-orm-lite`: migrations, inspectdb, shell) | ✅ |
|
|
177
|
+
| Test data factories (`ModelFactory`, `Faker`) & pytest plugin | ✅ |
|
|
178
|
+
| Official SDK 3.0 & SurrealDB 4.x ([migration note](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrating-to-0.50.md)) | ✅ |
|
|
176
179
|
|
|
177
180
|
## Supported versions
|
|
178
181
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
3.
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
and the
|
|
182
|
+
| ORM version | Official SDK | SurrealDB lines | Status |
|
|
183
|
+
| ----------- | ----------------------------------- | --------------- | ------------------------------- |
|
|
184
|
+
| `0.50.x` | `surrealdb[pydantic]>=3.0.0,<4.0.0` | 2.x, 3.x, 4.x | current |
|
|
185
|
+
| `0.40.x` | `surrealdb[pydantic]>=2.0.0,<3.0.0` | 2.x, 3.x | deprecated, security fixes only |
|
|
186
|
+
|
|
187
|
+
The ORM's minor series follows the SDK major, and the ORM supports exactly the SurrealDB versions the SDK supports,
|
|
188
|
+
from the ORM version that adopts that SDK. It is tested against SurrealDB **v2.7.0**, **v3.3.5** and **v4.0.0**, and
|
|
189
|
+
on the SDK's in-process engine (a SurrealDB 4.0 core); SurrealDB 3.1.5 is run as a backward-compatibility check. A
|
|
190
|
+
few capabilities rely on server features introduced in SurrealDB 3.x: on 2.x the ORM degrades gracefully or says so
|
|
191
|
+
before sending anything. The [compatibility guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) lists every tested version and every
|
|
192
|
+
difference between the three lines and the embedded engine.
|
|
193
|
+
|
|
194
|
+
**Upgrading from 0.40.x**: 0.50.0 moves to the official SDK 3.0, so multi-statement raw queries, the client of
|
|
195
|
+
`get_client()`, the order of `first()` and the embedded engine change; the
|
|
196
|
+
[migration note](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrating-to-0.50.md) shows each change. To stay on SDK 2.0, pin
|
|
197
|
+
`pip install "surreal-orm-lite<0.50"`.
|
|
185
198
|
|
|
186
199
|
## SurrealDB-ORM-lite vs SurrealDB-ORM
|
|
187
200
|
|
|
188
201
|
This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. The full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) uses a custom SDK for advanced features.
|
|
189
202
|
|
|
190
203
|
Both projects target the same feature set; the difference is **how** (official SDK vs custom
|
|
191
|
-
SDK) and **server support**. Everything below is on the lite roadmap via the official SDK
|
|
204
|
+
SDK) and **server support**. Everything below is on the lite roadmap via the official SDK 3.0
|
|
192
205
|
— only the custom-SDK internals stay exclusive to the full ORM; the official SDK's in-process engine (section 26) is lite-only.
|
|
193
206
|
|
|
194
207
|
| Feature | ORM-lite (official SDK) | ORM (custom SDK) |
|
|
195
208
|
| ----------------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
|
|
196
|
-
| Supported SurrealDB | **2.6/2.7 + 3.2/3.3**
|
|
209
|
+
| Supported SurrealDB | **2.6/2.7 + 3.2/3.3 + 4.0** | 3.x only |
|
|
197
210
|
| CRUD & QuerySet | ✅ | ✅ |
|
|
198
211
|
| Aggregations & GROUP BY | ✅ | ✅ |
|
|
199
212
|
| Model Signals | ✅ | ✅ |
|
|
@@ -235,12 +248,12 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
235
248
|
| Hybrid Search (RRF) | ✅ v0.37.0 (`hybrid_search()`) | ✅ |
|
|
236
249
|
| Migrations & CLI | ✅ v0.38.0 (migrations), ✅ v0.39.0 (CLI) | ✅ |
|
|
237
250
|
| Test Fixtures & Factories | ✅ v0.25.0 SurrealFixture; ✅ v0.40.0 factories | ✅ |
|
|
238
|
-
| Retry, Logging, Metrics | v0.
|
|
251
|
+
| Retry, Logging, Metrics | v0.51.0 (reconnect), v0.59.0 (logging, metrics) | ✅ |
|
|
239
252
|
| Connection Pool | post-GA (tentative) | ✅ |
|
|
240
253
|
| Custom SDK / CBOR Protocol | ❌ never | ✅ |
|
|
241
254
|
|
|
242
255
|
**Choose ORM-lite** if you want the official SDK, minimal dependencies, support for SurrealDB
|
|
243
|
-
2.x (2.6 / 2.7)
|
|
256
|
+
2.x (2.6 / 2.7), 3.x (3.2 / 3.3) **and** 4.x (4.0), and a full feature roadmap built entirely on the official SDK.
|
|
244
257
|
|
|
245
258
|
**Choose ORM** if you need the custom-SDK internals (CBOR protocol, native connection pool)
|
|
246
259
|
or those features available today rather than on the roadmap.
|
|
@@ -250,9 +263,10 @@ or those features available today rather than on the roadmap.
|
|
|
250
263
|
|
|
251
264
|
## Project status
|
|
252
265
|
|
|
253
|
-
Surreal ORM Lite is in **alpha** (0.x): every Tier 1 to Tier 3 feature of the roadmap has shipped, and
|
|
254
|
-
|
|
255
|
-
|
|
266
|
+
Surreal ORM Lite is in **alpha** (0.x): every Tier 1 to Tier 3 feature of the roadmap has shipped, and v0.50.0 moved
|
|
267
|
+
it to the official SDK 3.0 and SurrealDB 4.x. The SDK 3.0 features come next, v0.51.0 to v0.58.0, then the **beta**
|
|
268
|
+
phase (API freeze and hardening) in v0.59.0, on the way to GA as v3.0.0, numbered after the official SDK 3.0. The
|
|
269
|
+
[release overview](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md#roadmap) lists every release, and
|
|
256
270
|
[docs/ROADMAP.md](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ROADMAP.md) details each one.
|
|
257
271
|
|
|
258
272
|
## Contributing
|