surreal-orm-lite 0.7.0__tar.gz → 0.10.0__tar.gz

{surreal_orm_lite-0.7.0 → surreal_orm_lite-0.10.0}/CHANGELOG.md

@@ -5,6 +5,110 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-06-07
+
+### Added
+
+- **`model.upsert()`** — insert-or-replace by explicit id, backed by the SDK's native
+  `upsert()` (`UPSERT $record CONTENT $data`, full REPLACE). Supports `tx=` (buffered onto
+  the transaction).
+
+  ```python
+  user = User(id="alice", name="Alice", status="active")
+  await user.upsert()  # CREATE if absent, full REPLACE if present
+  ```
+
+- **`QuerySet.update_or_create()` / `QuerySet.get_or_create()`** — Django-style
+  criteria-based create-or-update returning `(instance, created)`. Writes route through
+  `save()` / `merge()`, so lifecycle signals fire, SDK errors normalise to `SurrealDbError`,
+  and the primary key anchors record identity. `update_or_create` does a **partial merge** on
+  update — fields outside the criteria/defaults are preserved — while `get_or_create` returns
+  an existing match untouched. Non-`exact` lookups (e.g. `name__contains`) drive the lookup
+  but are not written. A SELECT-guard raises an explicit `SurrealDbError` when the criteria
+  match more than one record.
+
+  ```python
+  user, created = await User.objects().update_or_create(
+      email="alice@example.com", defaults={"name": "Alice"}
+  )
+  user, created = await User.objects().get_or_create(
+      email="bob@example.com", defaults={"name": "Bob"}
+  )
+  ```
+
+### Notes
+
+- Behaviour is **identical on SurrealDB 2.6.x and 3.x** (no 3.x-only primitive): the native
+  `upsert()` call and the SELECT-guard work the same on both lines (verified by spike).
+- `upsert()` is REPLACE, not merge: fields omitted from the model are dropped. Use `merge()`
+  for partial updates.
+- `update_or_create` / `get_or_create` do the lookup and the write in two round-trips
+  (SurrealDB 2.6.x exposes no row-locking primitive here), so a small race window exists
+  under concurrent writers — the same non-atomic fallback Django documents.
+- Under `objects(tx=)`, `update_or_create` / `get_or_create` participate in the transaction on
+  SurrealDB 3.x (interactive); a buffered 2.6.x transaction raises on their lookup read
+  (reads inside a buffered transaction are unsupported — consistent with other QuerySet reads).
+
+## [0.9.0] - 2026-06-07
+
+### Added
+
+- **Transactions ORM — QuerySet & interactive strategy**: `objects(tx=)` plumbing routes
+  `QuerySet` reads (`get`, `first`, `all`, `exec`, `count`, `exists`, aggregations) and bulk
+  operations (`bulk_create`, `bulk_update`, `bulk_delete`) through the transaction.
+  Example:
+
+  ```python
+  async with SurrealDBConnectionManager.transaction() as tx:
+      users = await User.objects(tx=tx).filter(status="active").exec()
+      await User.objects(tx=tx).filter(role="guest").bulk_update(role="member")
+  ```
+
+- **Two transaction strategies** (auto-selected by `transaction()` based on URL + server):
+
+  - `InteractiveTransaction` (WebSocket + SurrealDB 3.x): uses the SDK's native
+    `begin()`/`commit()`/`cancel()` API tagged by `txn_id`. Reads inside the transaction
+    see uncommitted writes; `save(tx=)` now supports **auto-generated ids** and `refresh(tx=)`
+    works.
+  - `BufferedTransaction` (HTTP, or WebSocket on SurrealDB 2.6.x): preserves the v0.8.0
+    `BEGIN…COMMIT` batching semantics. Reads inside the transaction still raise.
+
+- Exported `BufferedTransaction` and `InteractiveTransaction` (in addition to the `Transaction`
+  base type) for typing and inspection.
+
+### Changed
+
+- `transaction()` now **cancels** on a commit failure (e.g. server-side rollback surfacing at
+  `COMMIT`), so an interactive transaction never leaves the shared connection half-open.
+
+### Fixed
+
+- `QuerySet.get(id)` inside an interactive transaction now normalises the SDK's
+  `NotFoundError` to `SurrealDbNotFoundError`, matching the non-tx path.
+
+### Notes
+
+- `bulk_update()`/`bulk_delete()` return `0` on the buffered strategy (the affected-row
+  count is not knowable before commit). On the interactive strategy they return the real
+  count.
+
+## [0.8.0] - 2026-06-06
+
+### Added
+
+- **Transactions ORM (core)**: `async with SurrealDBConnectionManager.transaction() as tx:`
+  context manager plus a `tx=` parameter on `save()`, `update()`, `merge()`, and `delete()`.
+  Operations are buffered and committed atomically as a single
+  `BEGIN TRANSACTION; … COMMIT TRANSACTION;` query; an exception in the block rolls
+  everything back.
+- Exported `Transaction`.
+
+### Notes
+
+- Inside a transaction, `save()` requires an explicit record id (auto-generated ids are not
+  buffered in this release). Reads/`refresh()` inside a transaction raise a clear error and
+  are planned for v0.9.0 (QuerySet `objects(tx=)` + savepoints).
+
 ## [0.7.0] - 2026-06-06
 
 ### Added

{surreal_orm_lite-0.7.0 → surreal_orm_lite-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.7.0
+Version: 0.10.0
 Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -71,12 +71,12 @@ This ORM is designed to:
 
 ## Requirements
 
-| Dependency   | Version                            |
-| ------------ | ---------------------------------- |
-| Python       | 3.11+                              |
-| SurrealDB    | 2.6.x or 3.1.x                     |
-| Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0  |
-| Pydantic     | >=2.13.4                           |
+| Dependency   | Version                           |
+| ------------ | --------------------------------- |
+| Python       | 3.11+                             |
+| SurrealDB    | 2.6.x or 3.1.x                    |
+| Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0 |
+| Pydantic     | >=2.13.4                          |
 
 > **Note**: As of v0.7.0, Surreal ORM Lite targets the SurrealDB Python SDK 2.x (`surrealdb[pydantic]>=2.0.0,<3.0.0`), which supports the SurrealDB 3.x protocol. It is tested against SurrealDB **v2.6.5** and **v3.1.3**.
 
@@ -203,6 +203,8 @@ results = await User.objects().query(
 | `-field` ordering      | ✅     |
 | Relations & Graph      | ✅     |
 | FETCH clause           | ✅     |
+| Transactions (`tx=`)   | ✅     |
+| upsert / get_or_create | ✅     |
 
 ### Supported Filter Lookups
 
@@ -358,6 +360,73 @@ async def time_user_save(sender, instance, **kwargs):
     print(f"Save took {duration:.3f}s")
 ```
 
+### 11. Transactions (atomic, all-or-nothing)
+
+```python
+from surreal_orm_lite import SurrealDBConnectionManager
+
+# All operations commit together, or none do.
+async with SurrealDBConnectionManager.transaction() as tx:
+    await User(id="alice", name="Alice").save(tx=tx)
+    await Order(id="o1", user="User:alice", total=100).save(tx=tx)
+
+    # v0.9.0: QuerySet reads & bulk ops participate in the transaction.
+    actives = await User.objects(tx=tx).filter(status="active").exec()
+    await User.objects(tx=tx).filter(role="guest").bulk_update(role="member")
+    # Auto-commit on success; auto-rollback if the block raises.
+```
+
+`transaction()` picks the strategy automatically based on the connection:
+
+- **WebSocket + SurrealDB 3.x** → `InteractiveTransaction` (native `begin()`/`commit()`/`cancel()`).
+  Reads inside the tx see uncommitted writes; `save(tx=)` supports auto-generated ids;
+  `refresh(tx=)` and `QuerySet.objects(tx=)` reads work.
+- **HTTP, or WebSocket on SurrealDB 2.6.x** → `BufferedTransaction`. Writes are buffered and
+  flushed as one `BEGIN TRANSACTION; …; COMMIT TRANSACTION;` query at commit; reads inside the
+  tx raise; `save(tx=)` requires an explicit `id`. `bulk_update`/`bulk_delete` return `0`
+  (the row count is not knowable before commit).
+
+### 12. Upsert & get_or_create / update_or_create
+
+```python
+from surreal_orm_lite import BaseSurrealModel, SurrealConfigDict
+
+
+class User(BaseSurrealModel):
+    model_config = SurrealConfigDict(primary_key="id")
+    id: str | None = None
+    name: str
+    email: str
+
+
+# Insert-or-replace by explicit id (full REPLACE — omitted fields are dropped).
+# Use merge() instead if you only want a partial update.
+await User(id="alice", name="Alice", email="alice@example.com").upsert()
+
+# Criteria-based, Django-style; returns (instance, created).
+# update_or_create: on create, writes criteria + defaults; on update, MERGEs them (a partial
+# update — fields outside the criteria/defaults are preserved). Lifecycle signals fire on both
+# paths, and the primary key anchors the record identity.
+user, created = await User.objects().update_or_create(
+    email="alice@example.com", defaults={"name": "Alice"}
+)
+
+# get_or_create writes the defaults ONLY when creating; an existing match is returned as-is:
+user, created = await User.objects().get_or_create(
+    email="bob@example.com", defaults={"name": "Bob"}
+)
+
+# Both participate in a transaction via objects(tx=) (interactive on SurrealDB 3.x):
+async with SurrealDBConnectionManager.transaction() as tx:
+    user, created = await User.objects(tx=tx).get_or_create(email="z@x.io", defaults={"name": "Z"})
+```
+
+If the lookup criteria match more than one record, both methods raise `SurrealDbError`
+(the criteria are not unique). Non-`exact` lookups (e.g. `name__contains`) drive the lookup
+but are not written to the record. Without a transaction the behaviour is identical on
+SurrealDB 2.6.x and 3.x; under `objects(tx=)` they participate in the transaction on 3.x,
+while a buffered 2.6.x transaction raises on the lookup (see the behaviour table).
+
 ---
 
 ## Configuration Options
@@ -389,12 +458,33 @@ async with SurrealDBConnectionManager():
 
 As of v0.7.0, Surreal ORM Lite uses `surrealdb[pydantic]>=2.0.0,<3.0.0` (SurrealDB 3.x protocol) and is tested against both major SurrealDB release lines.
 
-| SurrealDB Version | SDK Version | Status             |
-| ----------------- | ----------- | ------------------ |
-| 3.1.3             | 2.0         | ✅ Tested          |
-| 2.6.5             | 2.0         | ✅ Tested          |
-| 2.6.x             | 2.0         | ✅ Compatible      |
-| < 2.6 or > 3.1    | —           | ⚠️ Not guaranteed  |
+**Compatibility advantage over the full ORM**: ORM-lite runs on **both** SurrealDB **2.6.x and 3.1**, while the full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) (custom SDK) targets **3.x only**. Lite stays usable on existing 2.6.x deployments without forcing a server upgrade.
+
+| SurrealDB Version | SDK Version | Status            |
+| ----------------- | ----------- | ----------------- |
+| 3.1.3             | 2.0         | ✅ Tested         |
+| 2.6.5             | 2.0         | ✅ Tested         |
+| 2.6.x             | 2.0         | ✅ Compatible     |
+| < 2.6 or > 3.1    | —           | ⚠️ Not guaranteed |
+
+### ORM behaviour: SurrealDB 2.6.x vs 3.x
+
+Surreal ORM Lite runs on both lines; some capabilities differ because they rely on server
+features introduced in SurrealDB 3.x. On 2.6.x the ORM degrades gracefully. Capabilities not
+listed behave the same on both lines.
+
+| ORM capability | SurrealDB 2.6.x | SurrealDB 3.x (3.1.3) | Since |
+| -------------- | --------------- | --------------------- | ----- |
+| Transaction strategy auto-selected by `transaction()` | buffered batch (`BEGIN…COMMIT`) | native interactive on WebSocket | v0.9.0 |
+| Reads inside a transaction (`objects(tx=)`) | raise (buffered cannot read) | see uncommitted writes | v0.9.0 |
+| `save(tx=)` with an auto-generated id | raises — explicit id required | supported | v0.9.0 |
+| `refresh(tx=)` inside a transaction | raises | works | v0.9.0 |
+| `bulk_update` / `bulk_delete` row count inside a tx | returns `0` (not knowable pre-commit) | real count | v0.9.0 |
+| "Already exists" error on create | normalised to `SurrealDbError` | normalised to `SurrealDbError` | v0.7.0 |
+| Cleanup on a missing target (`delete_table`, `remove_relation`) | native no-op | ORM makes it a silent no-op | v0.7.0 |
+| Aggregation over an empty set (`NaN` / `±inf`) | returns `0.0` / `None` | ORM normalises to `0.0` / `None` | v0.7.0 |
+| Namespace/db selection (`use()` ordering) | lenient (auto-creates) | strict — ORM signs in before `use()` | v0.7.0 |
+| `upsert()` / `update_or_create()` / `get_or_create()` | same on both lines | same on both lines | v0.10.0 |
 
 > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
 
@@ -414,19 +504,21 @@ Contributions are welcome! Please:
 
 ## Roadmap
 
-| Version | Theme                              | Status      |
-| ------- | ---------------------------------- | ----------- |
-| v0.2.x  | Core ORM (CRUD, QuerySet)          | ✅ Released |
-| v0.3.0  | Aggregations & Utilities           | ✅ Released |
-| v0.4.0  | Model Signals                      | ✅ Released |
-| v0.5.0  | Bulk Operations & Q Objects        | ✅ Released |
-| v0.6.0  | Relations & Graph                  | ✅ Released |
-| v0.7.0  | SDK 2.0 / SurrealDB 3.x migration  | ✅ Released |
-| v0.8.0  | Transactions ORM                   | 📋 Planned  |
-| v0.9.0  | SurrealFunc & Computed Fields      | 📋 Planned  |
-| v0.10.0 | FETCH, Field Aliases & DX          | 📋 Planned  |
-| v0.11.0 | Beta Phase                         | 📋 Planned  |
-| v1.0.0  | Production Ready                   | 📋 Planned  |
+| Version           | Theme                                            | Status      |
+| ----------------- | ------------------------------------------------ | ----------- |
+| v0.2.x – v0.7.0   | Core ORM → SDK 2.0 / SurrealDB 3.x migration     | ✅ Released |
+| v0.8.0            | Transactions ORM (`tx=`)                         | ✅ Released |
+| v0.9.0            | Transactions — QuerySet & interactive (3.x)      | ✅ Released |
+| v0.10.0           | upsert / update_or_create / get_or_create        | ✅ Released |
+| v0.11.0 – v0.22.0 | Tier 1 — Core (auth, live, relations, …)         | 📋 Planned  |
+| v0.23.0 – v0.29.0 | Tier 2 — Extended (rich types, geo, subqueries)  | 📋 Planned  |
+| v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned  |
+| v0.40.0           | Beta Phase (API freeze, hardening)               | 📋 Planned  |
+| v2.0.0            | Production / GA (aligned with SDK 2.0)           | 📋 Planned  |
+
+> Every roadmap feature is implementable with the **official SDK 2.0** (native methods or
+> `query()` SurrealQL) — no custom SDK. GA is numbered **v2.0.0** to mirror SDK 2.0; the `1.x`
+> line is intentionally skipped.
 
 See [docs/ROADMAP.md](docs/ROADMAP.md) for full details.
 
@@ -436,37 +528,52 @@ See [docs/ROADMAP.md](docs/ROADMAP.md) for full details.
 
 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.
 
-| Feature                   | ORM-lite (official SDK) | ORM (custom SDK) |
-| ------------------------- | ----------------------- | ---------------- |
-| CRUD & QuerySet           | ✅                      | ✅               |
-| Aggregations & GROUP BY   | ✅                      | ✅               |
-| Model Signals             | ✅                      | ✅               |
-| Bulk Operations           | ✅                      | ✅               |
-| Q Objects (OR/AND/NOT)    | ✅                      | ✅               |
-| Parameterized Filters     | ✅                      | ✅               |
-| Relations & Graph         | ✅                      | ✅               |
-| FETCH clause              | ✅                      | ✅               |
-| Transactions (tx=)        | v0.8.0                  | ✅               |
-| SurrealFunc & Computed    | v0.9.0                  | ✅               |
-| Field Aliases             | v0.10.0                 | ✅               |
-| Retry, Logging, Metrics   | v0.11.0                 | ✅               |
-| Live Models / CDC         | ❌                      | ✅               |
-| Vector / Full-Text Search | ❌                      | ✅               |
-| Hybrid Search (RRF)       | ❌                      | ✅               |
-| Migrations & CLI          | ❌                      | ✅               |
-| JWT Authentication        | ❌                      | ✅               |
-| Schema Introspection      | ❌                      | ✅               |
-| Connection Pool           | ❌                      | ✅               |
-| CBOR Protocol             | ❌                      | ✅               |
-| Subqueries & Query Cache  | ❌                      | ✅               |
-| Geospatial Fields         | ❌                      | ✅               |
-| DEFINE EVENT              | ❌                      | ✅               |
-| Test Fixtures & Factories | ❌                      | ✅               |
-| Atomic Array Operations   | ❌                      | ✅               |
-
-**Choose ORM-lite** if you want the official SDK, minimal dependencies, and core ORM features.
-
-**Choose ORM** if you need live queries, migrations, authentication, vector search, or advanced features.
+Both projects target the same feature set; the difference is **how** (official SDK vs custom
+SDK) and **server support**. Everything below is on the lite roadmap via the official SDK 2.0
+— only the custom-SDK internals stay exclusive to the full ORM.
+
+| Feature                       | ORM-lite (official SDK) | ORM (custom SDK) |
+| ----------------------------- | ----------------------- | ---------------- |
+| Supported SurrealDB           | **2.6.x + 3.1**         | 3.x only         |
+| CRUD & QuerySet               | ✅                      | ✅               |
+| Aggregations & GROUP BY       | ✅                      | ✅               |
+| Model Signals                 | ✅                      | ✅               |
+| Bulk Operations               | ✅                      | ✅               |
+| Q Objects (OR/AND/NOT)        | ✅                      | ✅               |
+| Parameterized Filters         | ✅                      | ✅               |
+| Relations & Graph             | ✅                      | ✅               |
+| FETCH clause                  | ✅                      | ✅               |
+| Transactions (tx=)            | ✅ v0.8 (core), v0.9 QS | ✅               |
+| Interactive tx (3.x native)   | ✅ v0.9                 | ✅               |
+| upsert / update_or_create     | ✅ v0.10.0              | ✅               |
+| Atomic field/array operations | v0.11.0                 | ✅               |
+| Retry on conflict             | v0.12.0                 | ✅               |
+| SurrealFunc & Computed        | v0.13 – v0.14           | ✅               |
+| JWT Authentication            | v0.16 – v0.17           | ✅               |
+| Field Aliases & DX            | v0.18.0                 | ✅               |
+| Live Models / CDC             | v0.19 – v0.21           | ✅               |
+| Native typed relations        | v0.22.0                 | ✅               |
+| Rich field types              | v0.23.0                 | ✅               |
+| Geospatial Fields             | v0.24.0                 | ✅               |
+| Subqueries & Query Cache      | v0.27 – v0.28           | ✅               |
+| Multi-database                | v0.29.0                 | ✅               |
+| Schema Introspection          | v0.30.0                 | ✅               |
+| DEFINE EVENT                  | v0.31.0                 | ✅               |
+| Materialized views            | v0.32.0                 | ✅               |
+| Full-Text Search              | v0.34.0                 | ✅               |
+| Vector Search (KNN/HNSW)      | v0.35.0                 | ✅               |
+| Hybrid Search (RRF)           | v0.36.0                 | ✅               |
+| Migrations & CLI              | v0.37 – v0.38           | ✅               |
+| Test Fixtures & Factories     | v0.39.0                 | ✅               |
+| Retry, Logging, Metrics       | v0.40.0                 | ✅               |
+| Connection Pool               | post-GA (tentative)     | ✅               |
+| Custom SDK / CBOR Protocol    | ❌ never                | ✅               |
+
+**Choose ORM-lite** if you want the official SDK, minimal dependencies, support for SurrealDB
+2.6.x **and** 3.1, and a full feature roadmap built entirely on the official SDK.
+
+**Choose ORM** if you need the custom-SDK internals (CBOR protocol, native connection pool)
+or those features available today rather than on the roadmap.
 
 - **SurrealDB-ORM GitHub**: [github.com/EulogySnowfall/SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
 - **SurrealDB-ORM PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)