surrealdb-orm 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

surreal_orm/model_base.py

@@ -1,4 +1,4 @@
-from typing import Any, Literal, Self, cast, TYPE_CHECKING
+from typing import Any, Literal, Self, TYPE_CHECKING
 
 from pydantic import BaseModel, ConfigDict, model_validator
 
@@ -71,6 +71,10 @@ class SurrealConfigDict(ConfigDict):
         password_field: Field containing password (USER type, default: "password")
         token_duration: JWT token duration (USER type, default: "15m")
         session_duration: Session duration (USER type, default: "12h")
+        server_fields: List of field names that are server-generated and should
+            be excluded from save/update operations (e.g., ["created_at", "updated_at"]).
+            These fields are populated by SurrealDB's VALUE clause and should not be
+            sent back during updates.
     """
 
     primary_key: str | None
@@ -83,6 +87,7 @@ class SurrealConfigDict(ConfigDict):
     password_field: str | None
     token_duration: str | None
     session_duration: str | None
+    server_fields: list[str] | None
 
 
 class BaseSurrealModel(BaseModel):
@@ -236,6 +241,23 @@ class BaseSurrealModel(BaseModel):
 
         return None
 
+    @classmethod
+    def get_server_fields(cls) -> set[str]:
+        """
+        Get the list of server-generated field names.
+
+        Server fields are populated by SurrealDB (e.g., via VALUE time::now())
+        and should be excluded from save/update operations.
+
+        Returns:
+            Set of field names to exclude from save/update operations.
+        """
+        if hasattr(cls, "model_config"):
+            server_fields = cls.model_config.get("server_fields", None)
+            if isinstance(server_fields, list):
+                return set(server_fields)
+        return set()
+
     def get_id(self) -> str | None:
         """
         Get the ID of the model instance.
@@ -276,6 +298,29 @@ class BaseSurrealModel(BaseModel):
                 data["id"] = _parse_record_id(data["id"])
             return data
 
+    def _update_from_db(self, record: dict[str, Any]) -> None:
+        """
+        Update instance fields from a database record without marking them as user-set.
+
+        This preserves the original __pydantic_fields_set__ so that exclude_unset=True
+        continues to work correctly on subsequent saves.
+
+        Args:
+            record: Dictionary of field values from the database.
+        """
+        # Store original fields_set to preserve user-set tracking
+        original_fields_set = self.__pydantic_fields_set__.copy()
+
+        for key, value in record.items():
+            if key == "id":
+                value = _parse_record_id(value)
+            if hasattr(self, key):
+                setattr(self, key, value)
+
+        # Restore original fields_set - only user-set fields should be marked
+        # DB-loaded fields should not be considered as "set" for exclude_unset
+        object.__setattr__(self, "__pydantic_fields_set__", original_fields_set)
+
     async def refresh(self) -> None:
         """
         Refresh the model instance from the database.
@@ -294,12 +339,8 @@ class BaseSurrealModel(BaseModel):
         if record is None:
             raise SurrealDbError("Can't refresh data, no record found.")  # pragma: no cover
 
-        # Update instance fields from the record
-        for key, value in record.items():
-            if key == "id":
-                value = _parse_record_id(value)
-            if hasattr(self, key):
-                setattr(self, key, value)
+        # Update instance fields without marking them as user-set
+        self._update_from_db(record)
         return None
 
     async def save(self, tx: "BaseTransaction | None" = None) -> Self:
@@ -318,15 +359,19 @@ class BaseSurrealModel(BaseModel):
             async with SurrealDBConnectionManager.transaction() as tx:
                 await user.save(tx=tx)
         """
+        # Build exclude set: always exclude 'id' and any server-generated fields
+        exclude_fields = {"id"} | self.get_server_fields()
+
         if tx is not None:
             # Use transaction
-            data = self.model_dump(exclude={"id"}, exclude_unset=True)
+            data = self.model_dump(exclude=exclude_fields, exclude_unset=True)
             id = self.get_id()
             table = self.get_table_name()
 
             if id is not None:
+                # Use upsert for idempotent save (create or update)
                 thing = f"{table}:{id}"
