sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/adapters/sqlite/litestar/store.py

@@ -0,0 +1,316 @@
+"""SQLite 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.sync_tools import async_
+
+if TYPE_CHECKING:
+    from sqlspec.adapters.sqlite.config import SqliteConfig
+
+
+SECONDS_PER_DAY = 86400.0
+JULIAN_EPOCH = 2440587.5
+
+__all__ = ("SQLiteStore",)
+
+
+class SQLiteStore(BaseSQLSpecStore["SqliteConfig"]):
+    """SQLite session store using synchronous SQLite driver.
+
+    Implements server-side session storage for Litestar using SQLite
+    via the synchronous sqlite3 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
+    - Automatic expiration handling
+    - Efficient cleanup of expired sessions
+
+    Args:
+        config: SqliteConfig instance.
+
+    Example:
+        from sqlspec.adapters.sqlite import SqliteConfig
+        from sqlspec.adapters.sqlite.litestar.store import SQLiteStore
+
+        config = SqliteConfig(database=":memory:")
+        store = SQLiteStore(config)
+        await store.create_table()
+    """
+
+    __slots__ = ()
+
+    def __init__(self, config: "SqliteConfig") -> None:
+        """Initialize SQLite session store.
+
+        Args:
+            config: SqliteConfig instance.
+
+        Notes:
+            Table name is read from config.extension_config["litestar"]["session_table"].
+        """
+        super().__init__(config)
+
+    def _get_create_table_sql(self) -> str:
+        """Get SQLite CREATE TABLE SQL.
+
+        Returns:
+            SQL statement to create the sessions table with proper indexes.
+
+        Notes:
+            - Uses REAL type for expires_at (stores Julian Day number)
+            - Julian Day enables direct comparison with julianday('now')
+            - Partial index WHERE expires_at IS NOT NULL reduces index size
+            - This approach ensures the index is actually used by query optimizer
+        """
+        return f"""
+        CREATE TABLE IF NOT EXISTS {self._table_name} (
+            session_id TEXT PRIMARY KEY,
+            data BLOB NOT NULL,
+            expires_at REAL
+        );
+        CREATE INDEX IF NOT EXISTS idx_{self._table_name}_expires_at
+        ON {self._table_name}(expires_at) WHERE expires_at IS NOT NULL;
+        """
+
+    def _get_drop_table_sql(self) -> "list[str]":
+        """Get SQLite 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_julian(self, dt: "datetime | None") -> "float | None":
+        """Convert datetime to Julian Day number for SQLite storage.
+
+        Args:
+            dt: Datetime to convert (must be UTC-aware).
+
+        Returns:
+            Julian Day number as REAL, or None if dt is None.
+
+        Notes:
+            Julian Day number is days since November 24, 4714 BCE (proleptic Gregorian).
+            This enables direct comparison with julianday('now') in SQL queries.
+        """
+        if dt is None:
+            return None
+
+        epoch = datetime(1970, 1, 1, tzinfo=timezone.utc)
+        delta_days = (dt - epoch).total_seconds() / SECONDS_PER_DAY
+        return JULIAN_EPOCH + delta_days
+
+    def _julian_to_datetime(self, julian: "float | None") -> "datetime | None":
+        """Convert Julian Day number back to datetime.
+
+        Args:
+            julian: Julian Day number.
+
+        Returns:
+            UTC-aware datetime, or None if julian is None.
+        """
+        if julian is None:
+            return None
+
+        days_since_epoch = julian - JULIAN_EPOCH
+        timestamp = days_since_epoch * SECONDS_PER_DAY
+        return datetime.fromtimestamp(timestamp, tz=timezone.utc)
+
+    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)
+        self._log_table_created()
+
+    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 julianday(expires_at) > julianday('now'))
+        """
+
+        with self._config.provide_connection() as conn:
+            cursor = conn.execute(sql, (key,))
+            row = cursor.fetchone()
+
+            if row is None:
+                return None
+
+            data, expires_at_julian = row
+
+            if renew_for is not None and expires_at_julian is not None:
+                new_expires_at = self._calculate_expires_at(renew_for)
+                new_expires_at_julian = self._datetime_to_julian(new_expires_at)
+                if new_expires_at_julian is not None:
+                    update_sql = f"""
+                    UPDATE {self._table_name}
+                    SET expires_at = ?
+                    WHERE session_id = ?
+                    """
+                    conn.execute(update_sql, (new_expires_at_julian, 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 Julian Day number (REAL) for optimal index usage.
+        """
+        data = self._value_to_bytes(value)
+        expires_at = self._calculate_expires_at(expires_in)
+        expires_at_julian = self._datetime_to_julian(expires_at)
+
+        sql = f"""
+        INSERT OR REPLACE INTO {self._table_name} (session_id, data, expires_at)
+        VALUES (?, ?, ?)
+        """
+
+        with self._config.provide_connection() as conn:
+            conn.execute(sql, (key, data, expires_at_julian))
+            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()
+        self._log_delete_all()
+
+    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 julianday(expires_at) > julianday('now'))
+        """
+
+        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_julian = row[0]
+            expires_at = self._julian_to_datetime(expires_at_julian)
+
+            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 julianday(expires_at) <= julianday('now')"
+
+        with self._config.provide_connection() as conn:
+            cursor = conn.execute(sql)
+            conn.commit()
+            count = cursor.rowcount
+            if count > 0:
+                self._log_delete_expired(count)
+            return count
+
+    async def delete_expired(self) -> int:
+        """Delete all expired sessions.
+
+        Returns:
+            Number of sessions deleted.
+        """
+        return await async_(self._delete_expired)()

sqlspec/adapters/sqlite/pool.py

@@ -0,0 +1,198 @@
+"""SQLite database configuration with thread-local connections."""
+
+import contextlib
+import sqlite3
+import threading
+import time
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, TypedDict, cast
+
+from typing_extensions import NotRequired
+
+from sqlspec.adapters.sqlite._typing import SqliteConnection
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+class SqliteConnectionParams(TypedDict):
+    """SQLite connection parameters."""
+
+    database: NotRequired[str]
+    timeout: NotRequired[float]
+    detect_types: NotRequired[int]
+    isolation_level: "NotRequired[str | None]"
+    check_same_thread: NotRequired[bool]
+    factory: "NotRequired[type[SqliteConnection] | None]"
+    cached_statements: NotRequired[int]
+    uri: NotRequired[bool]
+
+
+__all__ = ("SqliteConnectionPool",)
+
+logger = get_logger(__name__)
+
+
+class SqliteConnectionPool:
+    """Thread-local connection manager for SQLite.
+
+    SQLite connections aren't thread-safe, so we use thread-local storage
+    to ensure each thread has its own connection. This is simpler and more
+    efficient than a traditional pool for SQLite's constraints.
+    """
+
+    __slots__ = (
+        "_connection_parameters",
+        "_enable_optimizations",
+        "_health_check_interval",
+        "_recycle_seconds",
+        "_thread_local",
+    )
+
+    def __init__(
+        self,
+        connection_parameters: "dict[str, Any]",
+        enable_optimizations: bool = True,
+        recycle_seconds: int = 86400,
+        health_check_interval: float = 30.0,
+    ) -> None:
+        """Initialize the thread-local connection manager.
+
+        Args:
+            connection_parameters: SQLite connection parameters
+            enable_optimizations: Whether to apply performance PRAGMAs
+            recycle_seconds: Connection recycle time in seconds (default 24h)
+            health_check_interval: Seconds of idle time before running health check
+        """
+        if "check_same_thread" not in connection_parameters:
+            connection_parameters = {**connection_parameters, "check_same_thread": False}
+        self._connection_parameters = connection_parameters
+        self._thread_local = threading.local()
+        self._enable_optimizations = enable_optimizations
+        self._recycle_seconds = recycle_seconds
+        self._health_check_interval = health_check_interval
+
+    def _create_connection(self) -> SqliteConnection:
+        """Create a new SQLite connection with optimizations."""
+        connection = sqlite3.connect(**self._connection_parameters)
+
+        if self._enable_optimizations:
+            database = self._connection_parameters.get("database", ":memory:")
+            is_memory = database == ":memory:" or "mode=memory" in str(database)
+
+            if is_memory:
+                connection.execute("PRAGMA journal_mode = MEMORY")
+                connection.execute("PRAGMA synchronous = OFF")
+                connection.execute("PRAGMA temp_store = MEMORY")
+            else:
+                connection.execute("PRAGMA journal_mode = WAL")
+                connection.execute("PRAGMA synchronous = NORMAL")
+                connection.execute("PRAGMA busy_timeout = 5000")
+
+            connection.execute("PRAGMA foreign_keys = ON")
+
+        return connection  # type: ignore[no-any-return]
+
+    def _is_connection_alive(self, connection: SqliteConnection) -> bool:
+        """Check if a connection is still alive and usable.
+
+        Args:
+            connection: Connection to check
+
+        Returns:
+            True if connection is alive, False otherwise
+        """
+        try:
+            connection.execute("SELECT 1")
+        except Exception:
+            return False
+        return True
+
+    def _get_thread_connection(self) -> SqliteConnection:
+        """Get or create a connection for the current thread."""
+        thread_state = self._thread_local.__dict__
+        if "connection" not in thread_state:
+            self._thread_local.connection = self._create_connection()
+            self._thread_local.created_at = time.time()
+            self._thread_local.last_used = time.time()
+            return cast("SqliteConnection", self._thread_local.connection)
+
+        if self._recycle_seconds > 0 and time.time() - self._thread_local.created_at > self._recycle_seconds:
+            logger.debug("SQLite connection exceeded recycle time, recreating")
+            with contextlib.suppress(Exception):
+                self._thread_local.connection.close()
+            self._thread_local.connection = self._create_connection()
+            self._thread_local.created_at = time.time()
+            self._thread_local.last_used = time.time()
+            return cast("SqliteConnection", self._thread_local.connection)
+
+        idle_time = time.time() - thread_state.get("last_used", 0)
+        if idle_time > self._health_check_interval and not self._is_connection_alive(self._thread_local.connection):
+            logger.debug("SQLite connection failed health check after %.1fs idle, recreating", idle_time)
+            with contextlib.suppress(Exception):
+                self._thread_local.connection.close()
+            self._thread_local.connection = self._create_connection()
+            self._thread_local.created_at = time.time()
+
+        self._thread_local.last_used = time.time()
+        return cast("SqliteConnection", self._thread_local.connection)
+
+    def _close_thread_connection(self) -> None:
+        """Close the connection for the current thread."""
+        thread_state = self._thread_local.__dict__
+        if "connection" in thread_state:
+            with contextlib.suppress(Exception):
+                self._thread_local.connection.close()
+            del self._thread_local.connection
+            if "created_at" in thread_state:
+                del self._thread_local.created_at
+            if "last_used" in thread_state:
+                del self._thread_local.last_used
+
+    @contextmanager
+    def get_connection(self) -> "Generator[SqliteConnection, None, None]":
+        """Get a thread-local connection.
+
+        Yields:
+            SqliteConnection: A thread-local connection.
+        """
+        connection = self._get_thread_connection()
+        try:
+            yield connection
+        finally:
+            with contextlib.suppress(Exception):
+                if connection.in_transaction:
+                    connection.commit()
+
+    def close(self) -> None:
+        """Close the thread-local connection if it exists."""
+        self._close_thread_connection()
+
+    def acquire(self) -> SqliteConnection:
+        """Acquire a thread-local connection.
+
+        Returns:
+            SqliteConnection: A thread-local connection
+        """
+        return self._get_thread_connection()
+
+    def release(self, connection: SqliteConnection) -> None:
+        """Release a connection (no-op for thread-local connections).
+
+        Args:
+            connection: The connection to release (ignored)
+        """
+
+    def size(self) -> int:
+        """Get pool size (always 1 for thread-local)."""
+        try:
+            _ = self._thread_local.connection
+        except AttributeError:
+            return 0
+        else:
+            return 1
+
+    def checked_out(self) -> int:
+        """Get number of checked out connections (always 0)."""
+        return 0

sqlspec/adapters/sqlite/type_converter.py

@@ -0,0 +1,114 @@
+"""SQLite custom type handlers for optional JSON and type conversion support.
+
+Provides registration functions for SQLite's adapter/converter system to enable
+custom type handling. All handlers are optional and must be explicitly enabled
+via SqliteDriverFeatures configuration.
+
+All functions are designed for mypyc compilation using functools.partial
+instead of lambdas for adapter registration.
+"""
+
+import json
+import sqlite3
+from functools import partial
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ("json_adapter", "json_converter", "register_type_handlers", "unregister_type_handlers")
+
+logger = get_logger(__name__)
+
+DEFAULT_JSON_TYPE = "JSON"
+
+
+def json_adapter(value: Any, serializer: "Callable[[Any], str] | None" = None) -> str:
+    """Convert Python dict/list to JSON string for SQLite storage.
+
+    Args:
+        value: Python dict or list to serialize.
+        serializer: Optional JSON serializer callable. Defaults to standard json.dumps.
+
+    Returns:
+        JSON string representation.
+    """
+    if serializer is None:
+        return json.dumps(value, ensure_ascii=False)
+    return serializer(value)
+
+
+def json_converter(value: bytes, deserializer: "Callable[[str], Any] | None" = None) -> Any:
+    """Convert JSON string from SQLite to Python dict/list.
+
+    Args:
+        value: UTF-8 encoded JSON bytes from SQLite.
+        deserializer: Optional JSON deserializer callable. Defaults to standard json.loads.
+
+    Returns:
+        Deserialized Python object (dict or list).
+    """
+    if deserializer is None:
+        return json.loads(value.decode("utf-8"))
+    return deserializer(value.decode("utf-8"))
+
+
+def _make_json_adapter(serializer: "Callable[[Any], str] | None") -> "Callable[[Any], str]":
+    """Create a JSON adapter function with bound serializer.
+
+    This is a module-level factory to avoid lambda closures which are
+    problematic for mypyc compilation.
+
+    Args:
+        serializer: Optional JSON serializer callable.
+
+    Returns:
+        Adapter function ready for sqlite3.register_adapter.
+    """
+    return partial(json_adapter, serializer=serializer)
+
+
+def _make_json_converter(deserializer: "Callable[[str], Any] | None") -> "Callable[[bytes], Any]":
+    """Create a JSON converter function with bound deserializer.
+
+    This is a module-level factory to avoid lambda closures which are
+    problematic for mypyc compilation.
+
+    Args:
+        deserializer: Optional JSON deserializer callable.
+
+    Returns:
+        Converter function ready for sqlite3.register_converter.
+    """
+    return partial(json_converter, deserializer=deserializer)
+
+
+def register_type_handlers(
+    json_serializer: "Callable[[Any], str] | None" = None, json_deserializer: "Callable[[str], Any] | None" = None
+) -> None:
+    """Register custom type adapters and converters with sqlite3 module.
+
+    This function registers handlers globally for the sqlite3 module. It should be
+    called once during application initialization if custom type handling is needed.
+
+    Args:
+        json_serializer: Optional custom JSON serializer (e.g., orjson.dumps).
+        json_deserializer: Optional custom JSON deserializer (e.g., orjson.loads).
+    """
+    dict_adapter = _make_json_adapter(json_serializer)
+    list_adapter = _make_json_adapter(json_serializer)
+    converter = _make_json_converter(json_deserializer)
+
+    sqlite3.register_adapter(dict, dict_adapter)
+    sqlite3.register_adapter(list, list_adapter)
+    sqlite3.register_converter(DEFAULT_JSON_TYPE, converter)
+
+
+def unregister_type_handlers() -> None:
+    """Unregister custom type handlers from sqlite3 module.
+
+    Note: sqlite3 module does not provide an official unregister API, so this
+    function is a no-op placeholder for API consistency with other adapters.
+    """