Source code for sqlspec.config

"""Database configuration surfaces for SQLSpec adapters.

This module is intentionally interpreted even though compiled modules consume
its config classes. The public configuration API is stability-critical for
compiled callers: keep constructor fields, protocol attributes, migration
refresh behavior, storage capability hooks, and provider context managers
runtime-visible and backwards coherent. Move small pure helpers into compiled
modules only after proving the boundary with installed-wheel smoke coverage.
"""

import asyncio
import threading
from abc import ABC, abstractmethod
from collections.abc import Callable
from inspect import Signature, signature
from pathlib import Path
from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeAlias, TypeVar, cast

from typing_extensions import NotRequired, TypedDict

from sqlspec.core.config_runtime import (
    build_default_statement_config,
    close_async_pool,
    close_sync_pool,
    create_async_pool,
    create_sync_pool,
    seed_runtime_driver_features,
)
from sqlspec.exceptions import MissingDependencyError
from sqlspec.extensions.events import EventRuntimeHints
from sqlspec.loader import SQLFileLoader
from sqlspec.migrations import AsyncMigrationTracker, SyncMigrationTracker, create_migration_commands
from sqlspec.observability import ObservabilityConfig, ObservabilityRuntime
from sqlspec.typing import ConnectionT, PoolT
from sqlspec.utils.logging import get_logger
from sqlspec.utils.module_loader import ensure_pyarrow

if TYPE_CHECKING:
    from collections.abc import Awaitable
    from contextlib import AbstractAsyncContextManager, AbstractContextManager

    from sqlspec.core import StatementConfig
    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
    from sqlspec.migrations.commands import AsyncMigrationCommands, SyncMigrationCommands
    from sqlspec.storage import StorageCapabilities


__all__ = (
    "ADKCompressionConfig",
    "ADKConfig",
    "ADKPartitionConfig",
    "ADKRetentionConfig",
    "ADKSqliteOptimizationConfig",
    "AsyncConfigT",
    "AsyncDatabaseConfig",
    "ConfigT",
    "ConnectionT",
    "DatabaseConfigProtocol",
    "DriverT",
    "EventsConfig",
    "ExtensionConfigs",
    "FastAPIConfig",
    "FlaskConfig",
    "LifecycleConfig",
    "LitestarConfig",
    "MigrationConfig",
    "NoPoolAsyncConfig",
    "NoPoolSyncConfig",
    "OpenTelemetryConfig",
    "PoolT",
    "PrometheusConfig",
    "SanicConfig",
    "StarletteConfig",
    "SyncConfigT",
    "SyncDatabaseConfig",
)

AsyncConfigT = TypeVar("AsyncConfigT", bound="AsyncDatabaseConfig[Any, Any, Any] | NoPoolAsyncConfig[Any, Any]")
SyncConfigT = TypeVar("SyncConfigT", bound="SyncDatabaseConfig[Any, Any, Any] | NoPoolSyncConfig[Any, Any]")
ConfigT = TypeVar(
    "ConfigT",
    bound="AsyncDatabaseConfig[Any, Any, Any] | NoPoolAsyncConfig[Any, Any] | SyncDatabaseConfig[Any, Any, Any] | NoPoolSyncConfig[Any, Any]",
)

DriverT = TypeVar("DriverT", bound="SyncDriverAdapterBase | AsyncDriverAdapterBase")

logger = get_logger("sqlspec.config")

DRIVER_FEATURE_LIFECYCLE_HOOKS: dict[str, str | None] = {
    "on_connection_create": "connection",
    "on_connection_destroy": "connection",
    "on_pool_create": "pool",
    "on_pool_destroying": "pool",
    "on_pool_destroy": "pool",
    "on_session_start": "session",
    "on_session_end": "session",
}


