sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/adapters/duckdb/litestar/store.py

@@ -0,0 +1,332 @@
+"""DuckDB sync session store for Litestar integration."""
+
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
+
+from sqlspec.extensions.litestar.store import BaseSQLSpecStore
+from sqlspec.utils.logging import get_logger
+from sqlspec.utils.sync_tools import async_
+
+if TYPE_CHECKING:
+    from sqlspec.adapters.duckdb.config import DuckDBConfig
+
+logger = get_logger("adapters.duckdb.litestar.store")
+
+__all__ = ("DuckdbStore",)
+
+
+class DuckdbStore(BaseSQLSpecStore["DuckDBConfig"]):
+    """DuckDB session store using synchronous DuckDB driver.
+
+    Implements server-side session storage for Litestar using DuckDB
+    via the synchronous duckdb driver. Uses Litestar's sync_to_thread
+    utility to provide an async interface compatible with the Store protocol.
+
+    Provides efficient session management with:
+    - Sync operations wrapped for async compatibility
+    - INSERT OR REPLACE for UPSERT functionality
+    - Native TIMESTAMP type support
+    - Automatic expiration handling
+    - Efficient cleanup of expired sessions
+    - Columnar storage optimized for analytical queries
+
+    Note:
+        DuckDB is primarily designed for analytical (OLAP) workloads.
+        For high-concurrency OLTP session stores, consider PostgreSQL adapters.
+
+    Args:
+        config: DuckDBConfig instance.
+
+    Example:
+        from sqlspec.adapters.duckdb import DuckDBConfig
+        from sqlspec.adapters.duckdb.litestar.store import DuckdbStore
+
+        config = DuckDBConfig()
+        store = DuckdbStore(config)
+        await store.create_table()
+    """
+
+    __slots__ = ()
+
+    def __init__(self, config: "DuckDBConfig") -> None:
+        """Initialize DuckDB session store.
+
+        Args:
+            config: DuckDBConfig instance.
+
+        Notes:
+            Table name is read from config.extension_config["litestar"]["session_table"].
+        """
+        super().__init__(config)
+
+    def _get_create_table_sql(self) -> str:
+        """Get DuckDB CREATE TABLE SQL.
+
+        Returns:
+            SQL statement to create the sessions table with proper indexes.
+
+        Notes:
+            - Uses TIMESTAMP type for expires_at (DuckDB native datetime type)
+            - TIMESTAMP supports ISO 8601 format and direct comparisons
+            - Columnar storage makes this efficient for analytical queries
+            - DuckDB does not support partial indexes, so full index is created
+        """
+        return f"""
+        CREATE TABLE IF NOT EXISTS {self._table_name} (
+            session_id VARCHAR PRIMARY KEY,
+            data BLOB NOT NULL,
+            expires_at TIMESTAMP,
+            created_at TIMESTAMP DEFAULT NOW(),
+            updated_at TIMESTAMP DEFAULT NOW()
+        );
+        CREATE INDEX IF NOT EXISTS idx_{self._table_name}_expires_at
+        ON {self._table_name}(expires_at);
+        """
+
+    def _get_drop_table_sql(self) -> "list[str]":
+        """Get DuckDB DROP TABLE SQL statements.
+
+        Returns:
+            List of SQL statements to drop indexes and table.
+        """
+        return [f"DROP INDEX IF EXISTS idx_{self._table_name}_expires_at", f"DROP TABLE IF EXISTS {self._table_name}"]
+
+    def _datetime_to_timestamp(self, dt: "datetime | None") -> "str | None":
+        """Convert datetime to ISO 8601 string for DuckDB TIMESTAMP storage.
+
+        Args:
+            dt: Datetime to convert (must be UTC-aware).
+
+        Returns:
+            ISO 8601 formatted string, or None if dt is None.
+
+        Notes:
+            DuckDB's TIMESTAMP type accepts ISO 8601 format strings.
+            This enables efficient storage and comparison operations.
+        """
+        if dt is None:
+            return None
+        return dt.isoformat()
+
+    def _timestamp_to_datetime(self, ts: "str | datetime | None") -> "datetime | None":
+        """Convert TIMESTAMP string back to datetime.
+
+        Args:
+            ts: ISO 8601 timestamp string or datetime object.
+
+        Returns:
+            UTC-aware datetime, or None if ts is None.
+        """
+        if ts is None:
+            return None
+        if isinstance(ts, datetime):
+            if ts.tzinfo is None:
+                return ts.replace(tzinfo=timezone.utc)
+            return ts
+        dt = datetime.fromisoformat(ts)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+
+    def _create_table(self) -> None:
+        """Synchronous implementation of create_table."""
+        sql = self._get_create_table_sql()
+        with self._config.provide_session() as driver:
+            driver.execute_script(sql)
+        logger.debug("Created session table: %s", self._table_name)
+
+    async def create_table(self) -> None:
+        """Create the session table if it doesn't exist."""
+        await async_(self._create_table)()
+
+    def _get(self, key: str, renew_for: "int | timedelta | None" = None) -> "bytes | None":
+        """Synchronous implementation of get."""
+        sql = f"""
+        SELECT data, expires_at FROM {self._table_name}
+        WHERE session_id = ?
+        AND (expires_at IS NULL OR expires_at > CURRENT_TIMESTAMP)
+        """
+
+        with self._config.provide_connection() as conn:
+            cursor = conn.execute(sql, (key,))
+            row = cursor.fetchone()
+
+            if row is None:
+                return None
+
+            data, expires_at_str = row
+
+            if renew_for is not None and expires_at_str is not None:
+                new_expires_at = self._calculate_expires_at(renew_for)
+                new_expires_at_str = self._datetime_to_timestamp(new_expires_at)
+                if new_expires_at_str is not None:
+                    update_sql = f"""
+                    UPDATE {self._table_name}
+                    SET expires_at = ?, updated_at = NOW()
+                    WHERE session_id = ?
+                    """
+                    conn.execute(update_sql, (new_expires_at_str, key))
+                    conn.commit()
+
+            return bytes(data)
+
+    async def get(self, key: str, renew_for: "int | timedelta | None" = None) -> "bytes | None":
+        """Get a session value by key.
+
+        Args:
+            key: Session ID to retrieve.
+            renew_for: If given, renew the expiry time for this duration.
+
+        Returns:
+            Session data as bytes if found and not expired, None otherwise.
+        """
+        return await async_(self._get)(key, renew_for)
+
+    def _set(self, key: str, value: "str | bytes", expires_in: "int | timedelta | None" = None) -> None:
+        """Synchronous implementation of set.
+
+        Notes:
+            Stores expires_at as TIMESTAMP (ISO 8601 string) for DuckDB native support.
+            Uses INSERT ON CONFLICT instead of INSERT OR REPLACE to ensure all columns
+            are properly updated. created_at uses DEFAULT on insert, updated_at gets
+            current timestamp on both insert and update.
+        """
+        data = self._value_to_bytes(value)
+        expires_at = self._calculate_expires_at(expires_in)
+        expires_at_str = self._datetime_to_timestamp(expires_at)
+
+        sql = f"""
+        INSERT INTO {self._table_name} (session_id, data, expires_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT (session_id)
+        DO UPDATE SET
+            data = EXCLUDED.data,
+            expires_at = EXCLUDED.expires_at,
+            updated_at = NOW()
+        """
+
+        with self._config.provide_connection() as conn:
+            conn.execute(sql, (key, data, expires_at_str))
+            conn.commit()
+
+    async def set(self, key: str, value: "str | bytes", expires_in: "int | timedelta | None" = None) -> None:
+        """Store a session value.
+
+        Args:
+            key: Session ID.
+            value: Session data.
+            expires_in: Time until expiration.
+        """
+        await async_(self._set)(key, value, expires_in)
+
+    def _delete(self, key: str) -> None:
+        """Synchronous implementation of delete."""
+        sql = f"DELETE FROM {self._table_name} WHERE session_id = ?"
+
+        with self._config.provide_connection() as conn:
+            conn.execute(sql, (key,))
+            conn.commit()
+
+    async def delete(self, key: str) -> None:
+        """Delete a session by key.
+
+        Args:
+            key: Session ID to delete.
+        """
+        await async_(self._delete)(key)
+
+    def _delete_all(self) -> None:
+        """Synchronous implementation of delete_all."""
+        sql = f"DELETE FROM {self._table_name}"
+
+        with self._config.provide_connection() as conn:
+            conn.execute(sql)
+            conn.commit()
+        logger.debug("Deleted all sessions from table: %s", self._table_name)
+
+    async def delete_all(self) -> None:
+        """Delete all sessions from the store."""
+        await async_(self._delete_all)()
+
+    def _exists(self, key: str) -> bool:
+        """Synchronous implementation of exists."""
+        sql = f"""
+        SELECT 1 FROM {self._table_name}
+        WHERE session_id = ?
+        AND (expires_at IS NULL OR expires_at > CURRENT_TIMESTAMP)
+        """
+
+        with self._config.provide_connection() as conn:
+            cursor = conn.execute(sql, (key,))
+            result = cursor.fetchone()
+            return result is not None
+
+    async def exists(self, key: str) -> bool:
+        """Check if a session key exists and is not expired.
+
+        Args:
+            key: Session ID to check.
+
+        Returns:
+            True if the session exists and is not expired.
+        """
+        return await async_(self._exists)(key)
+
+    def _expires_in(self, key: str) -> "int | None":
+        """Synchronous implementation of expires_in."""
+        sql = f"""
+        SELECT expires_at FROM {self._table_name}
+        WHERE session_id = ?
+        """
+
+        with self._config.provide_connection() as conn:
+            cursor = conn.execute(sql, (key,))
+            row = cursor.fetchone()
+
+            if row is None or row[0] is None:
+                return None
+
+            expires_at_str = row[0]
+            expires_at = self._timestamp_to_datetime(expires_at_str)
+
+            if expires_at is None:
+                return None
+
+            now = datetime.now(timezone.utc)
+
+            if expires_at <= now:
+                return 0
+
+            delta = expires_at - now
+            return int(delta.total_seconds())
+
+    async def expires_in(self, key: str) -> "int | None":
+        """Get the time in seconds until the session expires.
+
+        Args:
+            key: Session ID to check.
+
+        Returns:
+            Seconds until expiration, or None if no expiry or key doesn't exist.
+        """
+        return await async_(self._expires_in)(key)
+
+    def _delete_expired(self) -> int:
+        """Synchronous implementation of delete_expired."""
+        sql = f"DELETE FROM {self._table_name} WHERE expires_at <= CURRENT_TIMESTAMP"
+
+        with self._config.provide_connection() as conn:
+            cursor = conn.execute(sql)
+            count = cursor.fetchone()
+            row_count = count[0] if count else 0
+            if row_count > 0:
+                logger.debug("Cleaned up %d expired sessions", row_count)
+            return row_count
+
+    async def delete_expired(self) -> int:
+        """Delete all expired sessions.
+
+        Returns:
+            Number of sessions deleted.
+        """
+        return await async_(self._delete_expired)()

