sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/config.py

@@ -1,5 +1,7 @@
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generic, Optional, TypeVar, Union
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeVar, cast
 
 from typing_extensions import NotRequired, TypedDict
 
@@ -11,20 +13,21 @@ from sqlspec.utils.logging import get_logger
 if TYPE_CHECKING:
     from collections.abc import Awaitable
     from contextlib import AbstractAsyncContextManager, AbstractContextManager
-    from pathlib import Path
 
     from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
     from sqlspec.loader import SQLFileLoader
-    from sqlspec.migrations.commands import MigrationCommands
+    from sqlspec.migrations.commands import AsyncMigrationCommands, SyncMigrationCommands
 
 
 __all__ = (
+    "ADKConfig",
     "AsyncConfigT",
     "AsyncDatabaseConfig",
     "ConfigT",
     "DatabaseConfigProtocol",
     "DriverT",
     "LifecycleConfig",
+    "LitestarConfig",
     "MigrationConfig",
     "NoPoolAsyncConfig",
     "NoPoolSyncConfig",
@@ -32,22 +35,22 @@ __all__ = (
     "SyncDatabaseConfig",
 )
 
-AsyncConfigT = TypeVar("AsyncConfigT", bound="Union[AsyncDatabaseConfig[Any, Any, Any], NoPoolAsyncConfig[Any, Any]]")
-SyncConfigT = TypeVar("SyncConfigT", bound="Union[SyncDatabaseConfig[Any, Any, Any], NoPoolSyncConfig[Any, Any]]")
+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="Union[Union[AsyncDatabaseConfig[Any, Any, Any], NoPoolAsyncConfig[Any, Any]], SyncDatabaseConfig[Any, Any, Any], NoPoolSyncConfig[Any, Any]]",
+    bound="AsyncDatabaseConfig[Any, Any, Any] | NoPoolAsyncConfig[Any, Any] | SyncDatabaseConfig[Any, Any, Any] | NoPoolSyncConfig[Any, Any]",
 )
 
 # Define TypeVars for Generic classes
 ConnectionT = TypeVar("ConnectionT")
 PoolT = TypeVar("PoolT")
-DriverT = TypeVar("DriverT", bound="Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]")
+DriverT = TypeVar("DriverT", bound="SyncDriverAdapterBase | AsyncDriverAdapterBase")
 
 logger = get_logger("config")
 
 
-class LifecycleConfig(TypedDict, total=False):
+class LifecycleConfig(TypedDict):
     """Lifecycle hooks for database adapters.
 
     Each hook accepts a list of callables to support multiple handlers.
@@ -64,14 +67,14 @@ class LifecycleConfig(TypedDict, total=False):
     on_error: NotRequired[list[Callable[[Exception, str, dict], None]]]
 
 
-class MigrationConfig(TypedDict, total=False):
+class MigrationConfig(TypedDict):
     """Configuration options for database migrations.
 
     All fields are optional with default values.
     """
 
-    script_location: NotRequired[str]
-    """Path to the migrations directory. Defaults to 'migrations'."""
+    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'."""
@@ -82,6 +85,164 @@ class MigrationConfig(TypedDict, total=False):
     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}_'."""
+
+    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."""
+
+
+class LitestarConfig(TypedDict):
+    """Configuration options for Litestar SQLSpec plugin.
+
+    All fields are optional with sensible defaults.
+    """
+
+    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"""
+
+    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()"""
+
+
+class ADKConfig(TypedDict):
+    """Configuration options for ADK session store extension.
+
+    All fields are optional with sensible defaults. Use in extension_config["adk"]:
+
+    Example:
+        from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+        config = AsyncpgConfig(
+            pool_config={"dsn": "postgresql://localhost/mydb"},
+            extension_config={
+                "adk": {
+                    "session_table": "my_sessions",
+                    "events_table": "my_events",
+                    "owner_id_column": "tenant_id INTEGER REFERENCES tenants(id)"
+                }
+            }
+        )
+
+    Notes:
+        This TypedDict provides type safety for extension config but is not required.
+        You can use plain dicts as well.
+    """
+
+    session_table: NotRequired[str]
+    """Name of the sessions table. Default: 'adk_sessions'
+
+    Examples:
+        "agent_sessions"
+        "my_app_sessions"
+        "tenant_acme_sessions"
+    """
+
+    events_table: NotRequired[str]
+    """Name of the events table. Default: 'adk_events'
+
+    Examples:
+        "agent_events"
+        "my_app_events"
+        "tenant_acme_events"
+    """
+
+    owner_id_column: NotRequired[str]
+    """Optional owner ID column definition to link sessions 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.
+
+    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)
+
+    Examples:
+        PostgreSQL with UUID FK:
+            "account_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE"
+
+        MySQL with BIGINT FK:
+            "user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE RESTRICT"
+
+        Oracle with NUMBER FK:
+            "user_id NUMBER(10) REFERENCES users(id) ENABLE VALIDATE"
+
+        SQLite with INTEGER FK:
+            "tenant_id INTEGER NOT NULL REFERENCES tenants(id)"
+
+        Nullable FK (optional relationship):
+            "workspace_id UUID REFERENCES workspaces(id) ON DELETE SET NULL"
+
+        No FK (just extra column):
+            "organization_name VARCHAR(128) NOT NULL"
+
+        Deferred constraint (PostgreSQL):
+            "user_id UUID REFERENCES users(id) DEFERRABLE INITIALLY DEFERRED"
+
+    Notes:
+        - Column name (first word) is extracted for INSERT/SELECT queries
+        - Rest of definition is passed through to CREATE TABLE DDL
+        - Database validates the DDL syntax (fail-fast on errors)
+        - Works with all database dialects (PostgreSQL, MySQL, SQLite, Oracle, etc.)
+    """
+
+    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.
+
+    Examples:
+        Oracle with in-memory enabled:
+            config = OracleAsyncConfig(
+                pool_config={"dsn": "oracle://..."},
+                extension_config={
+                    "adk": {
+                        "in_memory": True
+                    }
+                }
+            )
+
+    Notes:
+        - Improves query performance for analytics (10-100x faster)
+        - Tables created with INMEMORY clause
+        - Requires Oracle Database In-Memory option license
+        - Ignored by non-Oracle adapters
+    """
+
 
 class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     """Protocol defining the interface for database configurations."""
@@ -89,6 +250,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     __slots__ = (
         "_migration_commands",
         "_migration_loader",
+        "bind_key",
         "driver_features",
         "migration_config",
         "pool_instance",
@@ -96,18 +258,21 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     )
 
     _migration_loader: "SQLFileLoader"
-    _migration_commands: "MigrationCommands"
+    _migration_commands: "SyncMigrationCommands | AsyncMigrationCommands"
     driver_type: "ClassVar[type[Any]]"
     connection_type: "ClassVar[type[Any]]"
     is_async: "ClassVar[bool]" = False
     supports_connection_pooling: "ClassVar[bool]" = False
+    supports_transactional_ddl: "ClassVar[bool]" = False
     supports_native_arrow_import: "ClassVar[bool]" = False
     supports_native_arrow_export: "ClassVar[bool]" = False
     supports_native_parquet_import: "ClassVar[bool]" = False
     supports_native_parquet_export: "ClassVar[bool]" = False
+    bind_key: "str | None"
     statement_config: "StatementConfig"
-    pool_instance: "Optional[PoolT]"
-    migration_config: "Union[dict[str, Any], MigrationConfig]"
+    pool_instance: "PoolT | None"
+    migration_config: "dict[str, Any] | MigrationConfig"
+    driver_features: "dict[str, Any]"
 
     def __hash__(self) -> int:
         return id(self)
@@ -122,38 +287,38 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         return f"{type(self).__name__}({parts})"
 
     @abstractmethod
-    def create_connection(self) -> "Union[ConnectionT, Awaitable[ConnectionT]]":
+    def create_connection(self) -> "ConnectionT | Awaitable[ConnectionT]":
         """Create and return a new database connection."""
         raise NotImplementedError
 
     @abstractmethod
     def provide_connection(
         self, *args: Any, **kwargs: Any
-    ) -> "Union[AbstractContextManager[ConnectionT], AbstractAsyncContextManager[ConnectionT]]":
+    ) -> "AbstractContextManager[ConnectionT] | AbstractAsyncContextManager[ConnectionT]":
         """Provide a database connection context manager."""
         raise NotImplementedError
 
     @abstractmethod
     def provide_session(
         self, *args: Any, **kwargs: Any
-    ) -> "Union[AbstractContextManager[DriverT], AbstractAsyncContextManager[DriverT]]":
+    ) -> "AbstractContextManager[DriverT] | AbstractAsyncContextManager[DriverT]":
         """Provide a database session context manager."""
         raise NotImplementedError
 
     @abstractmethod
-    def create_pool(self) -> "Union[PoolT, Awaitable[PoolT]]":
+    def create_pool(self) -> "PoolT | Awaitable[PoolT]":
         """Create and return connection pool."""
         raise NotImplementedError
 
     @abstractmethod
-    def close_pool(self) -> "Optional[Awaitable[None]]":
+    def close_pool(self) -> "Awaitable[None] | None":
         """Terminate the connection pool."""
         raise NotImplementedError
 
     @abstractmethod
     def provide_pool(
         self, *args: Any, **kwargs: Any
-    ) -> "Union[PoolT, Awaitable[PoolT], AbstractContextManager[PoolT], AbstractAsyncContextManager[PoolT]]":
+    ) -> "PoolT | Awaitable[PoolT] | AbstractContextManager[PoolT] | AbstractAsyncContextManager[PoolT]":
         """Provide pool instance."""
         raise NotImplementedError
 
@@ -176,10 +341,10 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         at runtime when needed.
         """
         from sqlspec.loader import SQLFileLoader
-        from sqlspec.migrations.commands import MigrationCommands
+        from sqlspec.migrations.commands import create_migration_commands
 
         self._migration_loader = SQLFileLoader()
-        self._migration_commands = MigrationCommands(self)  # type: ignore[arg-type]
+        self._migration_commands = create_migration_commands(self)  # pyright: ignore
 
     def _ensure_migration_loader(self) -> "SQLFileLoader":
         """Get the migration SQL loader and auto-load files if needed.
@@ -200,7 +365,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 
         return self._migration_loader
 
-    def _ensure_migration_commands(self) -> "MigrationCommands":
+    def _ensure_migration_commands(self) -> "SyncMigrationCommands | AsyncMigrationCommands":
         """Get the migration commands instance.
 
         Returns:
@@ -219,13 +384,12 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """
         return self._ensure_migration_loader()
 
-    def load_migration_sql_files(self, *paths: "Union[str, Path]") -> None:
+    def load_migration_sql_files(self, *paths: "str | Path") -> None:
         """Load additional migration SQL files from specified paths.
 
         Args:
             *paths: One or more file paths or directory paths to load migration SQL files from.
         """
-        from pathlib import Path
 
         loader = self._ensure_migration_loader()
         for path in paths:
@@ -236,7 +400,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
             else:
                 logger.warning("Migration path does not exist: %s", path_obj)
 
-    def get_migration_commands(self) -> "MigrationCommands":
+    def get_migration_commands(self) -> "SyncMigrationCommands | AsyncMigrationCommands":
         """Get migration commands for this configuration.
 
         Returns:
@@ -244,25 +408,27 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """
         return self._ensure_migration_commands()
 
-    def migrate_up(self, revision: str = "head") -> None:
+    async def migrate_up(self, revision: str = "head") -> None:
         """Apply migrations up to the specified revision.
 
         Args:
             revision: Target revision or "head" for latest. Defaults to "head".
         """
         commands = self._ensure_migration_commands()
-        commands.upgrade(revision)
 
-    def migrate_down(self, revision: str = "-1") -> None:
+        await cast("AsyncMigrationCommands", commands).upgrade(revision)
+
+    async def migrate_down(self, revision: str = "-1") -> None:
         """Apply migrations down to the specified revision.
 
         Args:
             revision: Target revision, "-1" for one step back, or "base" for all migrations. Defaults to "-1".
         """
         commands = self._ensure_migration_commands()
-        commands.downgrade(revision)
 
-    def get_current_migration(self, verbose: bool = False) -> "Optional[str]":
+        await cast("AsyncMigrationCommands", commands).downgrade(revision)
+
+    async def get_current_migration(self, verbose: bool = False) -> "str | None":
         """Get the current migration version.
 
         Args:
@@ -272,9 +438,10 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
             Current migration version or None if no migrations applied.
         """
         commands = self._ensure_migration_commands()
-        return commands.current(verbose=verbose)
 
-    def create_migration(self, message: str, file_type: str = "sql") -> None:
+        return await cast("AsyncMigrationCommands", commands).current(verbose=verbose)
+
+    async def create_migration(self, message: str, file_type: str = "sql") -> None:
         """Create a new migration file.
 
         Args:
@@ -282,9 +449,10 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
             file_type: Type of migration file to create ('sql' or 'py'). Defaults to 'sql'.
         """
         commands = self._ensure_migration_commands()
-        commands.revision(message, file_type)
 
-    def init_migrations(self, directory: "Optional[str]" = None, package: bool = True) -> None:
+        await cast("AsyncMigrationCommands", commands).revision(message, file_type)
+
+    async def init_migrations(self, directory: "str | None" = None, package: bool = True) -> None:
         """Initialize migration directory structure.
 
         Args:
@@ -293,17 +461,18 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """
         if directory is None:
             migration_config = self.migration_config or {}
-            directory = migration_config.get("script_location") or "migrations"
+            directory = str(migration_config.get("script_location") or "migrations")
 
         commands = self._ensure_migration_commands()
         assert directory is not None
-        commands.init(directory, package)
+
+        await cast("AsyncMigrationCommands", commands).init(directory, package)
 
 
 class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     """Base class for sync database configurations that do not implement a pool."""
 
-    __slots__ = ("connection_config",)
+    __slots__ = ("connection_config", "extension_config")
     is_async: "ClassVar[bool]" = False
     supports_connection_pooling: "ClassVar[bool]" = False
     migration_tracker_type: "ClassVar[type[Any]]" = SyncMigrationTracker
@@ -311,14 +480,18 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     def __init__(
         self,
         *,
-        connection_config: Optional[dict[str, Any]] = None,
-        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        connection_config: dict[str, Any] | None = None,
+        migration_config: "dict[str, Any] | MigrationConfig | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
+        self.bind_key = bind_key
         self.pool_instance = None
         self.connection_config = connection_config or {}
-        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self.extension_config: dict[str, dict[str, Any]] = extension_config or {}
+        self.migration_config: dict[str, Any] | MigrationConfig = migration_config or {}
         self._initialize_migration_components()
 
         if statement_config is None:
@@ -339,7 +512,7 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
         raise NotImplementedError
 
     def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "AbstractContextManager[DriverT]":
         """Provide a database session context manager."""
         raise NotImplementedError
@@ -357,7 +530,7 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     """Base class for async database configurations that do not implement a pool."""
 
-    __slots__ = ("connection_config",)
+    __slots__ = ("connection_config", "extension_config")
     is_async: "ClassVar[bool]" = True
     supports_connection_pooling: "ClassVar[bool]" = False
     migration_tracker_type: "ClassVar[type[Any]]" = AsyncMigrationTracker
@@ -365,14 +538,18 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     def __init__(
         self,
         *,
-        connection_config: "Optional[dict[str, Any]]" = None,
-        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        connection_config: "dict[str, Any] | None" = None,
+        migration_config: "dict[str, Any] | MigrationConfig | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
+        self.bind_key = bind_key
         self.pool_instance = None
         self.connection_config = connection_config or {}
-        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self.extension_config: dict[str, dict[str, Any]] = extension_config or {}
+        self.migration_config: dict[str, Any] | MigrationConfig = migration_config or {}
         self._initialize_migration_components()
 
         if statement_config is None:
@@ -393,7 +570,7 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
         raise NotImplementedError
 
     def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "AbstractAsyncContextManager[DriverT]":
         """Provide a database session context manager."""
         raise NotImplementedError
@@ -411,7 +588,7 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     """Base class for sync database configurations with connection pooling."""
 
-    __slots__ = ("pool_config",)
+    __slots__ = ("extension_config", "pool_config")
     is_async: "ClassVar[bool]" = False
     supports_connection_pooling: "ClassVar[bool]" = True
     migration_tracker_type: "ClassVar[type[Any]]" = SyncMigrationTracker
@@ -419,15 +596,19 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     def __init__(
         self,
         *,
-        pool_config: "Optional[dict[str, Any]]" = None,
-        pool_instance: "Optional[PoolT]" = None,
-        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        pool_config: "dict[str, Any] | None" = None,
+        pool_instance: "PoolT | None" = None,
+        migration_config: "dict[str, Any] | MigrationConfig | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
+        self.bind_key = bind_key
         self.pool_instance = pool_instance
         self.pool_config = pool_config or {}
-        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self.extension_config: dict[str, dict[str, Any]] = extension_config or {}
+        self.migration_config: dict[str, Any] | MigrationConfig = migration_config or {}
         self._initialize_migration_components()
 
         if statement_config is None:
@@ -469,7 +650,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
         raise NotImplementedError
 
     def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "AbstractContextManager[DriverT]":
         """Provide a database session context manager."""
         raise NotImplementedError
@@ -488,7 +669,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
 class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     """Base class for async database configurations with connection pooling."""
 
-    __slots__ = ("pool_config",)
+    __slots__ = ("extension_config", "pool_config")
     is_async: "ClassVar[bool]" = True
     supports_connection_pooling: "ClassVar[bool]" = True
     migration_tracker_type: "ClassVar[type[Any]]" = AsyncMigrationTracker
@@ -496,15 +677,19 @@ class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     def __init__(
         self,
         *,
-        pool_config: "Optional[dict[str, Any]]" = None,
-        pool_instance: "Optional[PoolT]" = None,
-        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        pool_config: "dict[str, Any] | None" = None,
+        pool_instance: "PoolT | None" = None,
+        migration_config: "dict[str, Any] | MigrationConfig | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
+        self.bind_key = bind_key
         self.pool_instance = pool_instance
         self.pool_config = pool_config or {}
-        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self.extension_config: dict[str, dict[str, Any]] = extension_config or {}
+        self.migration_config: dict[str, Any] | MigrationConfig = migration_config or {}
         self._initialize_migration_components()
 
         if statement_config is None:
@@ -548,7 +733,7 @@ class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
         raise NotImplementedError
 
     def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "AbstractAsyncContextManager[DriverT]":
         """Provide a database session context manager."""
         raise NotImplementedError

sqlspec/core/__init__.py

@@ -1,9 +1,9 @@
-"""SQLSpec Core Module - High-Performance SQL Processing System.
+"""SQLSpec Core Module - SQL Processing System.
 
 This module provides the core SQL processing infrastructure for SQLSpec, implementing
 a complete pipeline for SQL statement compilation, parameter processing, caching,
-and result management. All components are optimized for MyPyC compilation and
-designed for maximum performance with minimal overhead.
+and result management. All components are optimized for MyPyC compilation to
+reduce overhead.
 
 Architecture Overview:
     The core module implements a single-pass processing pipeline where SQL statements
@@ -90,7 +90,7 @@ Example Usage:
 """
 
 from sqlspec.core import filters
-from sqlspec.core.cache import CacheConfig, CacheStats, MultiLevelCache, UnifiedCache, get_cache
+from sqlspec.core.cache import CacheConfig, CacheStats, MultiLevelCache, UnifiedCache, get_cache, get_cache_config
 from sqlspec.core.compiler import OperationType, SQLProcessor
 from sqlspec.core.filters import StatementFilter
 from sqlspec.core.hashing import (
@@ -131,6 +131,7 @@ __all__ = (
     "UnifiedCache",
     "filters",
     "get_cache",
+    "get_cache_config",
     "hash_expression",
     "hash_expression_node",
     "hash_optimized_expression",