-                await tx.create(thing, data)
+                await tx.upsert(thing, data)
                 return self
 
             # Auto-generate ID - create without specific ID
@@ -335,13 +380,14 @@ class BaseSurrealModel(BaseModel):
 
         # Original behavior without transaction
         client = await SurrealDBConnectionManager.get_client()
-        data = self.model_dump(exclude={"id"}, exclude_unset=True)
+        data = self.model_dump(exclude=exclude_fields, exclude_unset=True)
         id = self.get_id()
         table = self.get_table_name()
 
         if id is not None:
+            # Use upsert for idempotent save (create or update)
             thing = f"{table}:{id}"
-            await client.create(thing, data)
+            await client.upsert(thing, data)
             return self
 
         # Auto-generate the ID
@@ -351,9 +397,12 @@ class BaseSurrealModel(BaseModel):
         if not result.exists:
             raise SurrealDbError("Can't save data, no record returned.")  # pragma: no cover
 
-        obj = self.from_db(cast(dict | list | None, result.record))
-        if isinstance(obj, type(self)):
-            self = obj
+        # Update self's attributes from the database response
+        # This includes the auto-generated ID and any server-side fields
+        # Use _update_from_db to avoid marking DB fields as user-set
+        record = result.record
+        if isinstance(record, dict):
+            self._update_from_db(record)
             return self
 
         raise SurrealDbError("Can't save data, no record returned.")  # pragma: no cover
@@ -365,7 +414,9 @@ class BaseSurrealModel(BaseModel):
         Args:
             tx: Optional transaction to use for this operation.
         """
-        data = self.model_dump(exclude={"id"}, exclude_unset=True)
+        # Build exclude set: always exclude 'id' and any server-generated fields
+        exclude_fields = {"id"} | self.get_server_fields()
+        data = self.model_dump(exclude=exclude_fields, exclude_unset=True)
         id = self.get_id()
 
         if id is None:
@@ -388,13 +439,16 @@ class BaseSurrealModel(BaseModel):
         """
         return f"{cls.__name__}:{item}"
 
-    async def merge(self, tx: "BaseTransaction | None" = None, **data: Any) -> Any:
+    async def merge(self, tx: "BaseTransaction | None" = None, **data: Any) -> Self:
         """
         Merge (partial update) the model instance in the database.
 
         Args:
             tx: Optional transaction to use for this operation.
             **data: Fields to update.
+
+        Returns:
+            Self: The updated model instance.
         """
         data_set = {key: value for key, value in data.items()}
 
@@ -406,11 +460,16 @@ class BaseSurrealModel(BaseModel):
 
         if tx is not None:
             await tx.merge(thing, data_set)
-            return
+            # Update local instance with merged data
+            for key, value in data_set.items():
+                if hasattr(self, key):
+                    setattr(self, key, value)
+            return self
 
         client = await SurrealDBConnectionManager.get_client()
         await client.merge(thing, data_set)
         await self.refresh()
+        return self
 
     async def delete(self, tx: "BaseTransaction | None" = None) -> None:
         """

surreal_sdk/connection/base.py

@@ -315,6 +315,23 @@ class BaseSurrealConnection(ABC):
         result = await self.rpc("update", [thing, data])
         return RecordsResponse.from_rpc_result(result)
 
+    async def upsert(self, thing: str, data: dict[str, Any]) -> RecordsResponse:
+        """
+        Upsert record(s) - create if not exists, update if exists.
+
+        This is the recommended method for save operations when you have
+        a specific ID and want idempotent behavior.
+
+        Args:
+            thing: Table name or record ID
+            data: Record data
+
+        Returns:
+            RecordsResponse containing upserted record(s)
+        """
+        result = await self.rpc("upsert", [thing, data])
+        return RecordsResponse.from_rpc_result(result)
+
     async def merge(self, thing: str, data: dict[str, Any]) -> RecordsResponse:
         """
         Merge data into record(s), updating only specified fields.

surreal_sdk/transaction.py

@@ -119,6 +119,11 @@ class BaseTransaction(ABC):
         """Update records within the transaction."""
         ...
 