sqlspec/adapters/duckdb/pool.py

@@ -4,9 +4,9 @@ import logging
 import threading
 import time
 from contextlib import contextmanager, suppress
-from typing import TYPE_CHECKING, Any, Final, Optional, cast
+from typing import TYPE_CHECKING, Any, Final, cast
 
-import duckdb  # type: ignore[import-untyped]
+import duckdb
 
 from sqlspec.adapters.duckdb._types import DuckDBConnection
 
@@ -51,9 +51,9 @@ class DuckDBConnectionPool:
         self,
         connection_config: "dict[str, Any]",
         pool_recycle_seconds: int = POOL_RECYCLE,
-        extensions: "Optional[list[dict[str, Any]]]" = None,
-        secrets: "Optional[list[dict[str, Any]]]" = None,
-        on_connection_create: "Optional[Callable[[DuckDBConnection], None]]" = None,
+        extensions: "list[dict[str, Any]] | None" = None,
+        secrets: "list[dict[str, Any]] | None" = None,
+        on_connection_create: "Callable[[DuckDBConnection], None] | None" = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the thread-local connection manager.

sqlspec/adapters/duckdb/type_converter.py

@@ -5,20 +5,63 @@ support and standardized datetime formatting.
 """
 
 from datetime import datetime
-from typing import Any
+from functools import lru_cache
+from typing import Any, Final
 from uuid import UUID
 
 from sqlspec.core.type_conversion import BaseTypeConverter, convert_uuid, format_datetime_rfc3339
 
+DUCKDB_SPECIAL_CHARS: Final[frozenset[str]] = frozenset({"-", ":", "T", ".", "[", "{"})
+
 
 class DuckDBTypeConverter(BaseTypeConverter):
     """DuckDB-specific type conversion with native UUID support.
 
     Extends the base TypeDetector with DuckDB-specific functionality
     including native UUID handling and standardized datetime formatting.
+    Includes per-instance LRU cache for improved performance.
     """
 
-    __slots__ = ()
+    __slots__ = ("_convert_cache", "_enable_uuid_conversion")
+
+    def __init__(self, cache_size: int = 5000, enable_uuid_conversion: bool = True) -> None:
+        """Initialize converter with per-instance conversion cache.
+
+        Args:
+            cache_size: Maximum number of string values to cache (default: 5000)
+            enable_uuid_conversion: Enable automatic UUID string conversion (default: True)
+        """
+        super().__init__()
+        self._enable_uuid_conversion = enable_uuid_conversion
+
+        @lru_cache(maxsize=cache_size)
+        def _cached_convert(value: str) -> Any:
+            if not value or not any(c in value for c in DUCKDB_SPECIAL_CHARS):
+                return value
+            detected_type = self.detect_type(value)
+            if detected_type:
+                if detected_type == "uuid" and not self._enable_uuid_conversion:
+                    return value
+                try:
+                    return self.convert_value(value, detected_type)
+                except Exception:
+                    return value
+            return value
+
+        self._convert_cache = _cached_convert
+
+    def convert_if_detected(self, value: Any) -> Any:
+        """Convert string if special type detected (cached).
+
+        Args:
+            value: Value to potentially convert
+
+        Returns:
+            Converted value or original value
+        """
+        if not isinstance(value, str):
+            return value
+        return self._convert_cache(value)
 
     def handle_uuid(self, value: Any) -> Any:
         """Handle UUID conversion for DuckDB.
