surreal-orm-lite 0.40.0__tar.gz → 0.40.1__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.0 → surreal_orm_lite-0.40.1}/CHANGELOG.md +37 -0
- surreal_orm_lite-0.40.1/PKG-INFO +313 -0
- surreal_orm_lite-0.40.1/README.md +262 -0
- surreal_orm_lite-0.40.1/docs/README.md +182 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/pyproject.toml +1 -1
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_base.py +353 -35
- surreal_orm_lite-0.40.0/PKG-INFO +0 -8010
- surreal_orm_lite-0.40.0/README.md +0 -7959
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/.gitignore +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/LICENSE +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/Makefile +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cli/__init__.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cli/__main__.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cli/commands.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/define_parser.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/hybrid.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/introspection.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/__init__.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/autodetect.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/compare.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/constants.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/executor.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/generator.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/introspector.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/loader.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/migration.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/operations.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/render.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/state.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_ddl.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_generator.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/schema.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/schema_state.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/search.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/subquery.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/factories.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/pytest_plugin.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/utils.py +0 -0
- {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/vector.py +0 -0
|
@@ -5,6 +5,43 @@ 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.40.1] - 2026-11-02
|
|
9
|
+
|
|
10
|
+
The remembered forward-reference rebuild of v0.39.5 keys on the names a model's annotations mention, compares
|
|
11
|
+
them by identity and follows type aliases. No new public API.
|
|
12
|
+
|
|
13
|
+
### Fixed
|
|
14
|
+
|
|
15
|
+
- **A loop no longer rebuilds an incomplete model at every turn** (#395). The memory of a failed
|
|
16
|
+
`model_rebuild()` now holds only the names the model's string annotations mention, looked up in the
|
|
17
|
+
calling function's local names and in the model's module, instead of whole namespaces: a loop variable or
|
|
18
|
+
any other unrelated name changing no longer triggers a new `model_rebuild()`. A mentioned name bound to
|
|
19
|
+
another forward reference adds the names that one mentions. The names a still-incomplete linked model of
|
|
20
|
+
another module mentions are looked up in the calling function's local names too, as Pydantic resolves them
|
|
21
|
+
there: binding one as a local name tries again.
|
|
22
|
+
- **The remembered values are compared with `is`** (#395), and kept alive by the memory, instead of being
|
|
23
|
+
compared by `id()`: a value freed and replaced by another object at the same address can no longer leave
|
|
24
|
+
the memory stale.
|
|
25
|
+
- **Links through a type alias, a dataclass or a `TypedDict` are followed** (#395). A linked model reached
|
|
26
|
+
through `typing.TypeAliasType` (PEP 695's `type BA = B | None`, or the `typing_extensions` backport, read
|
|
27
|
+
through its `__value__`), or through the fields of a dataclass or a `TypedDict`, now ends the memory when
|
|
28
|
+
it completes, so the next call raises the model's refusal. An alias whose value is itself a forward
|
|
29
|
+
reference (`TypeAliasType("BA", "C | None")`, `list["C"] | None`, `type BA = "C | None"`) is remembered
|
|
30
|
+
with the names it mentions, looked up in the calling function's local names and in the alias's module:
|
|
31
|
+
defining one there tries again. An alias whose value raises (an undefined name,
|
|
32
|
+
or an error such as `AttributeError`) never makes an ORM call fail: the field stays `any`, as before, and
|
|
33
|
+
on Python 3.14+ defining a name the alias mentions tries again.
|
|
34
|
+
- **Forward references in the return annotations of computed fields and serializers count** (#395): a name
|
|
35
|
+
mentioned by the return annotation of a `@computed_field`, `@field_serializer` or `@model_serializer` (or by
|
|
36
|
+
its explicit `return_type`), which Pydantic evaluates to complete the model, is remembered too, so defining
|
|
37
|
+
it completes the model at the next call.
|
|
38
|
+
- **`Literal` values and `Annotated` metadata are not read as names** (#395): the strings in
|
|
39
|
+
`Literal["user", "admin"]` and the metadata of `Annotated[int, "doc"]` (all its arguments but the first) are
|
|
40
|
+
no longer looked up as forward references, as objects or as string annotations (Python 3.14's lazy
|
|
41
|
+
annotations, `from __future__ import annotations`), so a loop variable named `user` no longer rebuilds the
|
|
42
|
+
model at every turn.
|
|
43
|
+
- Same behaviour on SurrealDB 2.x and 3.x.
|
|
44
|
+
|
|
8
45
|
## [0.40.0] - 2026-11-02
|
|
9
46
|
|
|
10
47
|
Test data factories (`ModelFactory`, `Faker`) and an opt-in pytest plugin in `surreal_orm_lite.testing`, with
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: surreal-orm-lite
|
|
3
|
+
Version: 0.40.1
|
|
4
|
+
Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
|
|
5
|
+
Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
6
|
+
Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
7
|
+
Project-URL: Repository, https://github.com/EulogySnowfall/SurrealDB-ORM-lite.git
|
|
8
|
+
Project-URL: Issues, https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Yannick Croteau <croteau.yannick@gmail.com>
|
|
11
|
+
License: # MIT License
|
|
12
|
+
|
|
13
|
+
Copyright (c) 2024-2026 Yannick Croteau
|
|
14
|
+
|
|
15
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
16
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
17
|
+
in the Software without restriction, including without limitation the rights
|
|
18
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
19
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
20
|
+
furnished to do so, subject to the following conditions:
|
|
21
|
+
|
|
22
|
+
The above copyright notice and this permission notice shall be included in all
|
|
23
|
+
copies or substantial portions of the Software.
|
|
24
|
+
|
|
25
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
26
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
27
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
28
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
29
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
30
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
31
|
+
SOFTWARE.
|
|
32
|
+
License-File: LICENSE
|
|
33
|
+
Keywords: async,database,orm,pydantic,surrealdb
|
|
34
|
+
Classifier: Development Status :: 3 - Alpha
|
|
35
|
+
Classifier: Framework :: Pydantic :: 2
|
|
36
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
37
|
+
Classifier: Operating System :: OS Independent
|
|
38
|
+
Classifier: Programming Language :: Python :: 3
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
42
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
43
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
44
|
+
Classifier: Topic :: Database
|
|
45
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
46
|
+
Classifier: Typing :: Typed
|
|
47
|
+
Requires-Python: >=3.11
|
|
48
|
+
Requires-Dist: pydantic>=2.13.4
|
|
49
|
+
Requires-Dist: surrealdb[pydantic]<3.0.0,>=2.0.0
|
|
50
|
+
Description-Content-Type: text/markdown
|
|
51
|
+
|
|
52
|
+
# Surreal ORM Lite
|
|
53
|
+
|
|
54
|
+

|
|
55
|
+

|
|
56
|
+

|
|
57
|
+

|
|
58
|
+
[](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
|
|
59
|
+
|
|
60
|
+
**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
|
+
|
|
62
|
+
- **Official SDK only**: built on `surrealdb[pydantic]`, no custom protocol, few dependencies.
|
|
63
|
+
- **Two server lines**: the same code runs on SurrealDB **2.x and 3.x**, and on the SDK's in-process engine
|
|
64
|
+
(`mem://`, `surrealkv://`) for tests and notebooks.
|
|
65
|
+
- **Django-style queries**: `filter(age__gte=18)`, `Q` objects, `order_by("-age")`, aggregations, subqueries.
|
|
66
|
+
- **SurrealDB-native**: graph relations and typed edges, live queries, change feeds, time travel, full-text, vector
|
|
67
|
+
and hybrid search, events, views and schema DDL.
|
|
68
|
+
- **Tooling**: migrations, a `surreal-orm-lite` command line, schema introspection, test factories and a pytest
|
|
69
|
+
plugin.
|
|
70
|
+
|
|
71
|
+
**Documentation**: [user guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md) ·
|
|
72
|
+
[changelog](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/CHANGELOG.md) ·
|
|
73
|
+
[roadmap](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ROADMAP.md) ·
|
|
74
|
+
[examples](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/tree/main/examples)
|
|
75
|
+
|
|
76
|
+
## Installation
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pip install surreal-orm-lite
|
|
80
|
+
# or
|
|
81
|
+
uv add surreal-orm-lite
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
| Dependency | Version |
|
|
85
|
+
| ------------ | ------------------------------------------------------------ |
|
|
86
|
+
| Python | 3.11+ (tested on 3.11 to 3.15) |
|
|
87
|
+
| SurrealDB | 2.6.x / 2.7.x or 3.2.x / 3.3.x, or the SDK's embedded engine |
|
|
88
|
+
| Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0 |
|
|
89
|
+
| Pydantic | >=2.13.4 |
|
|
90
|
+
|
|
91
|
+
## Quick start
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
import asyncio
|
|
95
|
+
|
|
96
|
+
from pydantic import Field
|
|
97
|
+
|
|
98
|
+
from surreal_orm_lite import BaseSurrealModel, Q, SurrealDBConnectionManager
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
class User(BaseSurrealModel):
|
|
102
|
+
id: str | None = None
|
|
103
|
+
name: str = Field(..., max_length=100)
|
|
104
|
+
email: str
|
|
105
|
+
age: int = Field(..., ge=0)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
async def main() -> None:
|
|
109
|
+
# A server URL (ws://localhost:8000/rpc, http://localhost:8000) or an in-process engine (mem://).
|
|
110
|
+
SurrealDBConnectionManager.set_connection(
|
|
111
|
+
url="http://localhost:8000", user="root", password="root", namespace="app", database="app"
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
alice = await User(id="alice", name="Alice", email="alice@example.com", age=30).save()
|
|
115
|
+
await User(id="bob", name="Bob", email="bob@example.com", age=17).save()
|
|
116
|
+
|
|
117
|
+
adults = await User.objects().filter(age__gte=18).order_by("-age").exec()
|
|
118
|
+
a_or_minor = await User.objects().filter(Q(name__startswith="A") | Q(age__lt=18)).exec()
|
|
119
|
+
average = await User.objects().avg("age")
|
|
120
|
+
|
|
121
|
+
await alice.merge(age=31) # partial update
|
|
122
|
+
await alice.delete()
|
|
123
|
+
print(adults, a_or_minor, average)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
asyncio.run(main())
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The [getting started guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/getting-started.md)
|
|
130
|
+
walks through it, and the [querying guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/querying.md)
|
|
131
|
+
lists every QuerySet method and filter lookup.
|
|
132
|
+
|
|
133
|
+
## Documentation
|
|
134
|
+
|
|
135
|
+
| Guide | What it covers |
|
|
136
|
+
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
137
|
+
| [Getting started](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/getting-started.md) | Requirements, installation, connection, a first model and CRUD |
|
|
138
|
+
| [Models](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/models.md) | Primary keys, table names, server-side values, computed fields, field aliases |
|
|
139
|
+
| [Field types](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/fields.md) | Datetimes, durations, decimals, sets, ranges, record links, geospatial fields |
|
|
140
|
+
| [Querying](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/querying.md) | QuerySet methods, filter lookups, `Q` objects, `FETCH`, aggregations, time travel, subqueries, query cache |
|
|
141
|
+
| [Writing data](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/writing.md) | Bulk operations, signals, transactions, upserts, patches, retry on conflict |
|
|
142
|
+
| [Relations and graph](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/relations.md) | Graph relations, typed edges, `TYPE RELATION` constraints |
|
|
143
|
+
| [Stored functions and events](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/functions-and-events.md) | `call_function()`, `DEFINE EVENT` and `DEFINE FUNCTION` from Python |
|
|
144
|
+
| [Authentication](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/authentication.md) | `signin` / `signup`, record access, `AuthenticatedUserMixin` |
|
|
145
|
+
| [Live queries and change feeds](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/realtime.md) | Live queries, typed streams, auto-resubscribe, change feeds |
|
|
146
|
+
| [Connections](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/connections.md) | The connection manager, event loops, several databases |
|
|
147
|
+
| [Embedded engine](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/embedded.md) | `mem://` and `surrealkv://` in-process databases, test fixtures |
|
|
148
|
+
| [Schema and DDL](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/schema.md) | Schema introspection, materialized views, table DDL and permissions |
|
|
149
|
+
| [Search](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/search.md) | Full-text (BM25), vector (KNN, HNSW) and hybrid search |
|
|
150
|
+
| [Migrations](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/migrations.md) | `makemigrations()`, operations, `MigrationExecutor` |
|
|
151
|
+
| [Command line](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/cli.md) | `surreal-orm-lite`: migrate, rollback, inspectdb, schemadiff, shell |
|
|
152
|
+
| [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 |
|
|
154
|
+
|
|
155
|
+
The [documentation index](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md) lists every section of the guides.
|
|
156
|
+
|
|
157
|
+
## Features
|
|
158
|
+
|
|
159
|
+
| Feature | Status |
|
|
160
|
+
| ----------------------------------------------------------------------------- | ------ |
|
|
161
|
+
| Async/await support | ✅ |
|
|
162
|
+
| Pydantic validation | ✅ |
|
|
163
|
+
| CRUD operations | ✅ |
|
|
164
|
+
| QuerySet with filters | ✅ |
|
|
165
|
+
| Django-style lookups | ✅ |
|
|
166
|
+
| Custom primary keys | ✅ |
|
|
167
|
+
| HTTP connections | ✅ |
|
|
168
|
+
| WebSocket connections | ✅ |
|
|
169
|
+
| Aggregations | ✅ |
|
|
170
|
+
| GROUP BY | ✅ |
|
|
171
|
+
| Model Signals | ✅ |
|
|
172
|
+
| Raw SurrealQL queries | ✅ |
|
|
173
|
+
| Q Objects (OR/AND/NOT) | ✅ |
|
|
174
|
+
| Parameterized filters | ✅ |
|
|
175
|
+
| Bulk operations | ✅ |
|
|
176
|
+
| `-field` ordering | ✅ |
|
|
177
|
+
| Relations & Graph | ✅ |
|
|
178
|
+
| FETCH clause | ✅ |
|
|
179
|
+
| Transactions (`tx=`) | ✅ |
|
|
180
|
+
| upsert / get_or_create | ✅ |
|
|
181
|
+
| patch / atomic ops | ✅ |
|
|
182
|
+
| Retry on conflict | ✅ |
|
|
183
|
+
| Server-side functions | ✅ |
|
|
184
|
+
| Computed fields | ✅ |
|
|
185
|
+
| Stored `fn::` calls | ✅ |
|
|
186
|
+
| JWT / record auth | ✅ |
|
|
187
|
+
| Model-level auth mixin | ✅ |
|
|
188
|
+
| Field aliases & DX | ✅ |
|
|
189
|
+
| Live queries (raw) | ✅ |
|
|
190
|
+
| Typed live queries | ✅ |
|
|
191
|
+
| Live auto-resubscribe | ✅ |
|
|
192
|
+
| Change feeds (CDC) | ✅ |
|
|
193
|
+
| Typed edges (`insert_relation`) | ✅ |
|
|
194
|
+
| Custom table name | ✅ |
|
|
195
|
+
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range) | ✅ |
|
|
196
|
+
| Geospatial fields (nearby, distance, spatial lookups) | ✅ |
|
|
197
|
+
| Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
|
|
198
|
+
| Time travel (`as_of()`, versioned storage) | ✅ |
|
|
199
|
+
| Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
|
|
200
|
+
| Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
|
|
201
|
+
| Multiple databases (named connections, `using()`) | ✅ |
|
|
202
|
+
| Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
|
|
203
|
+
| Server-side events & function DDL (`Event`, `define_function()`) | ✅ |
|
|
204
|
+
| Materialized views (`view_query`, `define_view()`, read-only) | ✅ |
|
|
205
|
+
| Relation constraints (`relation_in`, `define_relation()`, `TYPE RELATION`) | ✅ |
|
|
206
|
+
| Model table DDL (`define_table()`, `schema_mode`, `permissions`) | ✅ |
|
|
207
|
+
| Full-text search (`search()`, BM25 score and highlights) | ✅ |
|
|
208
|
+
| Vector search (`similar_to()`, KNN, HNSW indexes) | ✅ |
|
|
209
|
+
| Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion) | ✅ |
|
|
210
|
+
| Migrations (makemigrations / migrate / rollback) | ✅ |
|
|
211
|
+
| Command line (`surreal-orm-lite`: migrations, inspectdb, shell) | ✅ |
|
|
212
|
+
| Test data factories (`ModelFactory`, `Faker`) & pytest plugin | ✅ |
|
|
213
|
+
|
|
214
|
+
## Supported versions
|
|
215
|
+
|
|
216
|
+
Surreal ORM Lite runs on **both** SurrealDB release lines, 2.x (2.6 / 2.7) and 3.x (3.2 / 3.3), and on the official
|
|
217
|
+
SDK's in-process engine. It is tested against SurrealDB **v2.7.0** and **v3.3.5**; SurrealDB
|
|
218
|
+
3.1.5 is run as a backward-compatibility check. A few capabilities rely on server features introduced in SurrealDB
|
|
219
|
+
3.x: on 2.x the ORM degrades gracefully or says so before sending anything. The
|
|
220
|
+
[compatibility guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/compatibility.md) lists every tested version and every difference between the two lines
|
|
221
|
+
and the embedded engine.
|
|
222
|
+
|
|
223
|
+
## SurrealDB-ORM-lite vs SurrealDB-ORM
|
|
224
|
+
|
|
225
|
+
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.
|
|
226
|
+
|
|
227
|
+
Both projects target the same feature set; the difference is **how** (official SDK vs custom
|
|
228
|
+
SDK) and **server support**. Everything below is on the lite roadmap via the official SDK 2.0
|
|
229
|
+
— only the custom-SDK internals stay exclusive to the full ORM; the official SDK's in-process engine (section 26) is lite-only.
|
|
230
|
+
|
|
231
|
+
| Feature | ORM-lite (official SDK) | ORM (custom SDK) |
|
|
232
|
+
| ----------------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
|
|
233
|
+
| Supported SurrealDB | **2.6/2.7 + 3.2/3.3** | 3.x only |
|
|
234
|
+
| CRUD & QuerySet | ✅ | ✅ |
|
|
235
|
+
| Aggregations & GROUP BY | ✅ | ✅ |
|
|
236
|
+
| Model Signals | ✅ | ✅ |
|
|
237
|
+
| Bulk Operations | ✅ | ✅ |
|
|
238
|
+
| Q Objects (OR/AND/NOT) | ✅ | ✅ |
|
|
239
|
+
| Parameterized Filters | ✅ | ✅ |
|
|
240
|
+
| Relations & Graph | ✅ (reverse, keyword edge fields, tx= on every write helper: v0.22.0) | ✅ |
|
|
241
|
+
| FETCH clause | ✅ | ✅ |
|
|
242
|
+
| Transactions (tx=) | ✅ v0.8 (core), v0.9 QS | ✅ |
|
|
243
|
+
| Interactive tx (3.x native) | ✅ v0.9 | ✅ |
|
|
244
|
+
| upsert / update_or_create | ✅ v0.10.0 | ✅ |
|
|
245
|
+
| Atomic field/array operations | ✅ v0.11.0 | ✅ |
|
|
246
|
+
| Retry on conflict | ✅ v0.12.0 | ✅ |
|
|
247
|
+
| SurrealFunc & server values | ✅ v0.13.0 | ✅ |
|
|
248
|
+
| Computed fields | ✅ v0.14.0 | ✅ |
|
|
249
|
+
| `call_function()` (`fn::`) | ✅ v0.15.0 | ✅ |
|
|
250
|
+
| JWT Authentication | ✅ v0.16.0 (connection) | ✅ |
|
|
251
|
+
| Model auth mixin | ✅ v0.17.0 | ✅ |
|
|
252
|
+
| Field Aliases & DX | ✅ v0.18.0 | ✅ |
|
|
253
|
+
| Live queries (raw notifs) | ✅ v0.19.0 | ✅ |
|
|
254
|
+
| Typed live queries | ✅ v0.20.0 | ✅ |
|
|
255
|
+
| Live auto-resubscribe / CDC | ✅ v0.21.0 | ✅ |
|
|
256
|
+
| Native typed relations | ✅ v0.22.0 (typed edge models) | ✅ DDL only (TableType.RELATION) |
|
|
257
|
+
| Rich field types | ✅ v0.23.0 | ✅ |
|
|
258
|
+
| Geospatial Fields | ✅ v0.24.0 | ✅ |
|
|
259
|
+
| Embedded engine | ✅ v0.25.0 (mem://, surrealkv://; rocksdb:// #233) | ❌ (HTTP/WebSocket only) |
|
|
260
|
+
| Time travel (`VERSION`) | ✅ v0.26.0 (`as_of()`) | ❌ |
|
|
261
|
+
| Subqueries | ✅ v0.27.0 (`Subquery`, a QuerySet in `filter()`) | ✅ |
|
|
262
|
+
| Query Cache | ✅ v0.28.0 (`cache()`, `QueryCache`) | ✅ |
|
|
263
|
+
| Multi-database | ✅ v0.29.0 (`add_connection()`, `using()`) | ✅ |
|
|
264
|
+
| Schema Introspection | ✅ v0.30.0 (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
|
|
265
|
+
| DEFINE EVENT | ✅ v0.31.0 (`Event`, `define_events()`, `ASYNC` on 3.x) | ✅ migrations (`DefineEvent`) |
|
|
266
|
+
| `define_function()` (DDL) | ✅ v0.31.0 | ❌ |
|
|
267
|
+
| Materialized views | ✅ v0.32.0 (`view_query`, `define_view()`) | ✅ |
|
|
268
|
+
| TYPE RELATION enforcement | ✅ v0.33.0 (`relation_in`, `define_relation()`) | ✅ DDL (`TableType.RELATION`, migrations) |
|
|
269
|
+
| Model table DDL | ✅ v0.34.0 (`define_table()`) | ✅ |
|
|
270
|
+
| Full-Text Search | ✅ v0.35.0 (`search()`) | ✅ |
|
|
271
|
+
| Vector Search (KNN/HNSW) | ✅ v0.36.0 (`similar_to()`) | ✅ |
|
|
272
|
+
| Hybrid Search (RRF) | ✅ v0.37.0 (`hybrid_search()`) | ✅ |
|
|
273
|
+
| Migrations & CLI | ✅ v0.38.0 (migrations), ✅ v0.39.0 (CLI) | ✅ |
|
|
274
|
+
| Test Fixtures & Factories | ✅ v0.25.0 SurrealFixture; ✅ v0.40.0 factories | ✅ |
|
|
275
|
+
| Retry, Logging, Metrics | v0.41.0 | ✅ |
|
|
276
|
+
| Connection Pool | post-GA (tentative) | ✅ |
|
|
277
|
+
| Custom SDK / CBOR Protocol | ❌ never | ✅ |
|
|
278
|
+
|
|
279
|
+
**Choose ORM-lite** if you want the official SDK, minimal dependencies, support for SurrealDB
|
|
280
|
+
2.x (2.6 / 2.7) **and** 3.x (3.2 / 3.3), and a full feature roadmap built entirely on the official SDK.
|
|
281
|
+
|
|
282
|
+
**Choose ORM** if you need the custom-SDK internals (CBOR protocol, native connection pool)
|
|
283
|
+
or those features available today rather than on the roadmap.
|
|
284
|
+
|
|
285
|
+
- **SurrealDB-ORM GitHub**: [github.com/EulogySnowfall/SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
|
|
286
|
+
- **SurrealDB-ORM PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
|
|
287
|
+
|
|
288
|
+
## Project status
|
|
289
|
+
|
|
290
|
+
Surreal ORM Lite is in **alpha** (0.x): every Tier 1 to Tier 3 feature of the roadmap has shipped, and the next
|
|
291
|
+
release, v0.41.0, opens the **beta** phase (API freeze and hardening) on the way to GA as v2.0.0, numbered after the
|
|
292
|
+
official SDK 2.0. The [release overview](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md#roadmap) lists every release, and
|
|
293
|
+
[docs/ROADMAP.md](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ROADMAP.md) details each one.
|
|
294
|
+
|
|
295
|
+
## Contributing
|
|
296
|
+
|
|
297
|
+
Contributions are welcome: see the [contributing guide](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/contributing.md). Report a vulnerability as the
|
|
298
|
+
[security policy](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/SECURITY.md) describes, not in a public issue.
|
|
299
|
+
|
|
300
|
+
## License
|
|
301
|
+
|
|
302
|
+
MIT License - see [LICENSE](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/LICENSE) for details.
|
|
303
|
+
|
|
304
|
+
## Author
|
|
305
|
+
|
|
306
|
+
**Yannick Croteau**
|
|
307
|
+
GitHub: [@EulogySnowfall](https://github.com/EulogySnowfall)
|
|
308
|
+
|
|
309
|
+
## Related Projects
|
|
310
|
+
|
|
311
|
+
- [SurrealDB](https://surrealdb.com/) - The database
|
|
312
|
+
- [surrealdb.py](https://github.com/surrealdb/surrealdb.py) - Official Python SDK
|
|
313
|
+
- [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) - Full-featured ORM with custom SDK
|