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

surreal_orm/__init__.py

@@ -78,4 +78,4 @@ __all__ = [
     "AuthenticatedUserMixin",
 ]
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"

surreal_orm/connection_manager.py

@@ -29,14 +29,31 @@ class SurrealDBConnectionManager:
         return await SurrealDBConnectionManager.get_client()
 
     @classmethod
-    def set_connection(cls, url: str, user: str, password: str, namespace: str, database: str) -> None:
+    def set_connection(
+        cls,
+        url: str,
+        user: str,
+        password: str,
+        namespace: str,
+        database: str,
+        *,
+        username: str | None = None,
+    ) -> None:
         """
         Set the connection kwargs for the SurrealDB instance.
 
-        :param kwargs: The connection kwargs for the SurrealDB instance.
+        :param url: The URL of the SurrealDB instance.
+        :param user: The username for authentication.
+        :param password: The password for authentication.
+        :param namespace: The namespace to use.
+        :param database: The database to use.
+        :param username: Keyword-only alias for 'user' (overrides 'user' if provided).
         """
+        # Allow 'username' keyword to override 'user' for API flexibility
+        actual_user = username if username is not None else user
+
         cls.__url = url
-        cls.__user = user
+        cls.__user = actual_user
         cls.__password = password
         cls.__namespace = namespace
         cls.__database = database

surreal_orm/migrations/operations.py

@@ -9,6 +9,53 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any, Callable, Coroutine
 
+from ..types import FieldType
+
+
+def _normalize_field_type(field_type: FieldType | str) -> str:
+    """
+    Normalize a field type to its string representation.
+
+    Accepts FieldType enum or string. For strings, validates that it's either
+    a known FieldType value or a valid generic type (e.g., "array<string>").
+
+    Args:
+        field_type: FieldType enum or string type specification
+
+    Returns:
+        String representation of the type for SurrealQL
+
+    Raises:
+        ValueError: If the string is not a valid SurrealDB type
+    """
+    if isinstance(field_type, FieldType):
+        return field_type.value
+
+    # Check if it's a known base type
+    try:
+        return FieldType(field_type).value
+    except ValueError:
+        pass
+
+    # Check if it's a generic type (e.g., "array<string>", "record<users>")
+    if "<" in field_type and field_type.endswith(">"):
+        base_type = field_type.split("<")[0]
+        try:
+            FieldType(base_type)
+            return field_type  # Valid generic type
+        except ValueError:
+            pass
+
+    # Check for union types (e.g., "int | null", "option<string>")
+    if "|" in field_type:
+        return field_type  # Allow union types
+
+    raise ValueError(
+        f"Invalid field type: '{field_type}'. "
+        f"Must be a FieldType enum value, a valid SurrealDB type string, "
+        f"or a generic type like 'array<string>' or 'record<users>'."
+    )
+
 
 @dataclass
 class Operation(ABC):
@@ -123,17 +170,24 @@ class AddField(Operation):
         AddField(
             table="users",
             name="email",
-            field_type="string",
+            field_type=FieldType.STRING,  # or "string"
             assertion="is::email($value)"
         )
 