@@ -27,12 +70,12 @@ class DuckDBTypeConverter(BaseTypeConverter):
             value: Value that might be a UUID.
 
         Returns:
-            UUID object if value is UUID-like, original value otherwise.
+            UUID object if value is UUID-like and conversion enabled, original value otherwise.
         """
         if isinstance(value, UUID):
-            return value  # DuckDB supports UUID natively
+            return value
 
-        if isinstance(value, str):
+        if isinstance(value, str) and self._enable_uuid_conversion:
             detected_type = self.detect_type(value)
             if detected_type == "uuid":
                 return convert_uuid(value)
@@ -59,23 +102,14 @@ class DuckDBTypeConverter(BaseTypeConverter):
         Returns:
             Converted value appropriate for DuckDB.
         """
-        # Handle UUIDs
         if isinstance(value, (str, UUID)):
             uuid_value = self.handle_uuid(value)
             if isinstance(uuid_value, UUID):
                 return uuid_value
 
-        # Handle other string types
         if isinstance(value, str):
-            detected_type = self.detect_type(value)
-            if detected_type:
-                try:
-                    return self.convert_value(value, detected_type)
-                except Exception:
-                    # If conversion fails, return original value
-                    return value
+            return self.convert_if_detected(value)
 
-        # Handle datetime formatting
         if isinstance(value, datetime):
             return self.format_datetime(value)
 