class _DriverFeatureHookWrapper:
    __slots__ = ("_callback", "_context_key", "_expects_argument")

    def __init__(self, callback: "Callable[..., Any]", context_key: "str | None", expects_argument: bool) -> None:
        self._callback = callback
        self._context_key = context_key
        self._expects_argument = expects_argument

    def __call__(self, context: "dict[str, Any]") -> None:
        if not self._expects_argument:
            self._callback()
            return
        if self._context_key is None:
            self._callback(context)
            return
        self._callback(context.get(self._context_key))



[docs]
class LifecycleConfig(TypedDict):
    """Lifecycle hooks for database adapters.

    Each hook accepts a list of callables to support multiple handlers.
    """

    on_connection_create: NotRequired[list[Callable[[Any], None]]]
    on_connection_destroy: NotRequired[list[Callable[[Any], None]]]
    on_pool_create: NotRequired[list[Callable[[Any], None]]]
    on_pool_destroying: NotRequired[list[Callable[[Any], Any]]]
    on_pool_destroy: NotRequired[list[Callable[[Any], None]]]
    on_session_start: NotRequired[list[Callable[[Any], None]]]
    on_session_end: NotRequired[list[Callable[[Any], None]]]
    on_query_start: NotRequired[list[Callable[[str, dict[str, Any]], None]]]
    on_query_complete: NotRequired[list[Callable[[str, dict[str, Any], Any], None]]]
    on_error: NotRequired[list[Callable[[Exception, str, dict[str, Any]], None]]]

[docs]

class MigrationConfig(TypedDict): """Configuration options for database migrations. All fields are optional with default values. """ script_location: NotRequired["str | Path"] """Path to the migrations directory. Accepts string or Path object. Defaults to 'migrations'.""" version_table_name: NotRequired[str] """Name of the table used to track applied migrations. Defaults to 'sqlspec_migrations'.""" default_schema: NotRequired[str] """Schema applied to migration sessions before user migration SQL runs, when supported by the adapter.""" version_table_schema: NotRequired[str] """Schema that stores the migration tracking table. Defaults to default_schema when omitted.""" project_root: NotRequired[str] """Path to the project root directory. Used for relative path resolution.""" enabled: NotRequired[bool] """Whether this configuration should be included in CLI operations. Defaults to True.""" auto_sync: NotRequired[bool] """Enable automatic version reconciliation during upgrade. When enabled (default), SQLSpec automatically updates database tracking when migrations are renamed from timestamp to sequential format. Defaults to True.""" strict_ordering: NotRequired[bool] """Enforce strict migration ordering. When enabled, prevents out-of-order migrations from being applied. Defaults to False.""" include_extensions: NotRequired["list[str]"] """List of extension names whose migrations should be included. Extension migrations maintain separate versioning and are prefixed with 'ext_{name}_'. Note: Extensions with migration support (litestar, adk, events) are auto-included when their settings are present in ``extension_config``. Use ``exclude_extensions`` to opt out. """ exclude_extensions: NotRequired["list[str]"] """ List of extension names to exclude from automatic migration inclusion. When an extension is configured in ``extension_config``, its migrations are automatically included. Use this to prevent that for specific extensions: """ transactional: NotRequired[bool] """Wrap migrations in transactions when supported. When enabled (default for adapters that support it), each migration runs in a transaction that is committed on success or rolled back on failure. This prevents partial migrations from leaving the database in an inconsistent state. Requires adapter support for transactional DDL. Defaults to True for PostgreSQL, SQLite, and DuckDB; False for MySQL, Oracle, and BigQuery. Individual migrations can override this with a '-- transactional: false' comment.""" use_logger: NotRequired[bool] """ Use Python logger instead of Rich console for migration output. When True, migration progress is logged via structlog/logging instead of being printed to the console with Rich formatting. This is useful for programmatic usage where console output is not desired. Can be overridden per-call via the ``use_logger`` parameter on ``migrate_up()`` and ``migrate_down()`` methods. Defaults to False (Rich console output). """ echo: NotRequired[bool] """Echo migration output to the console. When False, console output is suppressed. This is useful for script or CI environments that need quiet stdout. Defaults to True. """ summary_only: NotRequired[bool] """Emit a single summary log entry for migration commands. When True and ``use_logger`` is enabled, per-migration output is suppressed in favor of a single structured summary log event. Defaults to False. """

class FlaskConfig(TypedDict): """Configuration options for Flask SQLSpec extension. All fields are optional with sensible defaults. Use in extension_config["flask"]: """ connection_key: NotRequired[str] """Key for storing connection in Flask g object. Default: auto-generated from session_key.""" session_key: NotRequired[str] """Key for accessing session via plugin.get_session(). Default: 'db_session'.""" commit_mode: NotRequired[Literal["manual", "autocommit", "autocommit_include_redirect"]] """Transaction commit mode. Default: 'manual'. - manual: No automatic commits, user handles explicitly - autocommit: Commits on 2xx status, rollback otherwise - autocommit_include_redirect: Commits on 2xx-3xx status, rollback otherwise """ extra_commit_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger commit. Default: None.""" extra_rollback_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger rollback. Default: None.""" disable_di: NotRequired[bool] """Disable built-in dependency injection. Default: False. When True, the Flask extension will not register request hooks for managing database connections and sessions. Users are responsible for managing the database lifecycle manually via their own DI solution. """ enable_sqlcommenter_middleware: NotRequired[bool] """Control automatic SQLCommenter context population. Default: True. When the driver's :class:`~sqlspec.core.statement.StatementConfig` has ``enable_sqlcommenter=True``, request attributes are populated automatically. Set to ``False`` to explicitly disable this behavior. """ class LitestarConfig(TypedDict): """Configuration options for Litestar SQLSpec plugin. All fields are optional with sensible defaults. """ session_table: NotRequired["bool | str"] """Enable session table for server-side session storage. - ``True``: Use default table name ('litestar_session') - ``"custom_name"``: Use custom table name When set, litestar extension migrations are auto-included to create the session table. If you're only using litestar for DI/connection management (not session storage), leave this unset to skip the migrations. """ connection_key: NotRequired[str] """Key for storing connection in ASGI scope. Default: 'db_connection'""" pool_key: NotRequired[str] """Key for storing connection pool in application state. Default: 'db_pool'""" session_key: NotRequired[str] """Key for storing session in ASGI scope. Default: 'db_session'""" commit_mode: NotRequired[Literal["manual", "autocommit", "autocommit_include_redirect"]] """Transaction commit mode. Default: 'manual'""" enable_correlation_middleware: NotRequired[bool] """Enable request correlation ID middleware. Default: True""" correlation_header: NotRequired[str] """HTTP header to read the request correlation ID from when middleware is enabled. Default: ``X-Request-ID``""" extra_commit_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger commit. Default: set()""" extra_rollback_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger rollback. Default: set()""" disable_di: NotRequired[bool] """Disable built-in dependency injection. Default: False. When True, the Litestar plugin will not register dependency providers for managing database connections, pools, and sessions. Users are responsible for managing the database lifecycle manually via their own DI solution. """ enable_sqlcommenter_middleware: NotRequired[bool] """Control automatic SQLCommenter middleware registration. Default: True. When the driver's :class:`~sqlspec.core.statement.StatementConfig` has ``enable_sqlcommenter=True``, the middleware is registered automatically. Set to ``False`` to explicitly disable middleware registration even when SQLCommenter is enabled on the driver config. """ class StarletteConfig(TypedDict): """Configuration options for Starlette SQLSpec extension. All fields are optional with sensible defaults. Use in extension_config["starlette"]: """ connection_key: NotRequired[str] """Key for storing connection in request.state. Default: 'db_connection'""" pool_key: NotRequired[str] """Key for storing connection pool in app.state. Default: 'db_pool'""" session_key: NotRequired[str] """Key for storing session in request.state. Default: 'db_session'""" commit_mode: NotRequired[Literal["manual", "autocommit", "autocommit_include_redirect"]] """Transaction commit mode. Default: 'manual' - manual: No automatic commit/rollback - autocommit: Commit on 2xx, rollback otherwise - autocommit_include_redirect: Commit on 2xx-3xx, rollback otherwise """ extra_commit_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger commit. Default: set()""" extra_rollback_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger rollback. Default: set()""" disable_di: NotRequired[bool] """Disable built-in dependency injection. Default: False. When True, the Starlette/FastAPI extension will not add middleware for managing database connections and sessions. Users are responsible for managing the database lifecycle manually via their own DI solution. """ enable_sqlcommenter_middleware: NotRequired[bool] """Control automatic SQLCommenter middleware registration. Default: True. When the driver's :class:`~sqlspec.core.statement.StatementConfig` has ``enable_sqlcommenter=True``, the middleware is registered automatically. Set to ``False`` to explicitly disable middleware registration. """ sqlcommenter_framework: NotRequired[str] """Framework name for SQLCommenter attributes. Default: 'starlette'. Set to 'fastapi' when using FastAPI. """ class FastAPIConfig(StarletteConfig): """Configuration options for FastAPI SQLSpec extension. All fields are optional with sensible defaults. Use in ``extension_config["fastapi"]``. SQLCommenter defaults the framework attribute to ``"fastapi"``. """ class SanicConfig(TypedDict): """Configuration options for Sanic SQLSpec extension. All fields are optional with sensible defaults. Use in ``extension_config["sanic"]``. """ connection_key: NotRequired[str] """Key for storing connection in request.ctx. Default: 'db_connection'""" pool_key: NotRequired[str] """Key for storing connection pool in app.ctx. Default: 'db_pool'""" session_key: NotRequired[str] """Key for storing session in request.ctx. Default: 'db_session'""" commit_mode: NotRequired[Literal["manual", "autocommit", "autocommit_include_redirect"]] """Transaction commit mode. Default: 'manual' - manual: No automatic commit/rollback - autocommit: Commit on 2xx, rollback otherwise - autocommit_include_redirect: Commit on 2xx-3xx, rollback otherwise """ extra_commit_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger commit. Default: set()""" extra_rollback_statuses: NotRequired[set[int]] """Additional HTTP status codes that trigger rollback. Default: set()""" disable_di: NotRequired[bool] """Disable built-in dependency injection. Default: False. When True, the Sanic extension will not register request middleware for managing database connections and sessions. Users are responsible for managing the database lifecycle manually via their own DI solution. """ enable_correlation_middleware: NotRequired[bool] """Enable request correlation ID middleware. Default: False.""" correlation_header: NotRequired[str] """HTTP header to read the request correlation ID from when middleware is enabled. Default: ``X-Request-ID``.""" correlation_headers: NotRequired[tuple[str, ...] | list[str]] """Additional HTTP headers to read as correlation ID fallbacks.""" auto_trace_headers: NotRequired[bool] """Read standard trace context headers as correlation ID fallbacks. Default: True.""" enable_sqlcommenter_middleware: NotRequired[bool] """Control automatic SQLCommenter middleware registration. Default: True. When the driver's :class:`~sqlspec.core.statement.StatementConfig` has ``enable_sqlcommenter=True``, the middleware is registered automatically. Set to ``False`` to explicitly disable middleware registration. """ sqlcommenter_framework: NotRequired[str] """Framework name for SQLCommenter attributes. Default: 'sanic'.""" class ADKPartitionConfig(TypedDict): """Configuration for table partitioning and sharding strategies. Controls how ADK tables are partitioned across backends that support it. Backends without native partitioning support ignore these settings. """ strategy: NotRequired[Literal["range", "list", "hash"]] """ Partitioning strategy. Default: None (no partitioning). - range: Partition by range of values - list: Partition by discrete value lists - hash: Partition by hash of the partition key Supported by: PostgreSQL, MySQL 8+, Oracle, Spanner. Ignored by: SQLite, DuckDB. """ partition_key: NotRequired[str] """Column name used as the partition key. For range partitioning with time-based data, this is typically a timestamp column like 'created_at'. For hash partitioning, this is typically the primary key. """ session_partition_key: NotRequired[str] """Session-table partition key override for adapters that create separate ADK tables.""" events_partition_key: NotRequired[str] """Event-table partition key override for adapters that create separate ADK tables.""" memory_partition_key: NotRequired[str] """Memory-table partition key override for adapters that create separate ADK tables.""" interval: NotRequired[str] """Partition interval for range partitioning. Only meaningful when strategy is 'range'. """ partition_count: NotRequired[int] """Number of hash partitions for adapters that support hash-partitioned ADK tables.""" initial_less_than: NotRequired[str] """Initial range-partition upper bound for adapters that require a seed partition.""" class ADKRetentionConfig(TypedDict): """Configuration for data retention and TTL policies. Controls automatic cleanup of expired data. Backends with native TTL support (CockroachDB Row-Level TTL, Spanner Row Deletion Policy) use database-level enforcement. Others fall back to application-level sweep queries. """ session_ttl_seconds: NotRequired[int] """TTL for session records in seconds. Default: 0 (no expiry). When set, sessions older than this threshold are eligible for cleanup. Backends with native TTL (CockroachDB, Spanner) enforce this at the database level. Others require application-level cleanup via periodic sweep. """ event_ttl_seconds: NotRequired[int] """TTL for event records in seconds. Default: 0 (no expiry). When set, events older than this threshold are eligible for cleanup. """ memory_ttl_seconds: NotRequired[int] """TTL for memory entries in seconds. Default: 0 (no expiry). When set, memory entries older than this threshold are eligible for cleanup. """ sweep_interval_seconds: NotRequired[int] """Interval between application-level cleanup sweeps in seconds. Default: 3600 (1 hour). Only used when the backend does not support native TTL enforcement. Set to 0 to disable automatic sweeps (manual cleanup only). """ class ADKCompressionConfig(TypedDict): """Configuration for table-level compression. Controls compression of ADK table storage. Support and algorithms vary by backend. """ enabled: NotRequired[bool] """Enable table compression. Default: False. When True, adapters that support table-level compression will apply it during table creation. """ algorithm: NotRequired[str] """ Compression algorithm name. Backend-specific. When omitted, the backend default is used. """ level: NotRequired[int] """Compression level (where supported). Higher levels trade CPU for space savings. Valid ranges depend on the algorithm and backend. """ class ADKSqliteOptimizationConfig(TypedDict): """SQLite-specific PRAGMA optimization settings. Controls SQLite performance tuning parameters applied at connection time. These settings are ignored by non-SQLite adapters. """ cache_size: NotRequired[int] """SQLite page cache size. Default: -64000 (64 MB, negative means KiB). Larger caches reduce disk I/O for read-heavy workloads. Negative values specify size in KiB; positive values specify page count. """ mmap_size: NotRequired[int] """SQLite memory-mapped I/O size in bytes. Default: 31457280 (30 MB). Enables memory-mapped I/O for faster reads. Set to 0 to disable. """ journal_size_limit: NotRequired[int] """SQLite journal file size limit in bytes. Default: 67108864 (64 MB). Limits the size of the WAL or rollback journal file. Prevents unbounded journal growth in write-heavy workloads. """

[docs]

class ADKConfig(TypedDict): """Configuration options for ADK session and memory store extension. All fields are optional with sensible defaults. Use in extension_config["adk"]: Configuration supports three deployment scenarios: 1. SQLSpec manages everything (runtime + migrations) 2. SQLSpec runtime only (external migration tools like Alembic/Flyway) 3. Selective features (sessions OR memory, not both) """ enable_sessions: NotRequired[bool] """Enable session store at runtime. Default: True. When False: session service unavailable, session store operations disabled. Independent of migration control - can use externally-managed tables. """ enable_memory: NotRequired[bool] """Enable memory store at runtime. Default: True. When False: memory service unavailable, memory store operations disabled. Independent of migration control - can use externally-managed tables. """ include_sessions_migration: NotRequired[bool] """Include session tables in SQLSpec migrations. Default: True. When False: session migration DDL skipped (use external migration tools). Decoupled from enable_sessions - allows external table management with SQLSpec runtime. """ include_memory_migration: NotRequired[bool] """Include memory tables in SQLSpec migrations. Default: True. When False: memory migration DDL skipped (use external migration tools). Decoupled from enable_memory - allows external table management with SQLSpec runtime. """ session_table: NotRequired[str] """Name of the sessions table. Default: 'adk_sessions'""" events_table: NotRequired[str] """Name of the events table. Default: 'adk_events'""" memory_table: NotRequired[str] """Name of the memory entries table. Default: 'adk_memory_entries'""" artifact_table: NotRequired[str] """Name of the artifact versions table. Default: 'adk_artifact_versions'""" artifact_storage_uri: NotRequired[str] """ Base URI for artifact content storage. Points to a ``sqlspec/storage/`` backend where artifact binary content is stored. Can be a direct URI (``s3://bucket/path``, ``file:///path``) or a registered alias in the storage registry. """ memory_use_fts: NotRequired[bool] """Enable full-text search when supported. Default: False. When True, adapters will use their native FTS capabilities where available: - PostgreSQL: to_tsvector/to_tsquery with GIN index - SQLite: FTS5 virtual table - DuckDB: FTS extension with match_bm25 - Oracle: CONTAINS() with CTXSYS.CONTEXT index - Spanner: TOKENIZE_FULLTEXT with search index - MySQL: MATCH...AGAINST with FULLTEXT index When False, adapters use simple LIKE/ILIKE queries (works without indexes). """ memory_max_results: NotRequired[int] """Maximum number of results for memory search queries. Default: 20. Limits the number of memory entries returned by search_memory(). Can be overridden per-query via the limit parameter. """ owner_id_column: NotRequired[str] """ Optional owner ID column definition to link sessions/memories to a user, tenant, team, or other entity. Format: "column_name TYPE [NOT NULL] REFERENCES table(column) [options...]" The entire definition is passed through to DDL verbatim. We only parse the column name (first word) for use in INSERT/SELECT statements. This column is added to both session and memory tables for consistent multi-tenant isolation. Supports: - Foreign key constraints: REFERENCES table(column) - Nullable or NOT NULL - CASCADE options: ON DELETE CASCADE, ON UPDATE CASCADE - Dialect-specific options (DEFERRABLE, ENABLE VALIDATE, etc.) - Plain columns without FK (just extra column storage) """ in_memory: NotRequired[bool] """ Enable in-memory table storage (Oracle-specific). Default: False. When enabled, tables are created with the INMEMORY clause for Oracle Database, which stores table data in columnar format in memory for faster query performance. This is an Oracle-specific feature that requires: - Oracle Database 12.1.0.2 or higher - Database In-Memory option license (Enterprise Edition) - Sufficient INMEMORY_SIZE configured in the database instance Other database adapters ignore this setting. """ shard_count: NotRequired[int] """Optional hash shard count for session/event tables to reduce hotspotting. When set (>1), adapters that support computed shard columns will create a generated shard_id using MOD(FARM_FINGERPRINT(primary_key), shard_count) and include it in the primary key and filters. Ignored by adapters that do not support computed shards. """ session_table_options: NotRequired[str] """ Adapter-specific table OPTIONS/clauses for the sessions table. Passed verbatim when supported. Ignored by adapters without table OPTIONS support. """ events_table_options: NotRequired[str] """Adapter-specific table OPTIONS/clauses for the events table.""" memory_table_options: NotRequired[str] """Adapter-specific table OPTIONS/clauses for the memory table.""" expires_index_options: NotRequired[str] """Adapter-specific options for the expires/index used in ADK stores.""" # --- Capability-based configuration (Chapter 2: schema-capability-config) --- fts_language: NotRequired[str] """ Language configuration for full-text search indexing. Default: 'english'. Controls the language dictionary/stemmer for FTS implementations: - PostgreSQL: to_tsvector/to_tsquery language parameter - SQLite FTS5: tokenizer language for unicode61/porter - MySQL: FULLTEXT parser language (with ngram for CJK on 5.7.6+) - Oracle: CTXSYS.CONTEXT lexer language - Spanner: TOKENIZE_FULLTEXT language parameter - DuckDB: FTS stemmer language Only takes effect when ``memory_use_fts`` is True. Common values: 'english', 'simple', 'german', 'french', 'spanish', 'portuguese', 'italian', 'dutch', 'russian', 'chinese', 'japanese', 'korean'. """ schema_version: NotRequired[int] """ Explicit schema version for ADK tables. Default: None (auto-detect). When set, locks the ADK schema to a specific version. This is useful for: - Preventing automatic schema upgrades in production - Pinning to a known-good schema during testing - Coordinating schema changes across multiple application instances When None, the ADK extension auto-detects the current schema version and applies any pending upgrades during initialization. """ partitioning: NotRequired[ADKPartitionConfig] """Table partitioning configuration. Default: None (no partitioning). Controls how ADK tables are partitioned for improved query performance and data management at scale. See ``ADKPartitionConfig`` for options. Supported by: PostgreSQL, MySQL 8+, Oracle, Spanner. Ignored by: SQLite, DuckDB. """ retention: NotRequired[ADKRetentionConfig] """Data retention and TTL configuration. Default: None (no automatic cleanup). Controls automatic expiry and cleanup of old session, event, and memory data. See ``ADKRetentionConfig`` for options. Backends with native TTL (CockroachDB, Spanner) use database-level enforcement. Others fall back to application-level sweep queries. """ compression: NotRequired[ADKCompressionConfig] """Table compression configuration. Default: None (no compression). Controls table-level compression for ADK tables. See ``ADKCompressionConfig`` for options. """ sqlite_optimization: NotRequired[ADKSqliteOptimizationConfig] """SQLite-specific PRAGMA optimization settings. Default: None (SQLite defaults). Controls SQLite performance tuning parameters. Ignored by non-SQLite adapters. See ``ADKSqliteOptimizationConfig`` for options. """

[docs]

class EventsConfig(TypedDict): """Configuration options for the events extension. Use in ``extension_config["events"]``. """ backend: NotRequired[Literal["listen_notify", "table_queue", "listen_notify_durable", "advanced_queue"]] """Backend implementation. PostgreSQL adapters default to 'listen_notify', others to 'table_queue'. - listen_notify: Real-time PostgreSQL LISTEN/NOTIFY (ephemeral) - table_queue: Durable table-backed queue with retries (all adapters) - listen_notify_durable: Hybrid combining both (PostgreSQL only) - advanced_queue: Oracle Advanced Queueing """ queue_table: NotRequired[str] """Name of the fallback queue table. Defaults to 'sqlspec_event_queue'.""" lease_seconds: NotRequired[int] """Lease duration for claimed events before they can be retried. Defaults to 30 seconds.""" retention_seconds: NotRequired[int] """Retention window for acknowledged events before cleanup. Defaults to 86400 (24 hours).""" poll_interval: NotRequired[float] """Default poll interval in seconds for event consumers. Defaults to 1.0.""" select_for_update: NotRequired[bool] """Use SELECT FOR UPDATE locking when claiming events. Defaults to False.""" skip_locked: NotRequired[bool] """Use SKIP LOCKED for non-blocking event claims. Defaults to False.""" json_passthrough: NotRequired[bool] """Skip JSON encoding/decoding for payloads. Defaults to False.""" in_memory: NotRequired[bool] """ Enable Oracle INMEMORY clause for the queue table. Ignored by other adapters. Defaults to False. Note: To skip events migrations, use ``migration_config={"exclude_extensions": ["events"]}``. """