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

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

@@ -5,6 +5,50 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.9.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
@@ -204,6 +204,7 @@ results = await User.objects().query(
 | Relations & Graph      | ✅     |
 | FETCH clause           | ✅     |
 | Transactions (`tx=`)   | ✅     |
+| upsert / get_or_create | ✅     |
 
 ### Supported Filter Lookups
 
@@ -385,6 +386,47 @@ async with SurrealDBConnectionManager.transaction() as tx:
   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
@@ -425,6 +467,25 @@ As of v0.7.0, Surreal ORM Lite uses `surrealdb[pydantic]>=2.0.0,<3.0.0` (Surreal
 | 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.
 
 ---
@@ -448,7 +509,8 @@ Contributions are welcome! Please:
 | 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 – v0.22.0 | Tier 1 — Core (auth, live, relations, …)         | 📋 Planned  |
+| 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  |
@@ -483,7 +545,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
 | FETCH clause                  | ✅                      | ✅               |
 | Transactions (tx=)            | ✅ v0.8 (core), v0.9 QS | ✅               |
 | Interactive tx (3.x native)   | ✅ v0.9                 | ✅               |
-| upsert / update_or_create     | v0.10.0                 | ✅               |
+| 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           | ✅               |

{surreal_orm_lite-0.9.0 → surreal_orm_lite-0.10.0}/README.md

@@ -154,6 +154,7 @@ results = await User.objects().query(
 | Relations & Graph      | ✅     |
 | FETCH clause           | ✅     |
 | Transactions (`tx=`)   | ✅     |
+| upsert / get_or_create | ✅     |
 
 ### Supported Filter Lookups
 
@@ -335,6 +336,47 @@ async with SurrealDBConnectionManager.transaction() as tx:
   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
@@ -375,6 +417,25 @@ As of v0.7.0, Surreal ORM Lite uses `surrealdb[pydantic]>=2.0.0,<3.0.0` (Surreal
 | 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.
 
 ---
@@ -398,7 +459,8 @@ Contributions are welcome! Please:
 | 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 – v0.22.0 | Tier 1 — Core (auth, live, relations, …)         | 📋 Planned  |
+| 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  |
@@ -433,7 +495,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
 | FETCH clause                  | ✅                      | ✅               |
 | Transactions (tx=)            | ✅ v0.8 (core), v0.9 QS | ✅               |
 | Interactive tx (3.x native)   | ✅ v0.9                 | ✅               |
-| upsert / update_or_create     | v0.10.0                 | ✅               |
+| 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           | ✅               |

{surreal_orm_lite-0.9.0 → surreal_orm_lite-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.9.0"
+version = "0.10.0"
 description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
 readme = "README.md"
 requires-python = ">=3.11"

{surreal_orm_lite-0.9.0 → surreal_orm_lite-0.10.0}/src/surreal_orm_lite/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 
 from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
 from .connection_manager import SurrealDBConnectionManager

{surreal_orm_lite-0.9.0 → surreal_orm_lite-0.10.0}/src/surreal_orm_lite/model_base.py

@@ -1,6 +1,7 @@
 import contextlib
 import logging
 import typing
+from collections.abc import Awaitable, Callable
 from typing import Any, Self
 
 from pydantic import BaseModel, ConfigDict, model_validator
@@ -251,30 +252,101 @@ class BaseSurrealModel(BaseModel):
         is deferred until the transaction commits successfully; if the tx rolls back,
         ``post_save`` is NOT emitted (the write never happened).
         """
+        return await self._save_with_signals(self._do_save, tx)
+
+    def _apply_record(self, record: Any) -> None:
+        """Copy a returned DB row's fields onto this instance (id kept as native ``RecordID``).
+
+        Accepts the raw SDK result (a row dict, a single-element list, or ``None``) and applies
+        only attributes the model actually declares. Shared by ``_do_save``/``_do_upsert`` so
+        the "apply the row the server gave back" step lives in one place.
+        """
+        if isinstance(record, list):
+            record = record[0] if record else None
+        if isinstance(record, dict):
+            for key, value in record.items():
+                if hasattr(self, key):
+                    object.__setattr__(self, key, value)
+
+    async def _save_with_signals(
+        self,
+        do_op: Callable[..., Awaitable[tuple[Self, bool]]],
+        tx: Transaction | None,
+    ) -> Self:
+        """Shared ``save``/``upsert`` signal envelope around the concrete write ``do_op``.
+
+        Emits ``pre_save`` → (``around_save`` wrap) → ``post_save``. In a transaction the write
+        is buffered, so ``around_save`` is skipped and ``post_save`` is deferred to a
+        successful commit — identical for both ``save()`` (``do_op=_do_save``) and ``upsert()``
+        (``do_op=_do_upsert``), so the contract can't drift between them.
+        """
         sender = self.__class__
         has_signals = pre_save.has_handlers(sender) or post_save.has_handlers(sender) or around_save.has_handlers(sender)
 
         if not has_signals:
-            result, created = await self._do_save(tx=tx)
+            result, _created = await do_op(tx=tx)
             return result
 
         await pre_save.send(sender, instance=self)
 
         if tx is not None:
-            # Buffered op: there is no actual write to wrap here, so around_save is
-            # skipped (the write happens at commit). post_save is deferred to post-commit
-            # so handlers only run when the write is durable.
-            result, created = await self._do_save(tx=tx)
+            result, created = await do_op(tx=tx)
             tx.enqueue_post_commit(lambda: post_save.send(sender, instance=self, created=created))
             return result
 
         async with around_save.wrap(sender, instance=self):
-            result, created = await self._do_save(tx=tx)
+            result, created = await do_op(tx=tx)
 
         await post_save.send(sender, instance=self, created=created)
-
         return result
 
+    async def _do_upsert(self, tx: Transaction | None = None) -> tuple[Self, bool]:
+        """Internal upsert logic. Returns (self, created).
+
+        Uses the SDK's native ``upsert()`` which runs ``UPSERT $record CONTENT $data`` —
+        a full REPLACE: the record is created if absent, or entirely replaced if present
+        (fields omitted from the model are dropped). An explicit id is required (there is
+        nothing to match without one). ``created`` cannot be told apart from the native
+        call, so it is reported best-effort as ``True``; use ``update_or_create`` when the
+        precise ``created`` flag matters.
+
+        When ``tx`` is provided the ``UPSERT`` statement is buffered (deferred to commit);
+        on an interactive transaction the returned row is applied to ``self``.
+        """
+        record_id = self._record_id()
+        if record_id is None:
+            raise SurrealDbError(
+                "upsert() requires an explicit id (there is nothing to match without one); "
+                "use save() to create a record with an auto-generated id."
+            )
+        data = self.model_dump(exclude={"id"})
+
+        if tx is not None:
+            rows = await tx.add(f"UPSERT {record_id} CONTENT $data;", {"data": data})
+            self._apply_record(rows)
+            return self, True
+
+        client = await SurrealDBConnectionManager.get_client()
+        record = await client.upsert(record_id, data)
+        self._apply_record(record)
+        return self, True
+
+    async def upsert(self, tx: Transaction | None = None) -> Self:
+        """
+        Insert the model instance, or fully replace it if a record with the same id exists.
+
+        Backed by the SDK's native ``upsert()`` (``UPSERT $record CONTENT $data``): this is
+        REPLACE semantics, so any field omitted from the model is removed from the stored
+        record. For a partial update use ``merge()`` instead. An explicit id is required.
+
+        When ``tx`` is provided, the ``UPSERT`` is buffered onto the transaction.
+
+        Emits the same signals as ``save()`` (``pre_save``/``around_save``/``post_save``);
+        in a transaction ``around_save`` is skipped and ``post_save`` is deferred to a
+        successful commit (consistent with ``save(tx=)``).
+        """
+        return await self._save_with_signals(self._do_upsert, tx)
+
     async def update(self, tx: Transaction | None = None) -> Any:
         """
         Update the model instance to the database.

{surreal_orm_lite-0.9.0 → surreal_orm_lite-0.10.0}/src/surreal_orm_lite/query_set.py

@@ -748,6 +748,116 @@ class QuerySet:
             return len(results)
         return 0
 
+    # ==================== Upsert / get_or_create ====================
+
+    @staticmethod
+    def _criteria_payload(criteria: dict[str, Any]) -> dict[str, Any]:
+        """Field=value pairs usable as a WRITE payload, taken from EQUALITY criteria only.
+
+        ``criteria`` keys are filter lookups (``field`` or ``field__lookup``). A literal raw
+        key like ``name__contains`` must never be written as a column, so only ``exact``
+        lookups contribute to the payload (their base field name → value). Non-``exact``
+        lookups (``gt``/``contains``/``in``/…) still drive the lookup but cannot be written,
+        so they are excluded here — mirroring Django, which only writes exact lookups on
+        create.
+        """
+        payload: dict[str, Any] = {}
+        for key, value in criteria.items():
+            field_name, lookup = parse_lookup(key)
+            if lookup == "exact":
+                payload[field_name] = value
+        return payload
+
+    async def _lookup_matches(self, criteria: dict[str, Any]) -> list[Any]:
+        """Return rows matching ``criteria``, routed through the transaction when attached.
+
+        Reuses the parameterized WHERE builder (anti-injection) via a throwaway QuerySet's
+        ``filter(**criteria)``, then runs through ``_execute_query`` so the read participates
+        in ``self._tx`` (``objects(tx=)``) — seeing the tx's uncommitted writes on an
+        interactive transaction, and raising on a buffered one (consistent with every other
+        read). ``LIMIT 2`` is enough to distinguish 0 / 1 / >1.
+        """
+        probe = QuerySet(self.model)
+        probe.filter(**criteria)
+        where_clause, where_vars = probe._build_where()
+        query = f"SELECT * FROM {self._model_table}{where_clause} LIMIT 2;"
+        rows = await self._execute_query(query, where_vars)
+        return rows if isinstance(rows, list) else []
+
+    async def update_or_create(
+        self,
+        defaults: dict[str, Any] | None = None,
+        **criteria: Any,
+    ) -> tuple[Any, bool]:
+        """Look up a record by ``criteria``; create it or update it; return ``(obj, created)``.
+
+        Django-style: ``criteria`` are filters used to find the record; ``defaults`` are extra
+        field values (they win on conflict). The write payload is built from the EQUALITY
+        criteria fields plus ``defaults`` (non-``exact`` lookups drive the lookup only).
+
+        - 0 matches → CREATE via ``save()`` → ``created=True``.
+        - 1 match → partial UPDATE via ``merge()`` (untouched fields preserved) → ``created=False``.
+        - >1 matches → ``SurrealDbError`` (the criteria are not unique).
+
+        Writes go through ``save()``/``merge()``, so lifecycle signals fire, SDK errors are
+        normalised to ``SurrealDbError``, the primary key anchors identity, and — under
+        ``objects(tx=)`` — the operation participates in the transaction. The lookup and the
+        write are two round-trips (no server-side locking on SurrealDB 2.6.x), so a small race
+        window exists, the same non-atomic fallback Django documents. ``criteria`` must be
+        non-empty.
+
+        Create builds ``self.model(**payload)``: keys not declared on the model are dropped by
+        Pydantic, and a missing required field raises ``ValidationError`` at construction.
+        """
+        if not criteria:
+            raise SurrealDbError("update_or_create() requires at least one lookup criteria.")
+        defaults = defaults or {}
+        matches = await self._lookup_matches(criteria)
+        if len(matches) > 1:
+            raise SurrealDbError("update_or_create() matched multiple records; the lookup criteria are not unique.")
+        payload = {**self._criteria_payload(criteria), **defaults}
+        if not matches:
+            obj: Any = self.model(**payload)
+            await obj.save(tx=self._tx)
+            return obj, True
+        obj = self.model.from_db(matches[0])
+        await obj.merge(tx=self._tx, **payload)
+        return obj, False
+
+    async def get_or_create(
+        self,
+        defaults: dict[str, Any] | None = None,
+        **criteria: Any,
+    ) -> tuple[Any, bool]:
+        """Look up a record by ``criteria``; return it, or create it; return ``(obj, created)``.
+
+        Django-style: ``criteria`` are filters. Unlike ``update_or_create``, ``defaults`` are
+        applied ONLY when creating; an existing match is returned untouched.
+
+        - 0 matches → CREATE (equality criteria + ``defaults``) via ``save()`` → ``created=True``.
+        - 1 match → returned as-is (no write) → ``created=False``.
+        - >1 matches → ``SurrealDbError`` (the criteria are not unique).
+
+        The create goes through ``save()`` (signals, error normalisation, PK identity, and
+        ``objects(tx=)`` participation); the lookup routes through the transaction too.
+        ``criteria`` must be non-empty.
+
+        Create builds ``self.model(**payload)``: keys not declared on the model are dropped by
+        Pydantic, and a missing required field raises ``ValidationError`` at construction.
+        """
+        if not criteria:
+            raise SurrealDbError("get_or_create() requires at least one lookup criteria.")
+        defaults = defaults or {}
+        matches = await self._lookup_matches(criteria)
+        if len(matches) > 1:
+            raise SurrealDbError("get_or_create() matched multiple records; the lookup criteria are not unique.")
+        if matches:
+            return self.model.from_db(matches[0]), False
+        payload = {**self._criteria_payload(criteria), **defaults}
+        obj = self.model(**payload)
+        await obj.save(tx=self._tx)
+        return obj, True
+
     # ==================== Custom Query ====================
 
     async def query(self, query: str, variables: dict[str, Any] | None = None) -> Any: