sqlspec 0.12.1__py3-none-any.whl → 0.13.0__py3-none-any.whl

sqlspec/driver/_common.py

@@ -9,9 +9,10 @@ import sqlglot
 from sqlglot import exp
 from sqlglot.tokens import TokenType
 
+from sqlspec.driver.parameters import normalize_parameter_sequence
 from sqlspec.exceptions import NotFoundError
 from sqlspec.statement import SQLConfig
-from sqlspec.statement.parameters import ParameterStyle, ParameterValidator
+from sqlspec.statement.parameters import ParameterStyle, ParameterValidator, TypedParameter
 from sqlspec.statement.splitter import split_sql_script
 from sqlspec.typing import ConnectionT, DictRow, RowT, T
 from sqlspec.utils.logging import get_logger
@@ -84,7 +85,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
             return self.returns_rows(expression.expressions[-1])
         if isinstance(expression, (exp.Insert, exp.Update, exp.Delete)):
             return bool(expression.find(exp.Returning))
-        # Handle Anonymous expressions (failed to parse) using a robust approach
         if isinstance(expression, exp.Anonymous):
             return self._check_anonymous_returns_rows(expression)
         return False
@@ -113,13 +113,11 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
 
         # Approach 1: Try to re-parse with placeholders replaced
         try:
-            # Replace placeholders with a dummy literal that sqlglot can parse
             sanitized_sql = placeholder_regex.sub("1", sql_text)
 
             # If we replaced any placeholders, try parsing again
             if sanitized_sql != sql_text:
                 parsed = sqlglot.parse_one(sanitized_sql, read=None)
-                # Check if it's a query type that returns rows
                 if isinstance(
                     parsed, (exp.Select, exp.Values, exp.Table, exp.Show, exp.Describe, exp.Pragma, exp.Command)
                 ):
@@ -193,15 +191,12 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
         if parameters is None:
             return None
 
-        # Extract parameter info from the SQL
         validator = ParameterValidator()
         param_info_list = validator.extract_parameters(sql)
 
         if not param_info_list:
-            # No parameters in SQL, return None
             return None
 
-        # Determine the target style from the SQL if not provided
         if target_style is None:
             target_style = self.default_parameter_style
 
@@ -220,7 +215,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
             ParameterStyle.NAMED_PYFORMAT,
         }
 
-        # Check if parameters are already in the correct format
         params_are_dict = isinstance(parameters, (dict, Mapping))
         params_are_sequence = isinstance(parameters, (list, tuple, Sequence)) and not isinstance(
             parameters, (str, bytes)
@@ -229,7 +223,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
         # Single scalar parameter
         if len(param_info_list) == 1 and not params_are_dict and not params_are_sequence:
             if driver_expects_dict:
-                # Convert scalar to dict
                 param_info = param_info_list[0]
                 if param_info.name:
                     return {param_info.name: parameters}
@@ -242,7 +235,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
             ):
                 # If all parameters are numeric but named, convert to dict
                 # SQL has numeric placeholders but params might have named keys
-                # Only convert if keys don't match
                 numeric_keys_expected = {p.name for p in param_info_list if p.name}
                 if not numeric_keys_expected.issubset(parameters.keys()):
                     # Need to convert named keys to numeric positions
@@ -255,7 +247,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
 
             # Special case: Auto-generated param_N style when SQL expects specific names
             if all(key.startswith("param_") and key[6:].isdigit() for key in parameters):
-                # Check if SQL has different parameter names
                 sql_param_names = {p.name for p in param_info_list if p.name}
                 if sql_param_names and not any(name.startswith("param_") for name in sql_param_names):
                     # SQL has specific names, not param_N style - don't use these params as-is
@@ -263,7 +254,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
                     # For now, pass through and let validation catch it
                     pass
 
-            # Otherwise, dict format matches - return as-is
             return parameters
 
         if not driver_expects_dict and params_are_sequence:
@@ -272,11 +262,9 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
 
         # Formats don't match - need conversion
         if driver_expects_dict and params_are_sequence:
-            # Convert positional to dict
             dict_result: dict[str, Any] = {}
             for i, (param_info, value) in enumerate(zip(param_info_list, parameters)):
                 if param_info.name:
-                    # Use the name from SQL
                     if param_info.style == ParameterStyle.POSITIONAL_COLON and param_info.name.isdigit():
                         # Oracle uses string keys even for numeric placeholders
                         dict_result[param_info.name] = value
@@ -288,10 +276,8 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
             return dict_result
 
         if not driver_expects_dict and params_are_dict:
-            # Convert dict to positional
             # First check if it's already in param_N format
             if all(key.startswith("param_") and key[6:].isdigit() for key in parameters):
-                # Extract values in order
                 positional_result: list[Any] = []
                 for i in range(len(param_info_list)):
                     key = f"param_{i}"
@@ -299,7 +285,6 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
                         positional_result.append(parameters[key])
                 return positional_result
 
-            # Convert named dict to positional based on parameter order in SQL
             positional_params: list[Any] = []
             for param_info in param_info_list:
                 if param_info.name and param_info.name in parameters:
@@ -336,3 +321,53 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
         """
         # The split_sql_script function already handles dialect mapping and fallback
         return split_sql_script(script, dialect=str(self.dialect), strip_trailing_semicolon=strip_trailing_semicolon)
+
+    def _prepare_driver_parameters(self, parameters: Any) -> Any:
+        """Prepare parameters for database driver consumption by unwrapping TypedParameter objects.
+
+        This method normalizes parameter structure and unwraps TypedParameter objects
+        to their underlying values, which database drivers expect.
+
+        Args:
+            parameters: Parameters in any format (dict, list, tuple, scalar, TypedParameter)
+
+        Returns:
+            Parameters with TypedParameter objects unwrapped to primitive values
+        """
+
+        normalized = normalize_parameter_sequence(parameters)
+        if not normalized:
+            return []
+
+        return [self._coerce_parameter(p) if isinstance(p, TypedParameter) else p for p in normalized]
+
+    def _prepare_driver_parameters_many(self, parameters: Any) -> "list[Any]":
+        """Prepare parameter sequences for executemany operations.
+
+        This method handles sequences of parameter sets, unwrapping TypedParameter
+        objects in each set for database driver consumption.
+
+        Args:
+            parameters: Sequence of parameter sets for executemany
+
+        Returns:
+            List of parameter sets with TypedParameter objects unwrapped
+        """
+        if not parameters:
+            return []
+        return [self._prepare_driver_parameters(param_set) for param_set in parameters]
+
+    def _coerce_parameter(self, param: "TypedParameter") -> Any:
+        """Coerce TypedParameter to driver-safe value.
+
+        This method extracts the underlying value from a TypedParameter object.
+        Individual drivers can override this method to perform driver-specific
+        type coercion using the rich type information available in TypedParameter.
+
+        Args:
+            param: TypedParameter object with value and type information
+
+        Returns:
+            The underlying parameter value suitable for the database driver
+        """
+        return param.value

sqlspec/driver/_sync.py

@@ -1,21 +1,22 @@
 """Synchronous driver protocol implementation."""
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any, Optional, Union, overload
 
 from sqlspec.driver._common import CommonDriverAttributesMixin
-from sqlspec.statement.builder import DeleteBuilder, InsertBuilder, QueryBuilder, SelectBuilder, UpdateBuilder
-from sqlspec.statement.filters import StatementFilter
+from sqlspec.driver.parameters import process_execute_many_parameters
+from sqlspec.statement.builder import Delete, Insert, QueryBuilder, Select, Update
 from sqlspec.statement.result import SQLResult
 from sqlspec.statement.sql import SQL, SQLConfig, Statement
 from sqlspec.typing import ConnectionT, DictRow, ModelDTOT, RowT, StatementParameters
 from sqlspec.utils.logging import get_logger
-
-logger = get_logger("sqlspec")
-
+from sqlspec.utils.type_guards import can_convert_to_schema
 
 if TYPE_CHECKING:
-    from sqlspec.statement.result import DMLResultDict, ScriptResultDict, SelectResultDict
+    from sqlspec.statement.filters import StatementFilter
+
+logger = get_logger("sqlspec")
 
 __all__ = ("SyncDriverAdapterProtocol",)
 
@@ -39,7 +40,6 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
             config: SQL statement configuration
             default_row_type: Default row type for results (DictRow, TupleRow, etc.)
         """
-        # Initialize CommonDriverAttributes part
         super().__init__(connection=connection, config=config, default_row_type=default_row_type)
 
     def _build_statement(
@@ -57,41 +57,61 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         # If statement is already a SQL object, handle additional parameters
         if isinstance(statement, SQL):
             if parameters or kwargs:
-                # Create a new SQL object with the same SQL but additional parameters
-                return SQL(statement._sql, *parameters, _dialect=self.dialect, _config=_config, **kwargs)
+                new_config = _config
+                if self.dialect and not new_config.dialect:
+                    new_config = replace(new_config, dialect=self.dialect)
+                # Use raw SQL if available to ensure proper parsing with dialect
+                sql_source = statement._raw_sql or statement._statement
+                # Preserve filters and state when creating new SQL object
+                existing_state = {
+                    "is_many": statement._is_many,
+                    "is_script": statement._is_script,
+                    "original_parameters": statement._original_parameters,
+                    "filters": statement._filters,
+                    "positional_params": statement._positional_params,
+                    "named_params": statement._named_params,
+                }
+                return SQL(sql_source, *parameters, config=new_config, _existing_state=existing_state, **kwargs)
+            # Even without additional parameters, ensure dialect is set
+            if self.dialect and (not statement._config.dialect or statement._config.dialect != self.dialect):
+                new_config = replace(statement._config, dialect=self.dialect)
+                # Use raw SQL if available to ensure proper parsing with dialect
+                sql_source = statement._raw_sql or statement._statement
+                # Preserve parameters and state when creating new SQL object
+                # Use the public parameters property which always has the right value
+                existing_state = {
+                    "is_many": statement._is_many,
+                    "is_script": statement._is_script,
+                    "original_parameters": statement._original_parameters,
+                    "filters": statement._filters,
+                    "positional_params": statement._positional_params,
+                    "named_params": statement._named_params,
+                }
+                if statement.parameters:
+                    return SQL(
+                        sql_source, parameters=statement.parameters, config=new_config, _existing_state=existing_state
+                    )
+                return SQL(sql_source, config=new_config, _existing_state=existing_state)
             return statement
-        return SQL(statement, *parameters, _dialect=self.dialect, _config=_config, **kwargs)
+        new_config = _config
+        if self.dialect and not new_config.dialect:
+            new_config = replace(new_config, dialect=self.dialect)
+        return SQL(statement, *parameters, config=new_config, **kwargs)
 
     @abstractmethod
     def _execute_statement(
         self, statement: "SQL", connection: "Optional[ConnectionT]" = None, **kwargs: Any
-    ) -> "Union[SelectResultDict, DMLResultDict, ScriptResultDict]":
+    ) -> "SQLResult[RowT]":
         """Actual execution implementation by concrete drivers, using the raw connection.
 
-        Returns one of the standardized result dictionaries based on the statement type.
+        Returns SQLResult directly based on the statement type.
         """
         raise NotImplementedError
 
-    @abstractmethod
-    def _wrap_select_result(
-        self,
-        statement: "SQL",
-        result: "SelectResultDict",
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-        **kwargs: Any,
-    ) -> "Union[SQLResult[ModelDTOT], SQLResult[RowT]]":
-        raise NotImplementedError
-
-    @abstractmethod
-    def _wrap_execute_result(
-        self, statement: "SQL", result: "Union[DMLResultDict, ScriptResultDict]", **kwargs: Any
-    ) -> "SQLResult[RowT]":
-        raise NotImplementedError
-
     @overload
     def execute(
         self,
-        statement: "SelectBuilder",
+        statement: "Select",
         /,
         *parameters: "Union[StatementParameters, StatementFilter]",
         schema_type: "type[ModelDTOT]",
@@ -103,7 +123,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
     @overload
     def execute(
         self,
-        statement: "SelectBuilder",
+        statement: "Select",
         /,
         *parameters: "Union[StatementParameters, StatementFilter]",
         schema_type: None = None,
@@ -115,7 +135,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
     @overload
     def execute(
         self,
-        statement: "Union[InsertBuilder, UpdateBuilder, DeleteBuilder]",
+        statement: "Union[Insert, Update, Delete]",
         /,
         *parameters: "Union[StatementParameters, StatementFilter]",
         _connection: "Optional[ConnectionT]" = None,
@@ -126,7 +146,7 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
     @overload
     def execute(
         self,
-        statement: "Statement",
+        statement: "Union[str, SQL]",
         /,
         *parameters: "Union[StatementParameters, StatementFilter]",
         schema_type: "type[ModelDTOT]",
@@ -160,13 +180,21 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         sql_statement = self._build_statement(statement, *parameters, _config=_config or self.config, **kwargs)
         result = self._execute_statement(statement=sql_statement, connection=self._connection(_connection), **kwargs)
 
-        if self.returns_rows(sql_statement.expression):
-            return self._wrap_select_result(
-                sql_statement, cast("SelectResultDict", result), schema_type=schema_type, **kwargs
+        # If schema_type is provided and we have data, convert it
+        if schema_type and result.data and can_convert_to_schema(self):
+            converted_data = list(self.to_schema(data=result.data, schema_type=schema_type))
+            return SQLResult[ModelDTOT](
+                statement=result.statement,
+                data=converted_data,
+                column_names=result.column_names,
+                rows_affected=result.rows_affected,
+                operation_type=result.operation_type,
+                last_inserted_id=result.last_inserted_id,
+                execution_time=result.execution_time,
+                metadata=result.metadata,
             )
-        return self._wrap_execute_result(
-            sql_statement, cast("Union[DMLResultDict, ScriptResultDict]", result), **kwargs
-        )
+
+        return result
 
     def execute_many(
         self,
@@ -177,37 +205,19 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         _config: "Optional[SQLConfig]" = None,
         **kwargs: Any,
     ) -> "SQLResult[RowT]":
-        # Separate parameters from filters
-        param_sequences = []
-        filters = []
-        for param in parameters:
-            if isinstance(param, StatementFilter):
-                filters.append(param)
-            else:
-                param_sequences.append(param)
+        _filters, param_sequence = process_execute_many_parameters(parameters)
+
+        # For execute_many, disable transformations to prevent literal extraction
+        # since the SQL already has placeholders for bulk operations
+        many_config = _config or self.config
+        if many_config.enable_transformations:
+            from dataclasses import replace
+
+            many_config = replace(many_config, enable_transformations=False)
 
-        # Use first parameter as the sequence for execute_many
-        param_sequence = param_sequences[0] if param_sequences else None
-        # Convert tuple to list if needed
-        if isinstance(param_sequence, tuple):
-            param_sequence = list(param_sequence)
-        # Ensure param_sequence is a list or None
-        if param_sequence is not None and not isinstance(param_sequence, list):
-            param_sequence = list(param_sequence) if hasattr(param_sequence, "__iter__") else None
-        sql_statement = self._build_statement(statement, _config=_config or self.config, **kwargs).as_many(
-            param_sequence
-        )
+        sql_statement = self._build_statement(statement, _config=many_config, **kwargs).as_many(param_sequence)
 
-        result = self._execute_statement(
-            statement=sql_statement,
-            connection=self._connection(_connection),
-            parameters=param_sequence,
-            is_many=True,
-            **kwargs,
-        )
-        return self._wrap_execute_result(
-            sql_statement, cast("Union[DMLResultDict, ScriptResultDict]", result), **kwargs
-        )
+        return self._execute_statement(statement=sql_statement, connection=self._connection(_connection), **kwargs)
 
     def execute_script(
         self,
@@ -218,44 +228,10 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         _config: "Optional[SQLConfig]" = None,
         **kwargs: Any,
     ) -> "SQLResult[RowT]":
-        # Separate parameters from filters
-        param_values = []
-        filters = []
-        for param in parameters:
-            if isinstance(param, StatementFilter):
-                filters.append(param)
-            else:
-                param_values.append(param)
-
-        # Use first parameter as the primary parameter value, or None if no parameters
-        primary_params = param_values[0] if param_values else None
-
         script_config = _config or self.config
         if script_config.enable_validation:
-            script_config = SQLConfig(
-                enable_parsing=script_config.enable_parsing,
-                enable_validation=False,
-                enable_transformations=script_config.enable_transformations,
-                enable_analysis=script_config.enable_analysis,
-                strict_mode=False,
-                cache_parsed_expression=script_config.cache_parsed_expression,
-                parameter_converter=script_config.parameter_converter,
-                parameter_validator=script_config.parameter_validator,
-                analysis_cache_size=script_config.analysis_cache_size,
-                allowed_parameter_styles=script_config.allowed_parameter_styles,
-                target_parameter_style=script_config.target_parameter_style,
-                allow_mixed_parameter_styles=script_config.allow_mixed_parameter_styles,
-            )
+            script_config = replace(script_config, enable_validation=False, strict_mode=False)
 
-        sql_statement = SQL(statement, primary_params, *filters, _dialect=self.dialect, _config=script_config, **kwargs)
+        sql_statement = self._build_statement(statement, *parameters, _config=script_config, **kwargs)
         sql_statement = sql_statement.as_script()
-        script_output = self._execute_statement(
-            statement=sql_statement, connection=self._connection(_connection), is_script=True, **kwargs
-        )
-        if isinstance(script_output, str):
-            result = SQLResult[RowT](statement=sql_statement, data=[], operation_type="SCRIPT")
-            result.total_statements = 1
-            result.successful_statements = 1
-            return result
-        # Wrap the ScriptResultDict using the driver's wrapper
-        return self._wrap_execute_result(sql_statement, cast("ScriptResultDict", script_output), **kwargs)
+        return self._execute_statement(statement=sql_statement, connection=self._connection(_connection), **kwargs)

sqlspec/driver/connection.py

@@ -0,0 +1,207 @@
+"""Consolidated connection management utilities for database drivers.
+
+This module provides centralized connection handling to avoid duplication
+across database adapter implementations.
+"""
+
+from contextlib import asynccontextmanager, contextmanager
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, cast
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator
+
+from sqlspec.utils.type_guards import is_async_transaction_capable, is_sync_transaction_capable
+
+__all__ = (
+    "get_connection_info",
+    "managed_connection_async",
+    "managed_connection_sync",
+    "managed_transaction_async",
+    "managed_transaction_sync",
+    "validate_pool_config",
+)
+
+
+ConnectionT = TypeVar("ConnectionT")
+PoolT = TypeVar("PoolT")
+
+
+@contextmanager
+def managed_connection_sync(config: Any, provided_connection: Optional[ConnectionT] = None) -> "Iterator[ConnectionT]":
+    """Context manager for database connections.
+
+    Args:
+        config: Database configuration with provide_connection method
+        provided_connection: Optional existing connection to use
+
+    Yields:
+        Database connection
+    """
+    if provided_connection is not None:
+        yield provided_connection
+        return
+
+    # Get connection from config
+    with config.provide_connection() as connection:
+        yield connection
+
+
+@contextmanager
+def managed_transaction_sync(connection: ConnectionT, auto_commit: bool = True) -> "Iterator[ConnectionT]":
+    """Context manager for database transactions.
+
+    Args:
+        connection: Database connection
+        auto_commit: Whether to auto-commit on success
+
+    Yields:
+        Database connection
+    """
+    # Check if connection already has autocommit enabled
+    has_autocommit = getattr(connection, "autocommit", False)
+
+    if not auto_commit or not is_sync_transaction_capable(connection) or has_autocommit:
+        yield connection
+        return
+
+    try:
+        yield cast("ConnectionT", connection)
+        cast("Any", connection).commit()
+    except Exception:
+        # Some databases (like DuckDB) throw an error if rollback is called
+        # when no transaction is active. Catch and ignore these specific errors.
+        try:
+            cast("Any", connection).rollback()
+        except Exception as rollback_error:
+            # Check if this is a "no transaction active" type error
+            error_msg = str(rollback_error).lower()
+            if "no transaction" in error_msg or "transaction context error" in error_msg:
+                # Ignore rollback errors when no transaction is active
+                pass
+            else:
+                # Re-raise other rollback errors
+                raise
+        raise
+
+
+@asynccontextmanager
+async def managed_connection_async(
+    config: Any, provided_connection: Optional[ConnectionT] = None
+) -> "AsyncIterator[ConnectionT]":
+    """Async context manager for database connections.
+
+    Args:
+        config: Database configuration with provide_connection method
+        provided_connection: Optional existing connection to use
+
+    Yields:
+        Database connection
+    """
+    if provided_connection is not None:
+        yield provided_connection
+        return
+
+    # Get connection from config
+    async with config.provide_connection() as connection:
+        yield connection
+
+
+@asynccontextmanager
+async def managed_transaction_async(connection: ConnectionT, auto_commit: bool = True) -> "AsyncIterator[ConnectionT]":
+    """Async context manager for database transactions.
+
+    Args:
+        connection: Database connection
+        auto_commit: Whether to auto-commit on success
+
+    Yields:
+        Database connection
+    """
+    # Check if connection already has autocommit enabled
+    has_autocommit = getattr(connection, "autocommit", False)
+
+    if not auto_commit or not is_async_transaction_capable(connection) or has_autocommit:
+        yield connection
+        return
+
+    try:
+        yield cast("ConnectionT", connection)
+        await cast("Any", connection).commit()
+    except Exception:
+        # Some databases (like DuckDB) throw an error if rollback is called
+        # when no transaction is active. Catch and ignore these specific errors.
+        try:
+            await cast("Any", connection).rollback()
+        except Exception as rollback_error:
+            # Check if this is a "no transaction active" type error
+            error_msg = str(rollback_error).lower()
+            if "no transaction" in error_msg or "transaction context error" in error_msg:
+                # Ignore rollback errors when no transaction is active
+                pass
+            else:
+                # Re-raise other rollback errors
+                raise
+        raise
+
+
+def get_connection_info(connection: Any) -> dict[str, Any]:
+    """Extract connection information for logging/debugging.
+
+    Args:
+        connection: Database connection object
+
+    Returns:
+        Dictionary of connection information
+    """
+    info = {"type": type(connection).__name__, "module": type(connection).__module__}
+
+    # Try to get database name
+    for attr in ("database", "dbname", "db", "catalog"):
+        value = getattr(connection, attr, None)
+        if value is not None:
+            info["database"] = value
+            break
+
+    # Try to get host information
+    for attr in ("host", "hostname", "server"):
+        value = getattr(connection, attr, None)
+        if value is not None:
+            info["host"] = value
+            break
+
+    return info
+
+
+def validate_pool_config(
+    min_size: int, max_size: int, max_idle_time: Optional[int] = None, max_lifetime: Optional[int] = None
+) -> None:
+    """Validate connection pool configuration.
+
+    Args:
+        min_size: Minimum pool size
+        max_size: Maximum pool size
+        max_idle_time: Maximum idle time in seconds
+        max_lifetime: Maximum connection lifetime in seconds
+
+    Raises:
+        ValueError: If configuration is invalid
+    """
+    if min_size < 0:
+        msg = f"min_size must be >= 0, got {min_size}"
+        raise ValueError(msg)
+
+    if max_size < 1:
+        msg = f"max_size must be >= 1, got {max_size}"
+        raise ValueError(msg)
+
+    if min_size > max_size:
+        msg = f"min_size ({min_size}) cannot be greater than max_size ({max_size})"
+        raise ValueError(msg)
+
+    if max_idle_time is not None and max_idle_time < 0:
+        msg = f"max_idle_time must be >= 0, got {max_idle_time}"
+        raise ValueError(msg)
+
+    if max_lifetime is not None and max_lifetime < 0:
+        msg = f"max_lifetime must be >= 0, got {max_lifetime}"
+        raise ValueError(msg)