surreal-orm-lite 0.40.3__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.
Files changed (70) hide show
  1. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/CHANGELOG.md +49 -0
  2. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/PKG-INFO +98 -82
  3. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/README.md +94 -80
  4. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/docs/README.md +25 -8
  5. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/pyproject.toml +7 -2
  6. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/__init__.py +1 -1
  7. surreal_orm_lite-0.50.0/src/surreal_orm_lite/_client.py +460 -0
  8. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/_sdk.py +78 -21
  9. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/changefeed.py +7 -6
  10. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cli/commands.py +2 -2
  11. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/connection_manager.py +465 -120
  12. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/decoding.py +136 -177
  13. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/edge.py +3 -2
  14. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/embedded.py +23 -4
  15. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/encoding.py +48 -40
  16. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/geo.py +4 -4
  17. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/introspection.py +20 -10
  18. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/live.py +61 -23
  19. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/__init__.py +2 -1
  20. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/executor.py +200 -23
  21. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/render.py +55 -0
  22. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_auth.py +14 -4
  23. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_base.py +40 -37
  24. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/query_set.py +114 -57
  25. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/schema.py +10 -9
  26. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/schema_state.py +4 -1
  27. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/search.py +8 -6
  28. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/subquery.py +55 -4
  29. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/surql_literal.py +8 -22
  30. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/database.py +14 -9
  31. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/pytest_plugin.py +6 -3
  32. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/time_travel.py +3 -2
  33. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/transaction.py +13 -9
  34. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/types.py +13 -6
  35. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/utils.py +11 -15
  36. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/.gitignore +0 -0
  37. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/LICENSE +0 -0
  38. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/Makefile +0 -0
  39. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/aggregations.py +0 -0
  40. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/auth.py +0 -0
  41. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cache.py +0 -0
  42. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cli/__init__.py +0 -0
  43. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/cli/__main__.py +0 -0
  44. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/concurrency.py +0 -0
  45. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/connection_config.py +0 -0
  46. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/constants.py +0 -0
  47. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/define_parser.py +0 -0
  48. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/enum.py +0 -0
  49. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/exceptions.py +0 -0
  50. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/functions.py +0 -0
  51. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/hybrid.py +0 -0
  52. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/autodetect.py +0 -0
  53. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/compare.py +0 -0
  54. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/constants.py +0 -0
  55. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/generator.py +0 -0
  56. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/introspector.py +0 -0
  57. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/loader.py +0 -0
  58. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/migration.py +0 -0
  59. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/operations.py +0 -0
  60. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/migrations/state.py +0 -0
  61. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_ddl.py +0 -0
  62. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/model_generator.py +0 -0
  63. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/py.typed +0 -0
  64. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/q.py +0 -0
  65. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/routing.py +0 -0
  66. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/signals.py +0 -0
  67. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  68. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/factories.py +0 -0
  69. {surreal_orm_lite-0.40.3 → surreal_orm_lite-0.50.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  70. {surreal_orm_lite-0.40.3 → 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.40.3
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]<3.0.0,>=2.0.0
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
  ![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
+ ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.5%20%7C%204.0.0-purple)
58
+ ![SDK](https://img.shields.io/badge/SDK-Official%203.0-green)
57
59
  ![License](https://img.shields.io/badge/license-MIT-blue)
58
60
  [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](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]`, 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.
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.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 |
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 | Status |
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
- 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
231
- SDK's in-process engine. It is tested against SurrealDB **v2.7.0** and **v3.3.5**; SurrealDB
232
- 3.1.5 is run as a backward-compatibility check. A few capabilities rely on server features introduced in SurrealDB
233
- 3.x: on 2.x the ORM degrades gracefully or says so before sending anything. The
234
- [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
235
- and the embedded engine.
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 2.0
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** | 3.x only |
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.41.0 | ✅ |
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) **and** 3.x (3.2 / 3.3), and a full feature roadmap built entirely on the official SDK.
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 the next
305
- release, v0.41.0, opens the **beta** phase (API freeze and hardening) on the way to GA as v2.0.0, numbered after the
306
- official SDK 2.0. The [release overview](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md#roadmap) lists every release, and
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
  ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
4
- ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.5-purple)
5
- ![SDK](https://img.shields.io/badge/SDK-Official%202.0-green)
4
+ ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.5%20%7C%204.0.0-purple)
5
+ ![SDK](https://img.shields.io/badge/SDK-Official%203.0-green)
6
6
  ![License](https://img.shields.io/badge/license-MIT-blue)
7
7
  [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](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]`, no custom protocol, few dependencies.
12
- - **Two server lines**: the same code runs on SurrealDB **2.x and 3.x**, and on the SDK's in-process engine
13
- (`mem://`, `surrealkv://`) for tests and notebooks.
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.6.x / 2.7.x or 3.2.x / 3.3.x, or the SDK's embedded engine |
37
- | Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0 |
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 | Status |
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
- 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
180
- SDK's in-process engine. It is tested against SurrealDB **v2.7.0** and **v3.3.5**; SurrealDB
181
- 3.1.5 is run as a backward-compatibility check. A few capabilities rely on server features introduced in SurrealDB
182
- 3.x: on 2.x the ORM degrades gracefully or says so before sending anything. The
183
- [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
184
- and the embedded engine.
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 2.0
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** | 3.x only |
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.41.0 | ✅ |
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) **and** 3.x (3.2 / 3.3), and a full feature roadmap built entirely on the official SDK.
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 the next
254
- release, v0.41.0, opens the **beta** phase (API freeze and hardening) on the way to GA as v2.0.0, numbered after the
255
- official SDK 2.0. The [release overview](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md#roadmap) lists every release, and
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