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

sqlspec/config.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generic, Optional, TypeVar, Union, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeVar, cast
 
 from typing_extensions import NotRequired, TypedDict
 
@@ -19,35 +20,39 @@ if TYPE_CHECKING:
 
 
 __all__ = (
+    "ADKConfig",
     "AsyncConfigT",
     "AsyncDatabaseConfig",
     "ConfigT",
     "DatabaseConfigProtocol",
     "DriverT",
+    "FlaskConfig",
     "LifecycleConfig",
+    "LitestarConfig",
     "MigrationConfig",
     "NoPoolAsyncConfig",
     "NoPoolSyncConfig",
+    "StarletteConfig",
     "SyncConfigT",
     "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 +69,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 +87,262 @@ 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 FlaskConfig(TypedDict):
+    """Configuration options for Flask SQLSpec extension.
+
+    All fields are optional with sensible defaults. Use in extension_config["flask"]:
+
+    Example:
+        from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+        config = AsyncpgConfig(
+            pool_config={"dsn": "postgresql://localhost/mydb"},
+            extension_config={
+                "flask": {
+                    "commit_mode": "autocommit",
+                    "session_key": "db"
+                }
+            }
+        )
+
+    Notes:
+        This TypedDict provides type safety for extension config.
+        Flask extension uses g object for request-scoped storage.
+    """
+
+    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."""
+
+
+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 StarletteConfig(TypedDict):
+    """Configuration options for Starlette and FastAPI extensions.
+
+    All fields are optional with sensible defaults. Use in extension_config["starlette"]:
+
+    Example:
+        from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+        config = AsyncpgConfig(
+            pool_config={"dsn": "postgresql://localhost/mydb"},
+            extension_config={
+                "starlette": {
+                    "commit_mode": "autocommit",
+                    "session_key": "db"
+                }
+            }
+        )
+
+    Notes:
+        Both Starlette and FastAPI extensions use the "starlette" key.
+        This TypedDict provides type safety for extension config.
+    """
+
+    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()
+
+    Example:
+        extra_commit_statuses={201, 202}
+    """
+
+    extra_rollback_statuses: NotRequired[set[int]]
+    """Additional HTTP status codes that trigger rollback. Default: set()
+
+    Example:
+        extra_rollback_statuses={409}
+    """
+
+
+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."""
@@ -97,19 +358,21 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     )
 
     _migration_loader: "SQLFileLoader"
-    _migration_commands: "Union[SyncMigrationCommands, AsyncMigrationCommands]"
+    _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: "Optional[str]"
+    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)
@@ -124,38 +387,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
 
@@ -181,7 +444,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         from sqlspec.migrations.commands import create_migration_commands
 
         self._migration_loader = SQLFileLoader()
-        self._migration_commands = create_migration_commands(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.
@@ -193,8 +456,6 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         migration_config = self.migration_config or {}
         script_location = migration_config.get("script_location", "migrations")
 
-        from pathlib import Path
-
         migration_path = Path(script_location)
         if migration_path.exists() and not self._migration_loader.list_files():
             self._migration_loader.load_sql(migration_path)
@@ -202,7 +463,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 
         return self._migration_loader
 
-    def _ensure_migration_commands(self) -> "Union[SyncMigrationCommands, AsyncMigrationCommands]":
+    def _ensure_migration_commands(self) -> "SyncMigrationCommands | AsyncMigrationCommands":
         """Get the migration commands instance.
 
         Returns:
@@ -221,7 +482,7 @@ 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:
@@ -237,7 +498,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
             else:
                 logger.warning("Migration path does not exist: %s", path_obj)
 
-    def get_migration_commands(self) -> "Union[SyncMigrationCommands, AsyncMigrationCommands]":
+    def get_migration_commands(self) -> "SyncMigrationCommands | AsyncMigrationCommands":
         """Get migration commands for this configuration.
 
         Returns:
@@ -265,7 +526,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 
         await cast("AsyncMigrationCommands", commands).downgrade(revision)
 
-    async def get_current_migration(self, verbose: bool = False) -> "Optional[str]":
+    async def get_current_migration(self, verbose: bool = False) -> "str | None":
         """Get the current migration version.
 
         Args:
@@ -289,7 +550,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 
         await cast("AsyncMigrationCommands", commands).revision(message, file_type)
 
-    async def init_migrations(self, directory: "Optional[str]" = None, package: bool = True) -> None:
+    async def init_migrations(self, directory: "str | None" = None, package: bool = True) -> None:
         """Initialize migration directory structure.
 
         Args:
@@ -298,7 +559,7 @@ 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
@@ -309,7 +570,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 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
@@ -317,16 +578,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,
-        bind_key: "Optional[str]" = 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:
@@ -347,7 +610,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
@@ -365,7 +628,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
@@ -373,16 +636,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,
-        bind_key: "Optional[str]" = 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:
@@ -403,7 +668,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
@@ -421,7 +686,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
@@ -429,17 +694,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,
-        bind_key: "Optional[str]" = 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:
@@ -481,7 +748,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
@@ -500,7 +767,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
@@ -508,17 +775,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,
-        bind_key: "Optional[str]" = 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:
@@ -562,7 +831,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