+    @abstractmethod
+    async def upsert(self, thing: str, data: dict[str, Any]) -> "RecordsResponse":
+        """Upsert records within the transaction (create or update)."""
+        ...
+
     @abstractmethod
     async def merge(self, thing: str, data: dict[str, Any]) -> "RecordsResponse":
         """Merge data into records within the transaction."""
@@ -256,6 +261,15 @@ class HTTPTransaction(BaseTransaction):
         self._queue_statement(sql, data)
         return RecordsResponse(records=[], raw=[])
 
+    async def upsert(self, thing: str, data: dict[str, Any]) -> "RecordsResponse":
+        """Queue an upsert operation (create or update)."""
+        from .types import RecordsResponse
+
+        fields = ", ".join(f"{k} = ${k}" for k in data.keys())
+        sql = f"UPSERT {thing} SET {fields};"
+        self._queue_statement(sql, data)
+        return RecordsResponse(records=[], raw=[])
+
     async def merge(self, thing: str, data: dict[str, Any]) -> "RecordsResponse":
         """Queue a merge operation."""
         from .types import RecordsResponse
@@ -361,6 +375,12 @@ class WebSocketTransaction(BaseTransaction):
             raise TransactionError("Transaction not active")
         return await self._connection.update(thing, data)
 
+    async def upsert(self, thing: str, data: dict[str, Any]) -> "RecordsResponse":
+        """Execute upsert immediately within transaction (create or update)."""
+        if not self.is_active:
+            raise TransactionError("Transaction not active")
+        return await self._connection.upsert(thing, data)
+
     async def merge(self, thing: str, data: dict[str, Any]) -> "RecordsResponse":
         """Execute merge immediately within transaction."""
         if not self.is_active:

{surrealdb_orm-0.5.2.dist-info → surrealdb_orm-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surrealdb-orm
-Version: 0.5.2
+Version: 0.5.3
 Summary: SurrealDB ORM as 'DJango style' for Python with async support. Works with pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM
@@ -68,6 +68,14 @@ Description-Content-Type: text/markdown
 
 ## What's New in 0.5.x
 
+### v0.5.3 - ORM Improvements
+
+- **Upsert save behavior** - `save()` now uses `upsert` for existing records (idempotent, Django-like)
+- **`server_fields` config** - Exclude server-generated fields (created_at, updated_at) from saves
+- **`merge()` returns self** - Now returns the updated model instance instead of None
+- **`save()` updates self** - Updates original instance attributes instead of returning new object
+- **NULL values fix** - `exclude_unset=True` now works correctly after loading from DB
+
 ### v0.5.2 - Bug Fixes & FieldType Improvements
 
 - **FieldType enum** - Enhanced migration type system with `generic()` and `from_python_type()` methods

{surrealdb_orm-0.5.2.dist-info → surrealdb_orm-0.5.3.dist-info}/RECORD

@@ -3,7 +3,7 @@ surreal_orm/aggregations.py,sha256=5ERMHMWQfaW76OrMNazMjyg7dbf9bJ3GX_8QWz6tfxY,3
 surreal_orm/connection_manager.py,sha256=VJVfsuUXK5OEG0rtuiu3DKbyWxkkeFrCEtzjXFd6lAw,10496
 surreal_orm/constants.py,sha256=CLavEca1M6cLJLqVl4l4KoE-cBrgVQNsuGxW9zGJBmg,429
 surreal_orm/enum.py,sha256=kR-vzkHqnqy9YaYOvWTwAHdl2-WCzPcSEch-YTyJv1Y,158
-surreal_orm/model_base.py,sha256=8UjJGAHhNyltaSKp5yriXJHrxw_g05Z3nQvJ99Bb5QE,23013
+surreal_orm/model_base.py,sha256=yXFsCskiCkmqpWtpNpYWy-MIYsrQvovd71jHMgzUNG4,25652
 surreal_orm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 surreal_orm/query_set.py,sha256=3nmQ9A13g-1EJlRZsJQX8z7yFO3pjI_6MscFT3W4Lm0,38890
 surreal_orm/relations.py,sha256=pbsbKz2jw1h9FdFQowidUkx8krYv-l3OreQEViasN5w,21137
@@ -32,10 +32,10 @@ surreal_sdk/exceptions.py,sha256=qiDA3xJ2VkY8HUhvmDmW8kkNxhZ9NJu-FCUKUzfBrbU,148
 surreal_sdk/functions.py,sha256=eTJA6zWlivTEnKJgtR53MAygElhMB1o9p6_FPt8_ErI,20537
 surreal_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 surreal_sdk/pyproject.toml,sha256=pbcDsXdadtxF2d4aQKlinbEYEIftYfGy-T_lZX_8sRw,1421
-surreal_sdk/transaction.py,sha256=FkRcMO3qIb0CmjYnPRseDcZ1GIe-v1KRJeuATBuT_HU,13396
+surreal_sdk/transaction.py,sha256=AIvEJhGcqmaQ4WiyTCD_knhpGW7zffyd7eSYT32V3Vc,14287
 surreal_sdk/types.py,sha256=y08l9x-ZYgPSAIFztzly474HiZ9slxYqZ0oAA7jJpOI,9841
 surreal_sdk/connection/__init__.py,sha256=zTe2qPLHsl9Upy6NYUr04rr4aWP-D2vCMA2iM5eUcU0,363
-surreal_sdk/connection/base.py,sha256=Z8I3thpIHaKxI6CTv-sErdDzopaOZJHQLas3BX6tXXY,15194
+surreal_sdk/connection/base.py,sha256=AN-Ab84Vr5TcI4Wpxm_Px63yDBvBo2vLFUdffgBMtLw,15769
 surreal_sdk/connection/http.py,sha256=bUJ7bwEGKbufFo6NNggOBSimvJZZGmhoY9IR0Jd4YPw,12648
 surreal_sdk/connection/pool.py,sha256=v9FZmpfwWn674iY--xdDtaiYimBgpv3UtGT4k6q0DHE,7849
 surreal_sdk/connection/websocket.py,sha256=sTbYSAi9-C8W3T2gR1bm-XO3vtCirtdO95MYJoxH3z8,18238
@@ -45,8 +45,8 @@ surreal_sdk/streaming/__init__.py,sha256=TljF9HFN-XOshK_1smmTanF68hcdNsTgdlHtfFo
 surreal_sdk/streaming/change_feed.py,sha256=lS6CGNinsMkzslf1y0aV0VgZ2gq01EDIEZrnvvYhv-E,8540
 surreal_sdk/streaming/live_query.py,sha256=QwPXmRIsH0j3jgGQY9ULJU7MB0eTk8dnOVbPzy4SeSo,7561
 surreal_sdk/streaming/live_select.py,sha256=mYg6NKMx3GPShg_hYz4SjjDwhG7baI3t_Gynv8YCBNE,12035
-surrealdb_orm-0.5.2.dist-info/METADATA,sha256=K8-wXndSr-_25BO46XjHatDzUJikSChhSqDm9paEMqc,16596
-surrealdb_orm-0.5.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-surrealdb_orm-0.5.2.dist-info/entry_points.txt,sha256=3zbp1VzVPSxFrxNuvKZAyt9U432QITdBNjp5QnMZ2o8,62
-surrealdb_orm-0.5.2.dist-info/licenses/LICENSE,sha256=OYVJQ7TKsjHAgVndePmKcMWOZkxwJxOHiXOG1TAnCk4,1079
-surrealdb_orm-0.5.2.dist-info/RECORD,,
+surrealdb_orm-0.5.3.dist-info/METADATA,sha256=qCZAOpLAFD3y7PY_o8HJ2fgLldLm4wxE8E_G2nANl6k,17102
+surrealdb_orm-0.5.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+surrealdb_orm-0.5.3.dist-info/entry_points.txt,sha256=3zbp1VzVPSxFrxNuvKZAyt9U432QITdBNjp5QnMZ2o8,62
+surrealdb_orm-0.5.3.dist-info/licenses/LICENSE,sha256=OYVJQ7TKsjHAgVndePmKcMWOZkxwJxOHiXOG1TAnCk4,1079
+surrealdb_orm-0.5.3.dist-info/RECORD,,