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

sqlspec/driver/_async.py

@@ -1,10 +1,10 @@
 """Asynchronous driver protocol implementation."""
 
 from abc import abstractmethod
-from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, Union, cast, overload
+from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, TypeVar, Union, cast, overload
 
 from sqlspec.core import SQL, Statement
-from sqlspec.driver._common import CommonDriverAttributesMixin, ExecutionResult
+from sqlspec.driver._common import CommonDriverAttributesMixin, DataDictionaryMixin, ExecutionResult, VersionInfo
 from sqlspec.driver.mixins import SQLTranslatorMixin, ToSchemaMixin
 from sqlspec.exceptions import NotFoundError
 from sqlspec.utils.logging import get_logger
@@ -21,17 +21,28 @@ if TYPE_CHECKING:
 _LOGGER_NAME: Final[str] = "sqlspec"
 logger = get_logger(_LOGGER_NAME)
 
-__all__ = ("AsyncDriverAdapterBase",)
+__all__ = ("AsyncDataDictionaryBase", "AsyncDriverAdapterBase", "AsyncDriverT")
 
 
 EMPTY_FILTERS: Final["list[StatementFilter]"] = []
 
+AsyncDriverT = TypeVar("AsyncDriverT", bound="AsyncDriverAdapterBase")
+
 
 class AsyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, ToSchemaMixin):
     """Base class for asynchronous database drivers."""
 
     __slots__ = ()
 
+    @property
+    @abstractmethod
+    def data_dictionary(self) -> "AsyncDataDictionaryBase":
+        """Get the data dictionary for this driver.
+
+        Returns:
+            Data dictionary instance for metadata queries
+        """
+
     async def dispatch_statement_execution(self, statement: "SQL", connection: "Any") -> "SQLResult":
         """Central execution dispatcher using the Template Method Pattern.
 
@@ -487,3 +498,95 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, To
     def _raise_cannot_extract_value_from_row_type(self, type_name: str) -> NoReturn:
         msg = f"Cannot extract value from row type {type_name}"
         raise TypeError(msg)
+
+
+class AsyncDataDictionaryBase(DataDictionaryMixin):
+    """Base class for asynchronous data dictionary implementations."""
+
+    @abstractmethod
+    async def get_version(self, driver: "AsyncDriverAdapterBase") -> "Optional[VersionInfo]":
+        """Get database version information.
+
+        Args:
+            driver: Async database driver instance
+
+        Returns:
+            Version information or None if detection fails
+        """
+
+    @abstractmethod
+    async def get_feature_flag(self, driver: "AsyncDriverAdapterBase", feature: str) -> bool:
+        """Check if database supports a specific feature.
+
+        Args:
+            driver: Async database driver instance
+            feature: Feature name to check
+
+        Returns:
+            True if feature is supported, False otherwise
+        """
+
+    @abstractmethod
+    async def get_optimal_type(self, driver: "AsyncDriverAdapterBase", type_category: str) -> str:
+        """Get optimal database type for a category.
+
+        Args:
+            driver: Async database driver instance
+            type_category: Type category (e.g., 'json', 'uuid', 'boolean')
+
+        Returns:
+            Database-specific type name
+        """
+
+    async def get_tables(self, driver: "AsyncDriverAdapterBase", schema: "Optional[str]" = None) -> "list[str]":
+        """Get list of tables in schema.
+
+        Args:
+            driver: Async database driver instance
+            schema: Schema name (None for default)
+
+        Returns:
+            List of table names
+        """
+        _ = driver, schema
+        return []
+
+    async def get_columns(
+        self, driver: "AsyncDriverAdapterBase", table: str, schema: "Optional[str]" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name
+            schema: Schema name (None for default)
+
+        Returns:
+            List of column metadata dictionaries
+        """
+        _ = driver, table, schema
+        return []
+
+    async def get_indexes(
+        self, driver: "AsyncDriverAdapterBase", table: str, schema: "Optional[str]" = None
+    ) -> "list[dict[str, Any]]":
+        """Get index information for a table.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name
+            schema: Schema name (None for default)
+
+        Returns:
+            List of index metadata dictionaries
+        """
+        _ = driver, table, schema
+        return []
+
+    def list_available_features(self) -> "list[str]":
+        """List all features that can be checked via get_feature_flag.
+
+        Returns:
+            List of feature names this data dictionary supports
+        """
+        return self.get_default_features()

sqlspec/driver/_common.py

@@ -1,6 +1,8 @@
 """Common driver attributes and utilities."""
 
-from typing import TYPE_CHECKING, Any, Final, NamedTuple, Optional, Union, cast
+import re
+from contextlib import suppress
+from typing import TYPE_CHECKING, Any, Final, NamedTuple, Optional, TypeVar, Union, cast
 
 from mypy_extensions import trait
 from sqlglot import exp
@@ -25,13 +27,158 @@ __all__ = (
     "EXEC_ROWCOUNT_OVERRIDE",
     "EXEC_SPECIAL_DATA",
     "CommonDriverAttributesMixin",
+    "DataDictionaryMixin",
     "ExecutionResult",
     "ScriptExecutionResult",
+    "VersionInfo",
 )
 
 
 logger = get_logger("driver")
 
+DriverT = TypeVar("DriverT")
+VERSION_GROUPS_MIN_FOR_MINOR = 1
+VERSION_GROUPS_MIN_FOR_PATCH = 2
+
+
+class VersionInfo:
+    """Database version information."""
+
+    def __init__(self, major: int, minor: int = 0, patch: int = 0) -> None:
+        """Initialize version info.
+
+        Args:
+            major: Major version number
+            minor: Minor version number
+            patch: Patch version number
+        """
+        self.major = major
+        self.minor = minor
+        self.patch = patch
+
+    @property
+    def version_tuple(self) -> "tuple[int, int, int]":
+        """Get version as tuple for comparison."""
+        return (self.major, self.minor, self.patch)
+
+    def __str__(self) -> str:
+        """String representation of version info."""
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+    def __repr__(self) -> str:
+        """Detailed string representation."""
+        return f"VersionInfo({self.major}, {self.minor}, {self.patch})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check version equality."""
+        if not isinstance(other, VersionInfo):
+            return NotImplemented
+        return self.version_tuple == other.version_tuple
+
+    def __lt__(self, other: "VersionInfo") -> bool:
+        """Check if this version is less than another."""
+        return self.version_tuple < other.version_tuple
+
+    def __le__(self, other: "VersionInfo") -> bool:
+        """Check if this version is less than or equal to another."""
+        return self.version_tuple <= other.version_tuple
+
+    def __gt__(self, other: "VersionInfo") -> bool:
+        """Check if this version is greater than another."""
+        return self.version_tuple > other.version_tuple
+
+    def __ge__(self, other: "VersionInfo") -> bool:
+        """Check if this version is greater than or equal to another."""
+        return self.version_tuple >= other.version_tuple
+
+    def __hash__(self) -> int:
+        """Make VersionInfo hashable based on version tuple."""
+        return hash(self.version_tuple)
+
+
+@trait
+class DataDictionaryMixin:
+    """Mixin providing common data dictionary functionality."""
+
+    def parse_version_string(self, version_str: str) -> "Optional[VersionInfo]":
+        """Parse version string into VersionInfo.
+
+        Args:
+            version_str: Raw version string from database
+
+        Returns:
+            VersionInfo instance or None if parsing fails
+        """
+        # Try common version patterns
+        patterns = [
+            r"(\d+)\.(\d+)\.(\d+)",  # x.y.z
+            r"(\d+)\.(\d+)",  # x.y
+            r"(\d+)",  # x
+        ]
+
+        for pattern in patterns:
+            match = re.search(pattern, version_str)
+            if match:
+                groups = match.groups()
+
+                major = int(groups[0])
+                minor = int(groups[1]) if len(groups) > VERSION_GROUPS_MIN_FOR_MINOR else 0
+                patch = int(groups[2]) if len(groups) > VERSION_GROUPS_MIN_FOR_PATCH else 0
+                return VersionInfo(major, minor, patch)
+
+        return None
+
+    def detect_version_with_queries(self, driver: Any, queries: "list[str]") -> "Optional[VersionInfo]":
+        """Try multiple version queries to detect database version.
+
+        Args:
+            driver: Database driver instance
+            queries: List of SQL queries to try
+
+        Returns:
+            Version information or None if detection fails
+        """
+        for query in queries:
+            with suppress(Exception):
+                result = driver.execute(query)
+                if result.data:
+                    version_str = str(result.data[0])
+                    if isinstance(result.data[0], dict):
+                        version_str = str(next(iter(result.data[0].values())))
+                    elif isinstance(result.data[0], (list, tuple)):
+                        version_str = str(result.data[0][0])
+
+                    parsed_version = self.parse_version_string(version_str)
+                    if parsed_version:
+                        logger.debug("Detected database version: %s", parsed_version)
+                        return parsed_version
+
+        logger.warning("Could not detect database version")
+        return None
+
+    def get_default_type_mapping(self) -> "dict[str, str]":
+        """Get default type mappings for common categories.
+
+        Returns:
+            Dictionary mapping type categories to generic SQL types
+        """
+        return {
+            "json": "TEXT",
+            "uuid": "VARCHAR(36)",
+            "boolean": "INTEGER",
+            "timestamp": "TIMESTAMP",
+            "text": "TEXT",
+            "blob": "BLOB",
+        }
+
+    def get_default_features(self) -> "list[str]":
+        """Get default feature flags supported by most databases.
+
+        Returns:
+            List of commonly supported feature names
+        """
+        return ["supports_transactions", "supports_prepared_statements"]
+
 
 class ScriptExecutionResult(NamedTuple):
     """Result from script execution with statement count information."""
@@ -270,7 +417,11 @@ class CommonDriverAttributesMixin:
         ]
 
     def prepare_driver_parameters(
-        self, parameters: Any, statement_config: "StatementConfig", is_many: bool = False
+        self,
+        parameters: Any,
+        statement_config: "StatementConfig",
+        is_many: bool = False,
+        prepared_statement: Optional[Any] = None,  # pyright: ignore[reportUnusedParameter]
     ) -> Any:
         """Prepare parameters for database driver consumption.
 
@@ -281,6 +432,7 @@ class CommonDriverAttributesMixin:
             parameters: Parameters in any format (dict, list, tuple, scalar, TypedParameter)
             statement_config: Statement configuration for parameter style detection
             is_many: If True, handle as executemany parameter sequence
+            prepared_statement: Optional prepared statement containing metadata for parameter processing
 
         Returns:
             Parameters with TypedParameter objects unwrapped to primitive values
@@ -422,7 +574,7 @@ class CommonDriverAttributesMixin:
         compiled_sql, execution_parameters = prepared_statement.compile()
 
         prepared_parameters = self.prepare_driver_parameters(
-            execution_parameters, statement_config, is_many=statement.is_many
+            execution_parameters, statement_config, is_many=statement.is_many, prepared_statement=statement
         )
 
         if statement_config.parameter_config.output_transformer:
@@ -438,7 +590,7 @@ class CommonDriverAttributesMixin:
                 if isinstance(prepared_parameters, list)
                 else (
                     prepared_parameters
-                    if prepared_parameters is None
+                    if prepared_parameters is None or isinstance(prepared_parameters, dict)
                     else (
                         tuple(prepared_parameters)
                         if not isinstance(prepared_parameters, tuple)

sqlspec/driver/_sync.py

@@ -1,10 +1,10 @@
 """Synchronous driver protocol implementation."""
 
 from abc import abstractmethod
-from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, Union, cast, overload
+from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, TypeVar, Union, cast, overload
 
 from sqlspec.core import SQL
-from sqlspec.driver._common import CommonDriverAttributesMixin, ExecutionResult
+from sqlspec.driver._common import CommonDriverAttributesMixin, DataDictionaryMixin, ExecutionResult, VersionInfo
 from sqlspec.driver.mixins import SQLTranslatorMixin, ToSchemaMixin
 from sqlspec.exceptions import NotFoundError
 from sqlspec.utils.logging import get_logger
@@ -21,17 +21,28 @@ if TYPE_CHECKING:
 _LOGGER_NAME: Final[str] = "sqlspec"
 logger = get_logger(_LOGGER_NAME)
 
-__all__ = ("SyncDriverAdapterBase",)
+__all__ = ("SyncDataDictionaryBase", "SyncDriverAdapterBase", "SyncDriverT")
 
 
 EMPTY_FILTERS: Final["list[StatementFilter]"] = []
 
+SyncDriverT = TypeVar("SyncDriverT", bound="SyncDriverAdapterBase")
+
 
 class SyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, ToSchemaMixin):
     """Base class for synchronous database drivers."""
 
     __slots__ = ()
 
+    @property
+    @abstractmethod
+    def data_dictionary(self) -> "SyncDataDictionaryBase":
+        """Get the data dictionary for this driver.
+
+        Returns:
+            Data dictionary instance for metadata queries
+        """
+
     def dispatch_statement_execution(self, statement: "SQL", connection: "Any") -> "SQLResult":
         """Central execution dispatcher using the Template Method Pattern.
 
@@ -488,3 +499,95 @@ class SyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, ToS
     def _raise_cannot_extract_value_from_row_type(self, type_name: str) -> NoReturn:
         msg = f"Cannot extract value from row type {type_name}"
         raise TypeError(msg)
+
+
+class SyncDataDictionaryBase(DataDictionaryMixin):
+    """Base class for synchronous data dictionary implementations."""
+
+    @abstractmethod
+    def get_version(self, driver: "SyncDriverAdapterBase") -> "Optional[VersionInfo]":
+        """Get database version information.
+
+        Args:
+            driver: Sync database driver instance
+
+        Returns:
+            Version information or None if detection fails
+        """
+
+    @abstractmethod
+    def get_feature_flag(self, driver: "SyncDriverAdapterBase", feature: str) -> bool:
+        """Check if database supports a specific feature.
+
+        Args:
+            driver: Sync database driver instance
+            feature: Feature name to check
+
+        Returns:
+            True if feature is supported, False otherwise
+        """
+
+    @abstractmethod
+    def get_optimal_type(self, driver: "SyncDriverAdapterBase", type_category: str) -> str:
+        """Get optimal database type for a category.
+
+        Args:
+            driver: Sync database driver instance
+            type_category: Type category (e.g., 'json', 'uuid', 'boolean')
+
+        Returns:
+            Database-specific type name
+        """
+
+    def get_tables(self, driver: "SyncDriverAdapterBase", schema: "Optional[str]" = None) -> "list[str]":
+        """Get list of tables in schema.
+
+        Args:
+            driver: Sync database driver instance
+            schema: Schema name (None for default)
+
+        Returns:
+            List of table names
+        """
+        _ = driver, schema
+        return []
+
+    def get_columns(
+        self, driver: "SyncDriverAdapterBase", table: str, schema: "Optional[str]" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table.
+
+        Args:
+            driver: Sync database driver instance
+            table: Table name
+            schema: Schema name (None for default)
+
+        Returns:
+            List of column metadata dictionaries
+        """
+        _ = driver, table, schema
+        return []
+
+    def get_indexes(
+        self, driver: "SyncDriverAdapterBase", table: str, schema: "Optional[str]" = None
+    ) -> "list[dict[str, Any]]":
+        """Get index information for a table.
+
+        Args:
+            driver: Sync database driver instance
+            table: Table name
+            schema: Schema name (None for default)
+
+        Returns:
+            List of index metadata dictionaries
+        """
+        _ = driver, table, schema
+        return []
+
+    def list_available_features(self) -> "list[str]":
+        """List all features that can be checked via get_feature_flag.
+
+        Returns:
+            List of feature names this data dictionary supports
+        """
+        return self.get_default_features()

sqlspec/exceptions.py

@@ -3,6 +3,7 @@ from contextlib import contextmanager
 from typing import Any, Optional, Union
 
 __all__ = (
+    "ConfigResolverError",
     "FileNotFoundInStorageError",
     "ImproperConfigurationError",
     "IntegrityError",
@@ -69,6 +70,10 @@ class BackendNotRegisteredError(SQLSpecError):
         super().__init__(f"Storage backend '{backend_key}' is not registered. Please register it before use.")
 
 
+class ConfigResolverError(SQLSpecError):
+    """Exception raised when config resolution fails."""
+
+
 class SQLParsingError(SQLSpecError):
     """Issues parsing SQL statements."""
 

sqlspec/migrations/__init__.py

@@ -4,7 +4,7 @@ A native migration system for SQLSpec that leverages the SQLFileLoader
 and driver system for database versioning.
 """
 
-from sqlspec.migrations.commands import AsyncMigrationCommands, MigrationCommands, SyncMigrationCommands
+from sqlspec.migrations.commands import AsyncMigrationCommands, SyncMigrationCommands, create_migration_commands
 from sqlspec.migrations.loaders import (
     BaseMigrationLoader,
     MigrationLoadError,
@@ -12,7 +12,7 @@ from sqlspec.migrations.loaders import (
     SQLFileLoader,
     get_migration_loader,
 )
-from sqlspec.migrations.runner import AsyncMigrationRunner, SyncMigrationRunner
+from sqlspec.migrations.runner import AsyncMigrationRunner, SyncMigrationRunner, create_migration_runner
 from sqlspec.migrations.tracker import AsyncMigrationTracker, SyncMigrationTracker
 from sqlspec.migrations.utils import create_migration_file, drop_all, get_author
 
@@ -21,14 +21,15 @@ __all__ = (
     "AsyncMigrationRunner",
     "AsyncMigrationTracker",
     "BaseMigrationLoader",
-    "MigrationCommands",
     "MigrationLoadError",
     "PythonFileLoader",
     "SQLFileLoader",
     "SyncMigrationCommands",
     "SyncMigrationRunner",
     "SyncMigrationTracker",
+    "create_migration_commands",
     "create_migration_file",
+    "create_migration_runner",
     "drop_all",
     "get_author",
     "get_migration_loader",