@@ -90,14 +124,10 @@ class DuckDBTypeConverter(BaseTypeConverter):
         Returns:
             Value ready for DuckDB parameter binding.
         """
-        # DuckDB can handle most Python types natively
         converted = self.convert_duckdb_value(value)
-
-        # Ensure UUIDs are properly handled
         if isinstance(converted, UUID):
-            return converted  # DuckDB native UUID support
-
+            return converted
         return converted
 
 
-__all__ = ("DuckDBTypeConverter",)
+__all__ = ("DUCKDB_SPECIAL_CHARS", "DuckDBTypeConverter")

sqlspec/adapters/oracledb/_numpy_handlers.py

@@ -0,0 +1,133 @@
+"""Oracle NumPy vector type handlers for VECTOR data type support.
+
+Provides automatic conversion between NumPy arrays and Oracle VECTOR types
+via connection type handlers. Requires Oracle Database 23ai or higher.
+"""
+
+import array
+import logging
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.typing import NUMPY_INSTALLED
+
+if TYPE_CHECKING:
+    from oracledb import AsyncConnection, AsyncCursor, Connection, Cursor
+
+__all__ = (
+    "_input_type_handler",
+    "_output_type_handler",
+    "numpy_converter_in",
+    "numpy_converter_out",
+    "register_numpy_handlers",
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+DTYPE_TO_ARRAY_CODE: dict[str, str] = {"float64": "d", "float32": "f", "uint8": "B", "int8": "b"}
+
+
+def numpy_converter_in(value: Any) -> "array.array[Any]":
+    """Convert NumPy array to Oracle array for VECTOR insertion.
+
+    Args:
+        value: NumPy ndarray to convert.
+
+    Returns:
+        Python array.array compatible with Oracle VECTOR type.
+
+    Raises:
+        ImportError: If NumPy is not installed.
+        TypeError: If NumPy dtype is not supported for Oracle VECTOR.
+    """
+    if not NUMPY_INSTALLED:
+        msg = "NumPy is not installed - cannot convert vectors"
+        raise ImportError(msg)
+
+    dtype_name = value.dtype.name
+    array_code = DTYPE_TO_ARRAY_CODE.get(dtype_name)
+
+    if not array_code:
+        supported = ", ".join(DTYPE_TO_ARRAY_CODE.keys())
+        msg = f"Unsupported NumPy dtype for Oracle VECTOR: {dtype_name}. Supported: {supported}"
+        raise TypeError(msg)
+
+    return array.array(array_code, value)
+
+
+def numpy_converter_out(value: "array.array[Any]") -> Any:
+    """Convert Oracle array to NumPy array for VECTOR retrieval.
+
+    Args:
+        value: Oracle array.array from VECTOR column.
+
+    Returns:
+        NumPy ndarray with appropriate dtype, or original value if NumPy not installed.
+    """
+    if not NUMPY_INSTALLED:
+        return value
+
+    import numpy as np
+
+    return np.array(value, copy=True, dtype=value.typecode)
+
+
+def _input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
+    """Oracle input type handler for NumPy arrays.
+
+    Args:
+        cursor: Oracle cursor (sync or async).
+        value: Value being inserted.
+        arraysize: Array size for the cursor variable.
+
+    Returns:
+        Cursor variable with NumPy converter if value is ndarray, None otherwise.
+    """
+    if not NUMPY_INSTALLED:
+        return None
+
+    import numpy as np
+    import oracledb
+
+    if isinstance(value, np.ndarray):
+        return cursor.var(oracledb.DB_TYPE_VECTOR, arraysize=arraysize, inconverter=numpy_converter_in)
+    return None
+
+
+def _output_type_handler(cursor: "Cursor | AsyncCursor", metadata: Any) -> Any:
+    """Oracle output type handler for VECTOR columns.
+
+    Args:
+        cursor: Oracle cursor (sync or async).
+        metadata: Column metadata from Oracle.
+
+    Returns:
+        Cursor variable with NumPy converter if column is VECTOR, None otherwise.
+    """
+    if not NUMPY_INSTALLED:
+        return None
+
+    import oracledb
+
+    if metadata.type_code is oracledb.DB_TYPE_VECTOR:
+        return cursor.var(metadata.type_code, arraysize=cursor.arraysize, outconverter=numpy_converter_out)
+    return None
+
+
+def register_numpy_handlers(connection: "Connection | AsyncConnection") -> None:
+    """Register NumPy type handlers on Oracle connection.
+
+    Enables automatic conversion between NumPy arrays and Oracle VECTOR types.
+    Works for both sync and async connections.
+
+    Args:
+        connection: Oracle connection (sync or async).
+    """
+    if not NUMPY_INSTALLED:
+        logger.debug("NumPy not installed - skipping vector type handlers")
+        return
+
+    connection.inputtypehandler = _input_type_handler
+    connection.outputtypehandler = _output_type_handler
+    logger.debug("Registered NumPy vector type handlers on Oracle connection")

sqlspec/adapters/oracledb/_types.py

@@ -3,19 +3,37 @@ from typing import TYPE_CHECKING
 from oracledb import AsyncConnection, Connection
 
 if TYPE_CHECKING:
+    from typing import TypeAlias
+
+    from oracledb import DB_TYPE_VECTOR
     from oracledb.pool import AsyncConnectionPool, ConnectionPool
-    from typing_extensions import TypeAlias
 
     OracleSyncConnection: TypeAlias = Connection
     OracleAsyncConnection: TypeAlias = AsyncConnection
     OracleSyncConnectionPool: TypeAlias = ConnectionPool
     OracleAsyncConnectionPool: TypeAlias = AsyncConnectionPool
+    OracleVectorType: TypeAlias = int
 else:
     from oracledb.pool import AsyncConnectionPool, ConnectionPool
 
+    try:
+        from oracledb import DB_TYPE_VECTOR
+
+        OracleVectorType = int
+    except ImportError:
+        DB_TYPE_VECTOR = None
+        OracleVectorType = int
+
     OracleSyncConnection = Connection
     OracleAsyncConnection = AsyncConnection
     OracleSyncConnectionPool = ConnectionPool
     OracleAsyncConnectionPool = AsyncConnectionPool
 
-__all__ = ("OracleAsyncConnection", "OracleAsyncConnectionPool", "OracleSyncConnection", "OracleSyncConnectionPool")
+__all__ = (
+    "DB_TYPE_VECTOR",
+    "OracleAsyncConnection",
+    "OracleAsyncConnectionPool",
+    "OracleSyncConnection",
+    "OracleSyncConnectionPool",
+    "OracleVectorType",
+)

sqlspec/adapters/oracledb/adk/__init__.py

@@ -0,0 +1,5 @@
+"""Oracle ADK extension integration."""
+
+from sqlspec.adapters.oracledb.adk.store import OracleAsyncADKStore, OracleSyncADKStore
+
+__all__ = ("OracleAsyncADKStore", "OracleSyncADKStore")