+        # With generic types
+        AddField(
+            table="users",
+            name="tags",
+            field_type=FieldType.ARRAY.generic("string"),  # "array<string>"
+        )
+
     Generates:
         DEFINE FIELD email ON users TYPE string ASSERT is::email($value);
     """
 
     table: str
     name: str
-    field_type: str
+    field_type: FieldType | str
     default: Any = None
     assertion: str | None = None
     encrypted: bool = False
@@ -142,13 +196,19 @@ class AddField(Operation):
     value: str | None = None
     comment: str | None = None
 
+    def __post_init__(self) -> None:
+        """Validate field_type on initialization."""
+        # Validate the field type (raises ValueError if invalid)
+        _normalize_field_type(self.field_type)
+
     def forwards(self) -> str:
         parts = [f"DEFINE FIELD {self.name} ON {self.table}"]
 
         if self.flexible:
             parts.append("FLEXIBLE")
 
-        parts.append(f"TYPE {self.field_type}")
+        normalized_type = _normalize_field_type(self.field_type)
+        parts.append(f"TYPE {normalized_type}")
 
         # For encrypted fields, use VALUE clause with crypto function
         if self.encrypted:
@@ -224,7 +284,7 @@ class AlterField(Operation):
         AlterField(
             table="users",
             name="email",
-            field_type="string",
+            field_type=FieldType.STRING,  # or "string"
             assertion="is::email($value)"
         )
 
@@ -234,7 +294,7 @@ class AlterField(Operation):
 
     table: str
     name: str
-    field_type: str | None = None
+    field_type: FieldType | str | None = None
     default: Any = None
     assertion: str | None = None
     encrypted: bool = False
@@ -242,10 +302,19 @@ class AlterField(Operation):
     readonly: bool = False
     value: str | None = None
     # Store previous definition for rollback
-    previous_type: str | None = None
+    previous_type: FieldType | str | None = None
     previous_default: Any = None
     previous_assertion: str | None = None
 
+    def __post_init__(self) -> None:
+        """Validate field_type and set reversible based on previous state."""
+        # Validate field types if provided
+        if self.field_type is not None:
+            _normalize_field_type(self.field_type)
+        if self.previous_type is not None:
+            _normalize_field_type(self.previous_type)
+        object.__setattr__(self, "reversible", self.previous_type is not None)
+
     def forwards(self) -> str:
         # DEFINE FIELD is idempotent - it creates or updates
         parts = [f"DEFINE FIELD {self.name} ON {self.table}"]
@@ -254,7 +323,8 @@ class AlterField(Operation):
             parts.append("FLEXIBLE")
 
         if self.field_type:
-            parts.append(f"TYPE {self.field_type}")
+            normalized_type = _normalize_field_type(self.field_type)
+            parts.append(f"TYPE {normalized_type}")
 
         if self.encrypted:
             parts.append("VALUE crypto::argon2::generate($value)")
@@ -284,7 +354,8 @@ class AlterField(Operation):
         if not self.previous_type:
             return ""
 
-        parts = [f"DEFINE FIELD {self.name} ON {self.table} TYPE {self.previous_type}"]
+        normalized_prev_type = _normalize_field_type(self.previous_type)
+        parts = [f"DEFINE FIELD {self.name} ON {self.table} TYPE {normalized_prev_type}"]
 
         if self.previous_default is not None:
             if isinstance(self.previous_default, str):
@@ -297,10 +368,6 @@ class AlterField(Operation):
 
         return " ".join(parts) + ";"
 
-    def __post_init__(self) -> None:
-        """Set reversible based on whether previous state is stored."""
-        object.__setattr__(self, "reversible", self.previous_type is not None)
-
     def describe(self) -> str:
         return f"Alter field {self.name} on {self.table}"
 

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"})
+            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"})
+        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"})
+        # 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_orm/types.py

@@ -42,23 +42,114 @@ class FieldType(StrEnum):
     SurrealDB field types for schema definitions.
 
     Maps to SurrealDB's native type system.
+    See: https://surrealdb.com/docs/surrealql/datamodel
+
+    Numeric Types:
+        - INT: 64-bit signed integer (-9223372036854775808 to 9223372036854775807)
+        - FLOAT: 64-bit double-precision floating point
+        - DECIMAL: Arbitrary precision decimal (for financial calculations)
+        - NUMBER: Auto-detected numeric type (stores using minimal bytes)
+
+    Primitive Types:
+        - STRING: Text data
+        - BOOL: Boolean true/false
+        - DATETIME: RFC 3339 timestamp with timezone
+        - DURATION: Time length (e.g., "1h30m", "7d")
+        - BYTES: Binary data / byte array
+        - UUID: Universal unique identifier
+
+    Collection Types:
+        - ARRAY: Ordered collection (can be typed: array<string>)
+        - SET: Unique collection (auto-deduplicated)
+        - OBJECT: Flexible JSON-like container
+
+    Special Types:
+        - ANY: Accepts any value type
+        - OPTION: Optional value (can be typed: option<string>)
+        - RECORD: Reference to another record (can be typed: record<users>)
+        - GEOMETRY: GeoJSON spatial data (point, line, polygon, etc.)
+        - REGEX: Compiled regular expression
+
+    Generic Type Syntax:
+        For typed collections/references, use the generic() class method:
+        - FieldType.ARRAY.generic("string") -> "array<string>"
+        - FieldType.RECORD.generic("users") -> "record<users>"
+        - FieldType.OPTION.generic("int") -> "option<int>"
+        - FieldType.GEOMETRY.generic("point") -> "geometry<point>"
     """
 
-    STRING = "string"
+    # Numeric types
     INT = "int"
     FLOAT = "float"
+    DECIMAL = "decimal"
+    NUMBER = "number"
+
+    # Primitive types
+    STRING = "string"
     BOOL = "bool"
     DATETIME = "datetime"
     DURATION = "duration"
-    DECIMAL = "decimal"
+    BYTES = "bytes"
+    UUID = "uuid"
+
+    # Collection types
     ARRAY = "array"
+    SET = "set"
     OBJECT = "object"
-    RECORD = "record"
-    GEOMETRY = "geometry"
+
+    # Special types
     ANY = "any"
     OPTION = "option"
-    BYTES = "bytes"
-    UUID = "uuid"
+    RECORD = "record"
+    GEOMETRY = "geometry"
+    REGEX = "regex"
+
+    def generic(self, inner_type: str) -> str:
+        """
+        Create a generic type string for parameterized types.
+
+        Args:
+            inner_type: The inner type parameter (e.g., "string", "users", "point")
+
+        Returns:
+            Formatted type string (e.g., "array<string>", "record<users>")
+
+        Examples:
+            >>> FieldType.ARRAY.generic("string")
+            'array<string>'
+            >>> FieldType.RECORD.generic("users")
+            'record<users>'
+            >>> FieldType.GEOMETRY.generic("point|polygon")
+            'geometry<point|polygon>'
+        """
+        return f"{self.value}<{inner_type}>"
+
+    @classmethod
+    def from_python_type(cls, python_type: type) -> "FieldType":
+        """
+        Map a Python type to a SurrealDB FieldType.
+
+        Args:
+            python_type: A Python type (str, int, float, bool, list, dict, bytes)
+
+        Returns:
+            The corresponding FieldType
+
+        Raises:
+            ValueError: If the type cannot be mapped
+        """
+        mapping: dict[type, FieldType] = {
+            str: cls.STRING,
+            int: cls.INT,
+            float: cls.FLOAT,
+            bool: cls.BOOL,
+            list: cls.ARRAY,
+            dict: cls.OBJECT,
+            bytes: cls.BYTES,
+        }
+        if python_type in mapping:
+            return mapping[python_type]
+        raise ValueError(f"Cannot map Python type {python_type} to SurrealDB FieldType")
 
 
 class EncryptionAlgorithm(StrEnum):
@@ -75,6 +166,7 @@ class EncryptionAlgorithm(StrEnum):
 
 
 # Type mapping from Python types to SurrealDB types
+# Deprecated: Use FieldType.from_python_type() instead
 PYTHON_TO_SURREAL_TYPE: dict[type, FieldType] = {
     str: FieldType.STRING,
     int: FieldType.INT,

surreal_sdk/__init__.py

@@ -64,7 +64,7 @@ from .functions import (
     CryptoFunctions,
 )
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 __all__ = [
     # Connections
     "BaseSurrealConnection",

surreal_sdk/connection/base.py

@@ -71,8 +71,8 @@ class BaseSurrealConnection(ABC):
     # Abstract methods that must be implemented
 
     @abstractmethod
-    async def connect(self) -> None:
-        """Establish connection to SurrealDB."""
+    async def connect(self) -> Self:
+        """Establish connection to SurrealDB. Returns self for fluent API."""
         ...
 
     @abstractmethod
@@ -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/connection/http.py

@@ -4,7 +4,7 @@ HTTP Connection Implementation for SurrealDB SDK.
 Provides stateless HTTP-based connection, ideal for microservices and serverless.
 """
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Self
 
 import httpx
 
@@ -71,10 +71,10 @@ class HTTPConnection(BaseSurrealConnection):
         self._request_id += 1
         return self._request_id
 
-    async def connect(self) -> None:
-        """Establish HTTP client connection."""
+    async def connect(self) -> Self:
+        """Establish HTTP client connection. Returns self for fluent API."""
         if self._connected:
-            return
+            return self
 
         self._client = httpx.AsyncClient(
             base_url=self.url,
@@ -83,6 +83,7 @@ class HTTPConnection(BaseSurrealConnection):
             limits=httpx.Limits(max_keepalive_connections=0, max_connections=100),
         )
         self._connected = True
+        return self
 
     async def close(self) -> None:
         """Close HTTP client."""
@@ -112,10 +113,12 @@ class HTTPConnection(BaseSurrealConnection):
         request.id = self._next_request_id()
 
         try:
+            # Use pre-encoded JSON with custom encoder for datetime, UUID, etc.
+            headers = {**self.headers, "Content-Type": "application/json"}
             response = await self._client.post(
                 "/rpc",
-                json=request.to_dict(),
-                headers=self.headers,
+                content=request.to_json(),
+                headers=headers,
             )
             response.raise_for_status()
             return RPCResponse.from_dict(response.json())

surreal_sdk/connection/websocket.py

@@ -4,7 +4,7 @@ WebSocket Connection Implementation for SurrealDB SDK.
 Provides stateful WebSocket-based connection for real-time features.
 """
 
-from typing import TYPE_CHECKING, Any, Callable, Coroutine
+from typing import TYPE_CHECKING, Any, Callable, Coroutine, Self
 import asyncio
 import json
 
@@ -80,16 +80,17 @@ class WebSocketConnection(BaseSurrealConnection):
         self._reader_task: asyncio.Task[None] | None = None
         self._reconnect_task: asyncio.Task[None] | None = None
         self._closing = False
+        self._callback_tasks: set[asyncio.Task[Any]] = set()  # Track fire-and-forget callback tasks
 
     def _next_request_id(self) -> int:
         """Generate next request ID."""
         self._request_id += 1
         return self._request_id
 
-    async def connect(self) -> None:
-        """Establish WebSocket connection."""
+    async def connect(self) -> Self:
+        """Establish WebSocket connection. Returns self for fluent API."""
         if self._connected:
-            return
+            return self
 
         self._closing = False
         self._session = aiohttp.ClientSession()
@@ -113,6 +114,8 @@ class WebSocketConnection(BaseSurrealConnection):
             # Set namespace and database
             await self.use(self.namespace, self.database)
 
+            return self
+
         except aiohttp.ClientError as e:
             await self._cleanup()
             raise ConnectionError(f"WebSocket connection failed: {e}")
@@ -151,6 +154,11 @@ class WebSocketConnection(BaseSurrealConnection):
                 future.set_exception(ConnectionError("Connection closed"))
         self._pending.clear()
 
+        # Cancel all callback tasks
+        for task in self._callback_tasks:
+            task.cancel()
+        self._callback_tasks.clear()
+
         # Close WebSocket
         if self._ws:
             await self._ws.close()
@@ -217,7 +225,10 @@ class WebSocketConnection(BaseSurrealConnection):
             live_id = message.get("id")
             if live_id and live_id in self._live_callbacks:
                 callback = self._live_callbacks[live_id]
-                asyncio.create_task(callback(message))
+                # Track task for proper cleanup on connection close
+                task = asyncio.create_task(callback(message))
+                self._callback_tasks.add(task)
+                task.add_done_callback(self._callback_tasks.discard)
 
     async def _reconnect(self) -> None:
         """Attempt to reconnect after disconnection."""

surreal_sdk/protocol/rpc.py

@@ -5,10 +5,40 @@ Handles the JSON-RPC style messaging format used by SurrealDB.
 """
 
 from dataclasses import dataclass, field
+from datetime import date, datetime, time
+from decimal import Decimal
 from typing import Any
+from uuid import UUID
 import json
 
 
+class SurrealJSONEncoder(json.JSONEncoder):
+    """
+    Custom JSON encoder for SurrealDB types.
+
+    Handles serialization of Python types that are not natively JSON serializable:
+    - datetime → ISO 8601 string
+    - date → ISO 8601 string
+    - time → ISO 8601 string
+    - Decimal → float
+    - UUID → string
+    """
+
+    def default(self, obj: Any) -> Any:
+        """Encode non-standard types to JSON-serializable values."""
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        if isinstance(obj, date):
+            return obj.isoformat()
+        if isinstance(obj, time):
+            return obj.isoformat()
+        if isinstance(obj, Decimal):
+            return float(obj)
+        if isinstance(obj, UUID):
+            return str(obj)
+        return super().default(obj)
+
+
 @dataclass
 class RPCRequest:
     """
@@ -33,8 +63,8 @@ class RPCRequest:
         }
 
     def to_json(self) -> str:
-        """Serialize to JSON string."""
-        return json.dumps(self.to_dict())
+        """Serialize to JSON string with custom encoder for datetime, UUID, etc."""
+        return json.dumps(self.to_dict(), cls=SurrealJSONEncoder)
 
     @classmethod
     def query(cls, sql: str, vars: dict[str, Any] | None = None, request_id: int = 1) -> "RPCRequest":

surreal_sdk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-sdk"
-version = "0.5.1"
+version = "0.5.2"
 description = "Custom Python SDK for SurrealDB with HTTP and WebSocket support. No dependency on official surrealdb package."
 readme = "README.md"
 requires-python = ">=3.12"

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.1.dist-info → surrealdb_orm-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surrealdb-orm
-Version: 0.5.1
+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
@@ -66,7 +66,44 @@ Description-Content-Type: text/markdown
 
 ---
 
-## What's New in 0.4.0
+## 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
+- **datetime serialization** - Proper JSON encoding for datetime, date, time, Decimal, UUID
+- **Fluent API** - `connect()` now returns `self` for method chaining
+- **Session cleanup** - WebSocket callback tasks properly tracked and cancelled
+- **Optional fields** - `exclude_unset=True` prevents None from overriding DB defaults
+- **Parameter alias** - `username` parameter alias for `user` in ConnectionManager
+
+### v0.5.1 - Security Workflows
+
+- **Dependabot integration** - Automatic dependency security updates
+- **Auto-merge** - Dependabot PRs merged after CI passes
+- **SurrealDB monitoring** - Integration tests on new SurrealDB releases
+
+### v0.5.0 - Real-time SDK Enhancements
+
+- **Live Select Stream** - Async iterator pattern for real-time changes
+  - `async with db.live_select("table") as stream: async for change in stream:`
+  - `LiveChange` dataclass with `record_id`, `action`, `result`, `changed_fields`
+  - WHERE clause support with parameterized queries
+- **Auto-Resubscribe** - Automatic reconnection after WebSocket disconnect
+  - `auto_resubscribe=True` parameter for seamless K8s pod restart recovery
+  - `on_reconnect(old_id, new_id)` callback for tracking ID changes
+- **Typed Function Calls** - Pydantic/dataclass return type support
+  - `await db.call("fn::my_func", params={...}, return_type=MyModel)`
+
+### v0.4.0 - Relations & Graph
 
 - **Relations & Graph Traversal** - Django-style relation definitions with SurrealDB graph support
   - `ForeignKey`, `ManyToMany`, `Relation` field types
@@ -250,22 +287,54 @@ result = await db.fn.my_custom_function(arg1, arg2)
 Real-time updates via WebSocket:
 
 ```python
-from surreal_sdk import LiveQuery, LiveNotification, LiveAction
+from surreal_sdk import LiveAction
+
+# Async iterator pattern (recommended)
+async with db.live_select(
+    "orders",
+    where="status = $status",
+    params={"status": "pending"},
+    auto_resubscribe=True,  # Auto-reconnect on WebSocket drop
+) as stream:
+    async for change in stream:
+        match change.action:
+            case LiveAction.CREATE:
+                print(f"New order: {change.result}")
+            case LiveAction.UPDATE:
+                print(f"Updated: {change.record_id}")
+            case LiveAction.DELETE:
+                print(f"Deleted: {change.record_id}")
+
+# Callback-based pattern
+from surreal_sdk import LiveQuery, LiveNotification
 
 async def on_change(notification: LiveNotification):
-    if notification.action == LiveAction.CREATE:
-        print(f"New record: {notification.result}")
-    elif notification.action == LiveAction.UPDATE:
-        print(f"Updated: {notification.result}")
-    elif notification.action == LiveAction.DELETE:
-        print(f"Deleted: {notification.result}")
+    print(f"{notification.action}: {notification.result}")
 
 live = LiveQuery(ws_conn, "orders")
 await live.subscribe(on_change)
-# ... records changes trigger callbacks ...
+# ... record changes trigger callbacks ...
 await live.unsubscribe()
 ```
 
+**Typed Function Calls:**
+
+```python
+from pydantic import BaseModel
+
+class VoteResult(BaseModel):
+    success: bool
+    count: int
+
+# Call SurrealDB function with typed return
+result = await db.call(
+    "cast_vote",
+    params={"user": "alice", "vote": "yes"},
+    return_type=VoteResult
+)
+print(result.success, result.count)  # Typed access
+```
+
 ---
 
 ## ORM Features

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

@@ -1,15 +1,15 @@
-surreal_orm/__init__.py,sha256=CiOI5uxIRF0ul_PThqxXw47jui2oMuvXzbo_ZkzRAhA,1645
+surreal_orm/__init__.py,sha256=ucGuE53NINPmdGmEnoObF93n7iwyhORC-r0C-f_3n5Q,1645
 surreal_orm/aggregations.py,sha256=5ERMHMWQfaW76OrMNazMjyg7dbf9bJ3GX_8QWz6tfxY,3218
-surreal_orm/connection_manager.py,sha256=SA4W399idh8vVl5JI0LX_l-YE1C9KTfv51CaFNtQyGc,9971
+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=STFrLauWm3r1GOm4bX6hTdSwupcfjAZGIk6hsDnYO0M,22953
+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
 surreal_orm/surreal_function.py,sha256=zsiJHPa4Z-RfqJpekXupJI79SKxUGtsnptwFpq1KFEM,2627
 surreal_orm/surreal_ql.py,sha256=k3XHIdesu5Yb6RVU62ESizLLrJ8NtYYDQ8pI-WSqdRI,3436
-surreal_orm/types.py,sha256=bEbEXXVSRdjOFjt6IRZIXUjAjDvIymWdrxUGGa5imQY,2022
+surreal_orm/types.py,sha256=0mb3FLd9qYlDN2d_qv7ZXwhiqHpW9ytFrDIWSZIj2QE,5167
 surreal_orm/utils.py,sha256=mni_dTtb4VGTdge8eWSZpBw5xoWci2m-XThKFHYPKTo,171
 surreal_orm/auth/__init__.py,sha256=wydszeh5ee4OpQu_OSX7CpCNKNIXPGFTlAoTmapxho4,340
 surreal_orm/auth/access.py,sha256=FUuBAgnyq_j4a6RfLJ96TsgSHpaNXFpwLvrpCVrUbVA,5584
@@ -24,29 +24,29 @@ surreal_orm/migrations/executor.py,sha256=6QNhsJAt0EL1QmBXmXBrG5LyVhKyJa0xxqd-9C
 surreal_orm/migrations/generator.py,sha256=PutA0OjXZ8YgBXKTAJrMymo-E0h1zyaVpqh7qCzQ5LM,7994
 surreal_orm/migrations/introspector.py,sha256=49AWhOAZRhWdv2jSaW3n6uuoInNh_U8AzUCo6toYgPo,9673
 surreal_orm/migrations/migration.py,sha256=6z7rJC-oWBDzAj_tqIpOCDSjRK6kJoHdKdkI6blb718,5663
-surreal_orm/migrations/operations.py,sha256=8WVn0vo51blD8KpzuDFUAvR211vSkZZKyBFtcoa0Qmc,14207
+surreal_orm/migrations/operations.py,sha256=KHxxPIv-etJpMDrB9yqINhX1vnSisjX8hHviiuHSJCo,16555
 surreal_orm/migrations/state.py,sha256=cWLLOuvojeoafBTYBfgKHlWJ0n31mnBcbeBVTtRvn8Q,15848
 surreal_sdk/README.md,sha256=SCHz5yMMvgHE70V7JGupvg3VZTllVsu60D_DtOngJjk,1957
-surreal_sdk/__init__.py,sha256=TPcaNxDzPIm3DC67NKNqtgtHj1l4ICUkeCLSlBHmXkk,4055
+surreal_sdk/__init__.py,sha256=h7Bwv9N7FxrIM_YSi_Yy-bZYaMAw4o8kCeKH7UMtxvA,4055
 surreal_sdk/exceptions.py,sha256=qiDA3xJ2VkY8HUhvmDmW8kkNxhZ9NJu-FCUKUzfBrbU,1489
 surreal_sdk/functions.py,sha256=eTJA6zWlivTEnKJgtR53MAygElhMB1o9p6_FPt8_ErI,20537
 surreal_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-surreal_sdk/pyproject.toml,sha256=GYx99zPXSPu8mmrY0gKpnl-HUR9_aU9gOS85UyQdrQs,1421
-surreal_sdk/transaction.py,sha256=FkRcMO3qIb0CmjYnPRseDcZ1GIe-v1KRJeuATBuT_HU,13396
+surreal_sdk/pyproject.toml,sha256=pbcDsXdadtxF2d4aQKlinbEYEIftYfGy-T_lZX_8sRw,1421
+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=8InOGVHgcUiGLQcReNAK_D1yLH6gVP_jKXWgCVEzbBk,15165
-surreal_sdk/connection/http.py,sha256=0fef-CGJVUVQPXu_RGyR2bUQiebXk7l0pqXUHvc5m9M,12435
+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=veqDVLu3fpWMIZEi3QrKSBFyGlHLiQfMichgH8u-LiU,17739
+surreal_sdk/connection/websocket.py,sha256=sTbYSAi9-C8W3T2gR1bm-XO3vtCirtdO95MYJoxH3z8,18238
 surreal_sdk/protocol/__init__.py,sha256=ibLAVvwGfLChUHu3TStO7-bM1dkXggEE8x0BU7YNLTM,217
-surreal_sdk/protocol/rpc.py,sha256=_P-Am0T6OpXxO_9Un7RZnNe90ebeX0EJFHnBu7_k8TE,5945
+surreal_sdk/protocol/rpc.py,sha256=602CvidbgawtmzW6d80WRl-V6D7hRLSQkTld7ZR2nUg,6925
 surreal_sdk/streaming/__init__.py,sha256=TljF9HFN-XOshK_1smmTanF68hcdNsTgdlHtfFoAmtQ,714
 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.1.dist-info/METADATA,sha256=OkllmtEb8svEoNBcub_RKvmZcfytmlPo5qMK3y7Dx78,14375
-surrealdb_orm-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-surrealdb_orm-0.5.1.dist-info/entry_points.txt,sha256=3zbp1VzVPSxFrxNuvKZAyt9U432QITdBNjp5QnMZ2o8,62
-surrealdb_orm-0.5.1.dist-info/licenses/LICENSE,sha256=OYVJQ7TKsjHAgVndePmKcMWOZkxwJxOHiXOG1TAnCk4,1079
-surrealdb_orm-0.5.1.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,,