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.
Files changed (71) hide show
  1. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/CHANGELOG.md +37 -0
  2. surreal_orm_lite-0.40.1/PKG-INFO +313 -0
  3. surreal_orm_lite-0.40.1/README.md +262 -0
  4. surreal_orm_lite-0.40.1/docs/README.md +182 -0
  5. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/pyproject.toml +1 -1
  6. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/__init__.py +1 -1
  7. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_base.py +353 -35
  8. surreal_orm_lite-0.40.0/PKG-INFO +0 -8010
  9. surreal_orm_lite-0.40.0/README.md +0 -7959
  10. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/.gitignore +0 -0
  11. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/LICENSE +0 -0
  12. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/Makefile +0 -0
  13. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/_sdk.py +0 -0
  14. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/aggregations.py +0 -0
  15. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/auth.py +0 -0
  16. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cache.py +0 -0
  17. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/changefeed.py +0 -0
  18. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cli/__init__.py +0 -0
  19. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cli/__main__.py +0 -0
  20. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/cli/commands.py +0 -0
  21. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/concurrency.py +0 -0
  22. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/connection_config.py +0 -0
  23. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/connection_manager.py +0 -0
  24. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/constants.py +0 -0
  25. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/decoding.py +0 -0
  26. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/define_parser.py +0 -0
  27. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/edge.py +0 -0
  28. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/embedded.py +0 -0
  29. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/encoding.py +0 -0
  30. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/enum.py +0 -0
  31. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/exceptions.py +0 -0
  32. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/functions.py +0 -0
  33. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/geo.py +0 -0
  34. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/hybrid.py +0 -0
  35. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/introspection.py +0 -0
  36. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/live.py +0 -0
  37. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/__init__.py +0 -0
  38. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/autodetect.py +0 -0
  39. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/compare.py +0 -0
  40. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/constants.py +0 -0
  41. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/executor.py +0 -0
  42. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/generator.py +0 -0
  43. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/introspector.py +0 -0
  44. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/loader.py +0 -0
  45. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/migration.py +0 -0
  46. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/operations.py +0 -0
  47. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/render.py +0 -0
  48. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/migrations/state.py +0 -0
  49. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_auth.py +0 -0
  50. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_ddl.py +0 -0
  51. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/model_generator.py +0 -0
  52. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/py.typed +0 -0
  53. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/q.py +0 -0
  54. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/query_set.py +0 -0
  55. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/routing.py +0 -0
  56. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/schema.py +0 -0
  57. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/schema_state.py +0 -0
  58. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/search.py +0 -0
  59. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/signals.py +0 -0
  60. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/subquery.py +0 -0
  61. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/surql_literal.py +0 -0
  62. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
  63. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/database.py +0 -0
  64. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/factories.py +0 -0
  65. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  66. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/testing/pytest_plugin.py +0 -0
  67. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/time_travel.py +0 -0
  68. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/transaction.py +0 -0
  69. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/types.py +0 -0
  70. {surreal_orm_lite-0.40.0 → surreal_orm_lite-0.40.1}/src/surreal_orm_lite/utils.py +0 -0
  71. {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
+ ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
55
+ ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.5-purple)
56
+ ![SDK](https://img.shields.io/badge/SDK-Official%202.0-green)
57
+ ![License](https://img.shields.io/badge/license-MIT-blue)
58
+ [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](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