surrealdb-orm 0.5.2__tar.gz → 0.5.3.1__tar.gz

{surrealdb_orm-0.5.2 → surrealdb_orm-0.5.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surrealdb-orm
-Version: 0.5.2
+Version: 0.5.3.1
 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,20 @@ Description-Content-Type: text/markdown
 
 ## What's New in 0.5.x
 
+### v0.5.3.1 - Bug Fixes
+
+- **Partial updates for persisted records** - `save()` now uses `merge()` for already-persisted records, only sending modified fields
+- **datetime parsing** - `_update_from_db()` now parses ISO 8601 strings to `datetime` objects automatically
+- **`_db_persisted` flag** - Internal tracking to distinguish new vs persisted records
+
+### v0.5.3 - ORM Improvements
+
+- **Upsert save behavior** - `save()` now uses `upsert` for new records with ID (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 → surrealdb_orm-0.5.3.1}/README.md

@@ -15,6 +15,20 @@
 
 ## What's New in 0.5.x
 
+### v0.5.3.1 - Bug Fixes
+
+- **Partial updates for persisted records** - `save()` now uses `merge()` for already-persisted records, only sending modified fields
+- **datetime parsing** - `_update_from_db()` now parses ISO 8601 strings to `datetime` objects automatically
+- **`_db_persisted` flag** - Internal tracking to distinguish new vs persisted records
+
+### v0.5.3 - ORM Improvements
+
+- **Upsert save behavior** - `save()` now uses `upsert` for new records with ID (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 → surrealdb_orm-0.5.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surrealdb-orm"
-version = "0.5.2"
+version = "0.5.3.1"
 description = "SurrealDB ORM as 'DJango style' for Python with async support. Works with pydantic validation."
 readme = "README.md"
 requires-python = ">=3.12"

{surrealdb_orm-0.5.2 → surrealdb_orm-0.5.3.1}/src/surreal_orm/model_base.py

@@ -1,6 +1,7 @@
-from typing import Any, Literal, Self, cast, TYPE_CHECKING
+from datetime import datetime
+from typing import Any, Literal, Self, TYPE_CHECKING, get_args, get_origin
 
-from pydantic import BaseModel, ConfigDict, model_validator
+from pydantic import BaseModel, ConfigDict, PrivateAttr, model_validator
 
 from .connection_manager import SurrealDBConnectionManager
 from .types import SchemaMode, TableType
@@ -53,6 +54,36 @@ def _parse_record_id(record_id: Any) -> str | None:
     return record_str
 
 
+def _parse_datetime(value: Any) -> Any:
+    """
+    Parse a datetime value from SurrealDB.
+
+    SurrealDB returns datetime as ISO 8601 strings.
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        try:
+            # Try parsing ISO format (with or without timezone)
+            # SurrealDB returns format like "2026-02-02T13:21:23.641315924Z"
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return value  # Return as-is if we can't parse
+
+
+def _is_datetime_field(field_type: Any) -> bool:
+    """Check if a field type is datetime or Optional[datetime]."""
+    # Handle Optional[datetime] which is Union[datetime, None]
+    origin = get_origin(field_type)
+    if origin is not None:
+        args = get_args(field_type)
+        return datetime in args
+    return field_type is datetime
+
+
 class SurrealConfigDict(ConfigDict):
     """
     SurrealConfigDict is a configuration dictionary for SurrealDB models.
@@ -71,6 +102,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 +118,7 @@ class SurrealConfigDict(ConfigDict):
     password_field: str | None
     token_duration: str | None
     session_duration: str | None
+    server_fields: list[str] | None
 
 
 class BaseSurrealModel(BaseModel):
@@ -104,6 +140,10 @@ class BaseSurrealModel(BaseModel):
             password: Encrypted
     """
 
+    # Private attribute to track if this instance has been persisted to the database.
+    # This helps distinguish between create (first save) and update (subsequent saves).
+    _db_persisted: bool = PrivateAttr(default=False)
+
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """Register subclasses in the model registry for migration introspection."""
         super().__init_subclass__(**kwargs)
@@ -236,6 +276,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.
@@ -263,7 +320,9 @@ class BaseSurrealModel(BaseModel):
         if isinstance(record, list):
             return [cls.from_db(rs) for rs in record]  # type: ignore
 
-        return cls(**record)
+        instance = cls(**record)
+        instance._db_persisted = True
+        return instance
 
     @model_validator(mode="before")
     @classmethod
@@ -276,6 +335,43 @@ 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.
+
+        Also handles type coercion for datetime fields (SurrealDB returns ISO strings).
+
+        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()
+
+        # Get field type annotations for datetime parsing
+        field_types = self.__class__.model_fields
+
+        for key, value in record.items():
+            if key == "id":
+                value = _parse_record_id(value)
+            elif key in field_types:
+                # Check if this field is a datetime type and parse if needed
+                field_info = field_types[key]
+                if _is_datetime_field(field_info.annotation):
+                    value = _parse_datetime(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)
+
+        # Mark as persisted since we just loaded data from DB
+        self._db_persisted = True
+
     async def refresh(self) -> None:
         """
         Refresh the model instance from the database.
@@ -294,18 +390,19 @@ 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:
         """
         Save the model instance to the database.
 
+        For persisted records: uses merge() for partial update, only sending
+        explicitly set fields (preserving server-side values like timestamps).
+        For new records with ID: uses upsert() to create or fully replace.
+        For new records without ID: uses create() to auto-generate an ID.
+
         Args:
             tx: Optional transaction to use for this operation.
                 If provided, the operation will be part of the transaction.
@@ -318,42 +415,64 @@ 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()
+        id = self.get_id()
+        table = self.get_table_name()
+
         if tx is not None:
             # Use transaction
-            data = self.model_dump(exclude={"id"}, exclude_unset=True)
-            id = self.get_id()
-            table = self.get_table_name()
+            data = self.model_dump(exclude=exclude_fields, exclude_unset=True)
 
-            if id is not None:
+            if self._db_persisted and id is not None:
+                # Already persisted: use merge for partial update
+                # Only sends explicitly set fields, preserving server-side values
                 thing = f"{table}:{id}"
-                await tx.create(thing, data)
+                await tx.merge(thing, data)
                 return self
 
-            # Auto-generate ID - create without specific ID
-            await tx.create(table, data)
+            if id is not None:
+                # New record with user-provided ID: use upsert
+                thing = f"{table}:{id}"
+                await tx.upsert(thing, data)
+            else:
+                # Auto-generate ID
+                await tx.create(table, data)
+
+            self._db_persisted = True
             return self
 
         # Original behavior without transaction
         client = await SurrealDBConnectionManager.get_client()
-        data = self.model_dump(exclude={"id"}, exclude_unset=True)
-        id = self.get_id()
-        table = self.get_table_name()
+        data = self.model_dump(exclude=exclude_fields, exclude_unset=True)
+
+        if self._db_persisted and id is not None:
+            # Already persisted: use merge for partial update
+            # Only sends explicitly set fields, preserving server-side values
+            thing = f"{table}:{id}"
+            await client.merge(thing, data)
+            return self
 
         if id is not None:
+            # New record with user-provided ID: use upsert
             thing = f"{table}:{id}"
-            await client.create(thing, data)
+            await client.upsert(thing, data)
+            self._db_persisted = True
             return self
 
         # Auto-generate the ID
-        result = await client.create(table, data)  # pragma: no cover
+        result = await client.create(table, data)
 
         # SDK returns RecordResponse
         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
@@ -362,10 +481,15 @@ class BaseSurrealModel(BaseModel):
         """
         Update the model instance to the database.
 
+        Uses merge() to only update the specified fields, preserving
+        any fields that weren't explicitly set.
+
         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:
@@ -374,11 +498,13 @@ class BaseSurrealModel(BaseModel):
         thing = f"{self.__class__.__name__}:{id}"
 
         if tx is not None:
-            await tx.update(thing, data)
+            # Use merge for partial update - preserves unspecified fields
+            await tx.merge(thing, data)
             return None
 
         client = await SurrealDBConnectionManager.get_client()
-        result = await client.update(thing, data)
+        # Use merge for partial update - preserves unspecified fields
+        result = await client.merge(thing, data)
         return result.records
 
     @classmethod
@@ -388,13 +514,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 +535,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:
         """

{surrealdb_orm-0.5.2 → surrealdb_orm-0.5.3.1}/src/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.

{surrealdb_orm-0.5.2 → surrealdb_orm-0.5.3.1}/src/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: