sqlspec 0.13.1__py3-none-any.whl → 0.14.1__py3-none-any.whl

sqlspec/cli.py

@@ -0,0 +1,248 @@
+import sys
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
+
+if TYPE_CHECKING:
+    from click import Group
+
+    from sqlspec.config import AsyncDatabaseConfig, SyncDatabaseConfig
+
+__all__ = ("add_migration_commands", "get_sqlspec_group")
+
+
+def get_sqlspec_group() -> "Group":
+    """Get the SQLSpec CLI group.
+
+    Raises:
+        MissingDependencyError: If the `click` package is not installed.
+
+    Returns:
+        The SQLSpec CLI group.
+    """
+    from sqlspec.exceptions import MissingDependencyError
+
+    try:
+        import rich_click as click
+    except ImportError:
+        try:
+            import click  # type: ignore[no-redef]
+        except ImportError as e:
+            raise MissingDependencyError(package="click", install_package="cli") from e
+
+    @click.group(name="sqlspec")
+    @click.option(
+        "--config",
+        help="Dotted path to SQLAlchemy config(s) (e.g. 'myapp.config.sqlspec_configs')",
+        required=True,
+        type=str,
+    )
+    @click.pass_context
+    def sqlspec_group(ctx: "click.Context", config: str) -> None:
+        """SQLSpec CLI commands."""
+        from rich import get_console
+
+        from sqlspec.utils import module_loader
+
+        console = get_console()
+        ctx.ensure_object(dict)
+        try:
+            config_instance = module_loader.import_string(config)
+            if isinstance(config_instance, Sequence):
+                ctx.obj["configs"] = config_instance
+            else:
+                ctx.obj["configs"] = [config_instance]
+        except ImportError as e:
+            console.print(f"[red]Error loading config: {e}[/]")
+            ctx.exit(1)
+
+    return sqlspec_group
+
+
+def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
+    """Add migration commands to the database group.
+
+    Args:
+        database_group: The database group to add the commands to.
+
+    Raises:
+        MissingDependencyError: If the `click` package is not installed.
+
+    Returns:
+        The database group with the migration commands added.
+    """
+    from sqlspec.exceptions import MissingDependencyError
+
+    try:
+        import rich_click as click
+    except ImportError:
+        try:
+            import click  # type: ignore[no-redef]
+        except ImportError as e:
+            raise MissingDependencyError(package="click", install_package="cli") from e
+    from rich import get_console
+
+    console = get_console()
+
+    if database_group is None:
+        database_group = get_sqlspec_group()
+
+    bind_key_option = click.option(
+        "--bind-key", help="Specify which SQLAlchemy config to use by bind key", type=str, default=None
+    )
+    verbose_option = click.option("--verbose", help="Enable verbose output.", type=bool, default=False, is_flag=True)
+    no_prompt_option = click.option(
+        "--no-prompt",
+        help="Do not prompt for confirmation before executing the command.",
+        type=bool,
+        default=False,
+        required=False,
+        show_default=True,
+        is_flag=True,
+    )
+
+    def get_config_by_bind_key(
+        ctx: "click.Context", bind_key: Optional[str]
+    ) -> "Union[AsyncDatabaseConfig[Any, Any, Any], SyncDatabaseConfig[Any, Any, Any]]":
+        """Get the SQLAlchemy config for the specified bind key.
+
+        Args:
+            ctx: The click context.
+            bind_key: The bind key to get the config for.
+
+        Returns:
+            The SQLAlchemy config for the specified bind key.
+        """
+        configs = ctx.obj["configs"]
+        if bind_key is None:
+            return cast("Union[AsyncDatabaseConfig[Any, Any, Any], SyncDatabaseConfig[Any, Any, Any]]", configs[0])
+
+        for config in configs:
+            # Check if config has a name or identifier attribute
+            config_name = getattr(config, "name", None) or getattr(config, "bind_key", None)
+            if config_name == bind_key:
+                return cast("Union[AsyncDatabaseConfig[Any, Any, Any], SyncDatabaseConfig[Any, Any, Any]]", config)
+
+        console.print(f"[red]No config found for bind key: {bind_key}[/]")
+        sys.exit(1)
+
+    @database_group.command(name="show-current-revision", help="Shows the current revision for the database.")
+    @bind_key_option
+    @verbose_option
+    def show_database_revision(bind_key: Optional[str], verbose: bool) -> None:  # pyright: ignore[reportUnusedFunction]
+        """Show current database revision."""
+        from sqlspec.migrations.commands import MigrationCommands
+
+        ctx = click.get_current_context()
+        console.rule("[yellow]Listing current revision[/]", align="left")
+        sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+        migration_commands = MigrationCommands(config=sqlspec_config)
+        migration_commands.current(verbose=verbose)
+
+    @database_group.command(name="downgrade", help="Downgrade database to a specific revision.")
+    @bind_key_option
+    @no_prompt_option
+    @click.argument("revision", type=str, default="-1")
+    def downgrade_database(  # pyright: ignore[reportUnusedFunction]
+        bind_key: Optional[str], revision: str, no_prompt: bool
+    ) -> None:
+        """Downgrade the database to the latest revision."""
+        from rich.prompt import Confirm
+
+        from sqlspec.migrations.commands import MigrationCommands
+
+        ctx = click.get_current_context()
+        console.rule("[yellow]Starting database downgrade process[/]", align="left")
+        input_confirmed = (
+            True
+            if no_prompt
+            else Confirm.ask(f"Are you sure you want to downgrade the database to the `{revision}` revision?")
+        )
+        if input_confirmed:
+            sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+            migration_commands = MigrationCommands(config=sqlspec_config)
+            migration_commands.downgrade(revision=revision)
+
+    @database_group.command(name="upgrade", help="Upgrade database to a specific revision.")
+    @bind_key_option
+    @no_prompt_option
+    @click.argument("revision", type=str, default="head")
+    def upgrade_database(  # pyright: ignore[reportUnusedFunction]
+        bind_key: Optional[str], revision: str, no_prompt: bool
+    ) -> None:
+        """Upgrade the database to the latest revision."""
+        from rich.prompt import Confirm
+
+        from sqlspec.migrations.commands import MigrationCommands
+
+        ctx = click.get_current_context()
+        console.rule("[yellow]Starting database upgrade process[/]", align="left")
+        input_confirmed = (
+            True
+            if no_prompt
+            else Confirm.ask(f"[bold]Are you sure you want migrate the database to the `{revision}` revision?[/]")
+        )
+        if input_confirmed:
+            sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+            migration_commands = MigrationCommands(config=sqlspec_config)
+            migration_commands.upgrade(revision=revision)
+
+    @database_group.command(help="Stamp the revision table with the given revision")
+    @click.argument("revision", type=str)
+    @bind_key_option
+    def stamp(bind_key: Optional[str], revision: str) -> None:  # pyright: ignore[reportUnusedFunction]
+        """Stamp the revision table with the given revision."""
+        from sqlspec.migrations.commands import MigrationCommands
+
+        ctx = click.get_current_context()
+        sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+        migration_commands = MigrationCommands(config=sqlspec_config)
+        migration_commands.stamp(revision=revision)
+
+    @database_group.command(name="init", help="Initialize migrations for the project.")
+    @bind_key_option
+    @click.argument("directory", default=None, required=False)
+    @click.option("--package", is_flag=True, default=True, help="Create `__init__.py` for created folder")
+    @no_prompt_option
+    def init_sqlspec(  # pyright: ignore[reportUnusedFunction]
+        bind_key: Optional[str], directory: Optional[str], package: bool, no_prompt: bool
+    ) -> None:
+        """Initialize the database migrations."""
+        from rich.prompt import Confirm
+
+        from sqlspec.migrations.commands import MigrationCommands
+
+        ctx = click.get_current_context()
+        console.rule("[yellow]Initializing database migrations.", align="left")
+        input_confirmed = (
+            True if no_prompt else Confirm.ask("[bold]Are you sure you want initialize migrations for the project?[/]")
+        )
+        if input_confirmed:
+            configs = [get_config_by_bind_key(ctx, bind_key)] if bind_key is not None else ctx.obj["configs"]
+            for config in configs:
+                migration_config = getattr(config, "migration_config", {})
+                directory = migration_config.get("script_location", "migrations") if directory is None else directory
+                migration_commands = MigrationCommands(config=config)
+                migration_commands.init(directory=cast("str", directory), package=package)
+
+    @database_group.command(name="make-migrations", help="Create a new migration revision.")
+    @bind_key_option
+    @click.option("-m", "--message", default=None, help="Revision message")
+    @no_prompt_option
+    def create_revision(  # pyright: ignore[reportUnusedFunction]
+        bind_key: Optional[str], message: Optional[str], no_prompt: bool
+    ) -> None:
+        """Create a new database revision."""
+        from rich.prompt import Prompt
+
+        from sqlspec.migrations.commands import MigrationCommands
+
+        ctx = click.get_current_context()
+        console.rule("[yellow]Creating new migration revision[/]", align="left")
+        if message is None:
+            message = "new migration" if no_prompt else Prompt.ask("Please enter a message describing this revision")
+
+        sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+        migration_commands = MigrationCommands(config=sqlspec_config)
+        migration_commands.revision(message=message)
+
+    return database_group

sqlspec/config.py

@@ -47,10 +47,6 @@ logger = get_logger("config")
 class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     """Protocol defining the interface for database configurations."""
 
-    # Note: __slots__ cannot be used with dataclass fields in Python < 3.10
-    # Concrete subclasses can still use __slots__ for any additional attributes
-    __slots__ = ()
-
     is_async: "ClassVar[bool]" = field(init=False, default=False)
     supports_connection_pooling: "ClassVar[bool]" = field(init=False, default=False)
     supports_native_arrow_import: "ClassVar[bool]" = field(init=False, default=False)
@@ -61,12 +57,24 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     driver_type: "type[DriverT]" = field(init=False, repr=False, hash=False, compare=False)
     pool_instance: "Optional[PoolT]" = field(default=None)
     default_row_type: "type[Any]" = field(init=False)
+    migration_config: "dict[str, Any]" = field(default_factory=dict)
+    """Migration configuration settings."""
     _dialect: "DialectType" = field(default=None, init=False, repr=False, hash=False, compare=False)
 
+    # Adapter-level cache configuration
+    enable_adapter_cache: bool = field(default=True)
+    """Enable adapter-level SQL compilation caching."""
+    adapter_cache_size: int = field(default=500)
+    """Maximum number of compiled SQL statements to cache per adapter."""
+    enable_prepared_statements: bool = field(default=False)
+    """Enable prepared statement pooling for supported databases."""
+    prepared_statement_cache_size: int = field(default=100)
+    """Maximum number of prepared statements to maintain."""
+
     supported_parameter_styles: "ClassVar[tuple[str, ...]]" = ()
     """Parameter styles supported by this database adapter (e.g., ('qmark', 'named_colon'))."""
 
-    preferred_parameter_style: "ClassVar[str]" = "none"
+    default_parameter_style: "ClassVar[str]" = "none"
     """The preferred/native parameter style for this database."""
 
     def __hash__(self) -> int:
@@ -85,7 +93,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
             The SQL dialect type for this database.
         """
         if self._dialect is None:
-            self._dialect = self._get_dialect()  # type: ignore[misc]
+            self._dialect = self._get_dialect()
         return self._dialect
 
     def _get_dialect(self) -> "DialectType":
@@ -177,8 +185,6 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
 class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     """Base class for a sync database configurations that do not implement a pool."""
 
-    __slots__ = ()
-
     is_async: "ClassVar[bool]" = field(init=False, default=False)
     supports_connection_pooling: "ClassVar[bool]" = field(init=False, default=False)
     pool_instance: None = None
@@ -209,8 +215,6 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     """Base class for an async database configurations that do not implement a pool."""
 
-    __slots__ = ()
-
     is_async: "ClassVar[bool]" = field(init=False, default=True)
     supports_connection_pooling: "ClassVar[bool]" = field(init=False, default=False)
     pool_instance: None = None
@@ -241,15 +245,11 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 class GenericPoolConfig:
     """Generic Database Pool Configuration."""
 
-    __slots__ = ()
-
 
 @dataclass
 class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     """Generic Sync Database Configuration."""
 
-    __slots__ = ()
-
     is_async: "ClassVar[bool]" = field(init=False, default=False)
     supports_connection_pooling: "ClassVar[bool]" = field(init=False, default=True)
 
@@ -261,7 +261,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
         """
         if self.pool_instance is not None:
             return self.pool_instance
-        self.pool_instance = self._create_pool()  # type: ignore[misc]
+        self.pool_instance = self._create_pool()
         return self.pool_instance
 
     def close_pool(self) -> None:
@@ -271,7 +271,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     def provide_pool(self, *args: Any, **kwargs: Any) -> PoolT:
         """Provide pool instance."""
         if self.pool_instance is None:
-            self.pool_instance = self.create_pool()  # type: ignore[misc]
+            self.pool_instance = self.create_pool()
         return self.pool_instance
 
     def create_connection(self) -> ConnectionT:
@@ -301,8 +301,6 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
 class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     """Generic Async Database Configuration."""
 
-    __slots__ = ()
-
     is_async: "ClassVar[bool]" = field(init=False, default=True)
     supports_connection_pooling: "ClassVar[bool]" = field(init=False, default=True)
 
@@ -314,7 +312,7 @@ class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
         """
         if self.pool_instance is not None:
             return self.pool_instance
-        self.pool_instance = await self._create_pool()  # type: ignore[misc]
+        self.pool_instance = await self._create_pool()
         return self.pool_instance
 
     async def close_pool(self) -> None:
@@ -324,7 +322,7 @@ class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     async def provide_pool(self, *args: Any, **kwargs: Any) -> PoolT:
         """Provide pool instance."""
         if self.pool_instance is None:
-            self.pool_instance = await self.create_pool()  # type: ignore[misc]
+            self.pool_instance = await self.create_pool()
         return self.pool_instance
 
     async def create_connection(self) -> ConnectionT:

sqlspec/driver/_async.py

@@ -207,17 +207,23 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         _config: "Optional[SQLConfig]" = None,
         **kwargs: Any,
     ) -> "SQLResult[RowT]":
-        _filters, param_sequence = process_execute_many_parameters(parameters)
+        """Execute statement multiple times with different 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
+        Now passes first parameter set through pipeline to enable
+        literal extraction and consistent parameter processing.
+        """
+        filters, param_sequence = process_execute_many_parameters(parameters)
+
+        # Process first parameter set through pipeline for literal extraction
+        first_params = param_sequence[0] if param_sequence else None
 
-            many_config = replace(many_config, enable_transformations=False)
+        # Build statement with first params to trigger pipeline processing
+        sql_statement = self._build_statement(
+            statement, first_params, *filters, _config=_config or self.config, **kwargs
+        )
 
-        sql_statement = self._build_statement(statement, _config=many_config, **kwargs).as_many(param_sequence)
+        # Mark as many with full sequence
+        sql_statement = sql_statement.as_many(param_sequence)
 
         return await self._execute_statement(
             statement=sql_statement, connection=self._connection(_connection), **kwargs
@@ -230,14 +236,26 @@ class AsyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         *parameters: "Union[StatementParameters, StatementFilter]",
         _connection: "Optional[ConnectionT]" = None,
         _config: "Optional[SQLConfig]" = None,
+        _suppress_warnings: bool = False,  # New parameter for migrations
         **kwargs: Any,
     ) -> "SQLResult[RowT]":
+        """Execute a multi-statement script.
+
+        By default, validates each statement and logs warnings for dangerous
+        operations. Use _suppress_warnings=True for migrations and admin scripts.
+        """
         script_config = _config or self.config
-        if script_config.enable_validation:
-            script_config = replace(script_config, enable_validation=False, strict_mode=False)
+
+        # Keep validation enabled by default
+        # Validators will log warnings for dangerous operations
 
         sql_statement = self._build_statement(statement, *parameters, _config=script_config, **kwargs)
         sql_statement = sql_statement.as_script()
+
+        # Pass suppress warnings flag to execution
+        if _suppress_warnings:
+            kwargs["_suppress_warnings"] = True
+
         return await self._execute_statement(
             statement=sql_statement, connection=self._connection(_connection), **kwargs
         )

sqlspec/driver/_common.py

@@ -9,7 +9,7 @@ import sqlglot
 from sqlglot import exp
 from sqlglot.tokens import TokenType
 
-from sqlspec.driver.parameters import normalize_parameter_sequence
+from sqlspec.driver.parameters import convert_parameter_sequence
 from sqlspec.exceptions import NotFoundError
 from sqlspec.statement import SQLConfig
 from sqlspec.statement.parameters import ParameterStyle, ParameterValidator, TypedParameter
@@ -60,6 +60,7 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
             config: SQL statement configuration
             default_row_type: Default row type for results (DictRow, TupleRow, etc.)
         """
+        super().__init__()
         self.connection = connection
         self.config = config or SQLConfig()
         self.default_row_type = default_row_type or dict[str, Any]
@@ -335,11 +336,11 @@ class CommonDriverAttributesMixin(ABC, Generic[ConnectionT, RowT]):
             Parameters with TypedParameter objects unwrapped to primitive values
         """
 
-        normalized = normalize_parameter_sequence(parameters)
-        if not normalized:
+        converted = convert_parameter_sequence(parameters)
+        if not converted:
             return []
 
-        return [self._coerce_parameter(p) if isinstance(p, TypedParameter) else p for p in normalized]
+        return [self._coerce_parameter(p) if isinstance(p, TypedParameter) else p for p in converted]
 
     def _prepare_driver_parameters_many(self, parameters: Any) -> "list[Any]":
         """Prepare parameter sequences for executemany operations.

sqlspec/driver/_sync.py

@@ -205,17 +205,23 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         _config: "Optional[SQLConfig]" = None,
         **kwargs: Any,
     ) -> "SQLResult[RowT]":
-        _filters, param_sequence = process_execute_many_parameters(parameters)
+        """Execute statement multiple times with different 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
+        Now passes first parameter set through pipeline to enable
+        literal extraction and consistent parameter processing.
+        """
+        filters, param_sequence = process_execute_many_parameters(parameters)
+
+        # Process first parameter set through pipeline for literal extraction
+        first_params = param_sequence[0] if param_sequence else None
 
-            many_config = replace(many_config, enable_transformations=False)
+        # Build statement with first params to trigger pipeline processing
+        sql_statement = self._build_statement(
+            statement, first_params, *filters, _config=_config or self.config, **kwargs
+        )
 
-        sql_statement = self._build_statement(statement, _config=many_config, **kwargs).as_many(param_sequence)
+        # Mark as many with full sequence
+        sql_statement = sql_statement.as_many(param_sequence)
 
         return self._execute_statement(statement=sql_statement, connection=self._connection(_connection), **kwargs)
 
@@ -226,12 +232,24 @@ class SyncDriverAdapterProtocol(CommonDriverAttributesMixin[ConnectionT, RowT],
         *parameters: "Union[StatementParameters, StatementFilter]",
         _connection: "Optional[ConnectionT]" = None,
         _config: "Optional[SQLConfig]" = None,
+        _suppress_warnings: bool = False,  # New parameter for migrations
         **kwargs: Any,
     ) -> "SQLResult[RowT]":
+        """Execute a multi-statement script.
+
+        By default, validates each statement and logs warnings for dangerous
+        operations. Use _suppress_warnings=True for migrations and admin scripts.
+        """
         script_config = _config or self.config
-        if script_config.enable_validation:
-            script_config = replace(script_config, enable_validation=False, strict_mode=False)
+
+        # Keep validation enabled by default
+        # Validators will log warnings for dangerous operations
 
         sql_statement = self._build_statement(statement, *parameters, _config=script_config, **kwargs)
         sql_statement = sql_statement.as_script()
+
+        # Pass suppress warnings flag to execution
+        if _suppress_warnings:
+            kwargs["_suppress_warnings"] = True
+
         return self._execute_statement(statement=sql_statement, connection=self._connection(_connection), **kwargs)

sqlspec/driver/mixins/__init__.py

@@ -1,16 +1,22 @@
 """Driver mixins for instrumentation, storage, and utilities."""
 
+from sqlspec.driver.mixins._cache import AsyncAdapterCacheMixin, SyncAdapterCacheMixin
 from sqlspec.driver.mixins._pipeline import AsyncPipelinedExecutionMixin, SyncPipelinedExecutionMixin
+from sqlspec.driver.mixins._query_tools import AsyncQueryMixin, SyncQueryMixin
 from sqlspec.driver.mixins._result_utils import ToSchemaMixin
 from sqlspec.driver.mixins._sql_translator import SQLTranslatorMixin
 from sqlspec.driver.mixins._storage import AsyncStorageMixin, SyncStorageMixin
 from sqlspec.driver.mixins._type_coercion import TypeCoercionMixin
 
 __all__ = (
+    "AsyncAdapterCacheMixin",
     "AsyncPipelinedExecutionMixin",
+    "AsyncQueryMixin",
     "AsyncStorageMixin",
     "SQLTranslatorMixin",
+    "SyncAdapterCacheMixin",
     "SyncPipelinedExecutionMixin",
+    "SyncQueryMixin",
     "SyncStorageMixin",
     "ToSchemaMixin",
     "TypeCoercionMixin",

sqlspec/driver/mixins/_cache.py

@@ -0,0 +1,114 @@
+"""Adapter-level caching mixin for compiled SQL and prepared statements."""
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from sqlspec.statement.cache import SQLCache
+from sqlspec.statement.parameters import ParameterStyle
+
+if TYPE_CHECKING:
+    from sqlspec.statement.sql import SQL
+
+__all__ = ("AsyncAdapterCacheMixin", "SyncAdapterCacheMixin")
+
+
+class SyncAdapterCacheMixin:
+    """Mixin for adapter-level SQL compilation caching.
+
+    This mixin provides:
+    - Compiled SQL caching to avoid repeated compilation
+    - Parameter style conversion caching
+    - Prepared statement name management (for supported databases)
+
+    Integrates transparently with existing adapter execution flow.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize adapter with caching support."""
+        super().__init__(*args, **kwargs)
+
+        # Get cache configuration from config or use defaults
+        config = getattr(self, "config", None)
+        cache_size = getattr(config, "adapter_cache_size", 500) if config else 500
+        enable_cache = getattr(config, "enable_adapter_cache", True) if config else True
+
+        # Initialize caches
+        self._compiled_cache: Optional[SQLCache] = SQLCache(max_size=cache_size) if enable_cache else None
+        self._prepared_statements: dict[str, str] = {}
+        self._prepared_counter = 0
+
+    def _get_compiled_sql(self, statement: "SQL", target_style: ParameterStyle) -> tuple[str, Any]:
+        """Get compiled SQL with caching.
+
+        Args:
+            statement: SQL statement to compile
+            target_style: Target parameter style for compilation
+
+        Returns:
+            Tuple of (compiled_sql, parameters)
+        """
+        if self._compiled_cache is None:
+            # Caching disabled
+            return statement.compile(placeholder_style=target_style)
+
+        # Generate cache key
+        cache_key = self._adapter_cache_key(statement, target_style)
+
+        # Check cache
+        cached = self._compiled_cache.get(cache_key)
+        if cached is not None:
+            return cached  # type: ignore[no-any-return]
+
+        # Compile and cache
+        result = statement.compile(placeholder_style=target_style)
+        self._compiled_cache.set(cache_key, result)
+        return result
+
+    def _adapter_cache_key(self, statement: "SQL", style: ParameterStyle) -> str:
+        """Generate adapter-specific cache key.
+
+        Args:
+            statement: SQL statement
+            style: Parameter style
+
+        Returns:
+            Cache key string
+        """
+        # Use statement's internal cache key which includes SQL hash, params, and dialect
+        base_key = statement._cache_key()
+        # Add adapter-specific context
+        return f"{self.__class__.__name__}:{style.value}:{base_key}"
+
+    def _get_or_create_prepared_statement_name(self, sql_hash: str) -> str:
+        """Get or create a prepared statement name for the given SQL.
+
+        Used by PostgreSQL and other databases that support prepared statements.
+
+        Args:
+            sql_hash: Hash of the SQL statement
+
+        Returns:
+            Prepared statement name
+        """
+        if sql_hash in self._prepared_statements:
+            return self._prepared_statements[sql_hash]
+
+        # Create new prepared statement name
+        self._prepared_counter += 1
+        stmt_name = f"sqlspec_ps_{self._prepared_counter}"
+        self._prepared_statements[sql_hash] = stmt_name
+        return stmt_name
+
+    def _clear_adapter_cache(self) -> None:
+        """Clear all adapter-level caches."""
+        if self._compiled_cache is not None:
+            self._compiled_cache.clear()
+        self._prepared_statements.clear()
+        self._prepared_counter = 0
+
+
+class AsyncAdapterCacheMixin(SyncAdapterCacheMixin):
+    """Async version of AdapterCacheMixin.
+
+    Identical to AdapterCacheMixin since caching operations are synchronous.
+    Provided for naming consistency with async adapters.
+    """