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

sqlspec/statement/pipelines/transformers/_remove_hints.py

@@ -0,0 +1,81 @@
+"""Removes SQL hints from expressions."""
+
+from typing import TYPE_CHECKING, Optional
+
+from sqlglot import exp
+
+from sqlspec.statement.pipelines.base import ProcessorProtocol
+
+if TYPE_CHECKING:
+    from sqlspec.statement.pipelines.context import SQLProcessingContext
+
+__all__ = ("HintRemover",)
+
+
+class HintRemover(ProcessorProtocol):
+    """Removes SQL hints from expressions using SQLGlot's AST traversal.
+
+    This transformer removes SQL hints while preserving standard comments:
+    - Removes Oracle-style hints (/*+ hint */)
+    - Removes MySQL version comments (/*!50000 */)
+    - Removes formal hint expressions (exp.Hint nodes)
+    - Preserves standard comments (-- comment, /* comment */)
+    - Uses SQLGlot's AST for reliable, context-aware hint detection
+
+    Args:
+        enabled: Whether hint removal is enabled.
+        remove_oracle_hints: Whether to remove Oracle-style hints (/*+ hint */).
+        remove_mysql_version_comments: Whether to remove MySQL /*!50000 */ style comments.
+    """
+
+    def __init__(
+        self, enabled: bool = True, remove_oracle_hints: bool = True, remove_mysql_version_comments: bool = True
+    ) -> None:
+        self.enabled = enabled
+        self.remove_oracle_hints = remove_oracle_hints
+        self.remove_mysql_version_comments = remove_mysql_version_comments
+
+    def process(
+        self, expression: "Optional[exp.Expression]", context: "SQLProcessingContext"
+    ) -> "Optional[exp.Expression]":
+        """Removes SQL hints from the expression using SQLGlot AST traversal."""
+        if not self.enabled or expression is None or context.current_expression is None:
+            return expression
+
+        hints_removed_count = 0
+
+        def _remove_hint_node(node: exp.Expression) -> "Optional[exp.Expression]":
+            nonlocal hints_removed_count
+            if isinstance(node, exp.Hint):
+                hints_removed_count += 1
+                return None
+
+            if hasattr(node, "comments") and node.comments:
+                original_comment_count = len(node.comments)
+                comments_to_keep = []
+                for comment in node.comments:
+                    comment_text = str(comment).strip()
+                    hint_keywords = ["INDEX", "USE_NL", "USE_HASH", "PARALLEL", "FULL", "FIRST_ROWS", "ALL_ROWS"]
+                    is_oracle_hint = any(keyword in comment_text.upper() for keyword in hint_keywords)
+
+                    if is_oracle_hint:
+                        if self.remove_oracle_hints:
+                            continue
+                    elif comment_text.startswith("!") and self.remove_mysql_version_comments:
+                        continue
+
+                    comments_to_keep.append(comment)
+
+                if len(comments_to_keep) < original_comment_count:
+                    hints_removed_count += original_comment_count - len(comments_to_keep)
+                    node.pop_comments()
+                    if comments_to_keep:
+                        node.add_comments(comments_to_keep)
+            return node
+
+        transformed_expression = context.current_expression.transform(_remove_hint_node, copy=True)
+        context.current_expression = transformed_expression or exp.Anonymous(this="")
+
+        context.metadata["hints_removed"] = hints_removed_count
+
+        return context.current_expression

sqlspec/statement/pipelines/validators/__init__.py

@@ -0,0 +1,23 @@
+"""SQL Validation Pipeline Components."""
+
+from sqlspec.statement.pipelines.validators._dml_safety import DMLSafetyConfig, DMLSafetyValidator
+from sqlspec.statement.pipelines.validators._parameter_style import ParameterStyleValidator
+from sqlspec.statement.pipelines.validators._performance import PerformanceConfig, PerformanceValidator
+from sqlspec.statement.pipelines.validators._security import (
+    SecurityIssue,
+    SecurityIssueType,
+    SecurityValidator,
+    SecurityValidatorConfig,
+)
+
+__all__ = (
+    "DMLSafetyConfig",
+    "DMLSafetyValidator",
+    "ParameterStyleValidator",
+    "PerformanceConfig",
+    "PerformanceValidator",
+    "SecurityIssue",
+    "SecurityIssueType",
+    "SecurityValidator",
+    "SecurityValidatorConfig",
+)

sqlspec/statement/pipelines/validators/_dml_safety.py

@@ -0,0 +1,275 @@
+# DML Safety Validator - Consolidates risky DML operations and DDL prevention
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Optional
+
+from sqlglot import expressions as exp
+
+from sqlspec.exceptions import RiskLevel
+from sqlspec.statement.pipelines.validators.base import BaseValidator
+
+if TYPE_CHECKING:
+    from sqlspec.statement.pipelines.context import SQLProcessingContext
+
+__all__ = ("DMLSafetyConfig", "DMLSafetyValidator", "StatementCategory")
+
+
+class StatementCategory(Enum):
+    """Categories for SQL statement types."""
+
+    DDL = "ddl"  # CREATE, ALTER, DROP, TRUNCATE
+    DML = "dml"  # INSERT, UPDATE, DELETE, MERGE
+    DQL = "dql"  # SELECT
+    DCL = "dcl"  # GRANT, REVOKE
+    TCL = "tcl"  # COMMIT, ROLLBACK, SAVEPOINT
+
+
+@dataclass
+class DMLSafetyConfig:
+    """Configuration for DML safety validation."""
+
+    prevent_ddl: bool = True
+    prevent_dcl: bool = True
+    require_where_clause: "set[str]" = field(default_factory=lambda: {"DELETE", "UPDATE"})
+    allowed_ddl_operations: "set[str]" = field(default_factory=set)
+    migration_mode: bool = False  # Allow DDL in migration contexts
+    max_affected_rows: "Optional[int]" = None  # Limit for DML operations
+
+
+class DMLSafetyValidator(BaseValidator):
+    """Unified validator for DML/DDL safety checks.
+
+    This validator consolidates:
+    - DDL prevention (CREATE, ALTER, DROP, etc.)
+    - Risky DML detection (DELETE/UPDATE without WHERE)
+    - DCL restrictions (GRANT, REVOKE)
+    - Row limit enforcement
+    """
+
+    def __init__(self, config: "Optional[DMLSafetyConfig]" = None) -> None:
+        """Initialize the DML safety validator.
+
+        Args:
+            config: Configuration for safety validation
+        """
+        super().__init__()
+        self.config = config or DMLSafetyConfig()
+
+    def validate(self, expression: "exp.Expression", context: "SQLProcessingContext") -> None:
+        """Validate SQL statement for safety issues.
+
+        Args:
+            expression: The SQL expression to validate
+            context: The SQL processing context
+        """
+        # Categorize statement
+        category = self._categorize_statement(expression)
+        operation = self._get_operation_type(expression)
+
+        # Check DDL restrictions
+        if category == StatementCategory.DDL and self.config.prevent_ddl:
+            if operation not in self.config.allowed_ddl_operations:
+                self.add_error(
+                    context,
+                    message=f"DDL operation '{operation}' is not allowed",
+                    code="ddl-not-allowed",
+                    risk_level=RiskLevel.CRITICAL,
+                    expression=expression,
+                )
+
+        # Check DML safety
+        elif category == StatementCategory.DML:
+            if operation in self.config.require_where_clause and not self._has_where_clause(expression):
+                self.add_error(
+                    context,
+                    message=f"{operation} without WHERE clause affects all rows",
+                    code=f"{operation.lower()}-without-where",
+                    risk_level=RiskLevel.HIGH,
+                    expression=expression,
+                )
+
+            # Check affected row limits
+            if self.config.max_affected_rows:
+                estimated_rows = self._estimate_affected_rows(expression)
+                if estimated_rows > self.config.max_affected_rows:
+                    self.add_error(
+                        context,
+                        message=f"Operation may affect {estimated_rows:,} rows (limit: {self.config.max_affected_rows:,})",
+                        code="excessive-rows-affected",
+                        risk_level=RiskLevel.MEDIUM,
+                        expression=expression,
+                    )
+
+        # Check DCL restrictions
+        elif category == StatementCategory.DCL and self.config.prevent_dcl:
+            self.add_error(
+                context,
+                message=f"DCL operation '{operation}' is not allowed",
+                code="dcl-not-allowed",
+                risk_level=RiskLevel.HIGH,
+                expression=expression,
+            )
+
+        # Store metadata in context
+        context.metadata[self.__class__.__name__] = {
+            "statement_category": category.value,
+            "operation": operation,
+            "has_where_clause": self._has_where_clause(expression) if category == StatementCategory.DML else None,
+            "affected_tables": self._extract_affected_tables(expression),
+            "migration_mode": self.config.migration_mode,
+        }
+
+    @staticmethod
+    def _categorize_statement(expression: "exp.Expression") -> StatementCategory:
+        """Categorize SQL statement type.
+
+        Args:
+            expression: The SQL expression to categorize
+
+        Returns:
+            The statement category
+        """
+        if isinstance(expression, (exp.Create, exp.Alter, exp.Drop, exp.TruncateTable, exp.Comment)):
+            return StatementCategory.DDL
+
+        if isinstance(expression, (exp.Select, exp.Union, exp.Intersect, exp.Except)):
+            return StatementCategory.DQL
+
+        if isinstance(expression, (exp.Insert, exp.Update, exp.Delete, exp.Merge)):
+            return StatementCategory.DML
+
+        if isinstance(expression, (exp.Grant,)):
+            return StatementCategory.DCL
+
+        if isinstance(expression, (exp.Commit, exp.Rollback)):
+            return StatementCategory.TCL
+
+        return StatementCategory.DQL  # Default to query
+
+    @staticmethod
+    def _get_operation_type(expression: "exp.Expression") -> str:
+        """Get specific operation name.
+
+        Args:
+            expression: The SQL expression
+
+        Returns:
+            The operation type as string
+        """
+        return expression.__class__.__name__.upper()
+
+    @staticmethod
+    def _has_where_clause(expression: "exp.Expression") -> bool:
+        """Check if DML statement has WHERE clause.
+
+        Args:
+            expression: The SQL expression to check
+
+        Returns:
+            True if WHERE clause exists, False otherwise
+        """
+        if isinstance(expression, (exp.Delete, exp.Update)):
+            return expression.args.get("where") is not None
+        return True  # Other statements don't require WHERE
+
+    def _estimate_affected_rows(self, expression: "exp.Expression") -> int:
+        """Estimate number of rows affected by DML operation.
+
+        Args:
+            expression: The SQL expression
+
+        Returns:
+            Estimated number of affected rows
+        """
+        # Simple heuristic - can be enhanced with table statistics
+        if not self._has_where_clause(expression):
+            return 999999999  # Large number to indicate all rows
+
+        where = expression.args.get("where")
+        if where:
+            # Check for primary key or unique conditions
+            if self._has_unique_condition(where):
+                return 1
+            # Check for indexed conditions
+            if self._has_indexed_condition(where):
+                return 100  # Rough estimate
+
+        return 10000  # Conservative estimate
+
+    @staticmethod
+    def _has_unique_condition(where: "Optional[exp.Expression]") -> bool:
+        """Check if WHERE clause uses unique columns.
+
+        Args:
+            where: The WHERE expression
+
+        Returns:
+            True if unique condition found
+        """
+        if where is None:
+            return False
+        # Look for id = value patterns
+        for condition in where.find_all(exp.EQ):
+            if isinstance(condition.left, exp.Column):
+                col_name = condition.left.name.lower()
+                if col_name in {"id", "uuid", "guid", "pk", "primary_key"}:
+                    return True
+        return False
+
+    @staticmethod
+    def _has_indexed_condition(where: "Optional[exp.Expression]") -> bool:
+        """Check if WHERE clause uses indexed columns.
+
+        Args:
+            where: The WHERE expression
+
+        Returns:
+            True if indexed condition found
+        """
+        if where is None:
+            return False
+        # Look for common indexed column patterns
+        for condition in where.find_all(exp.Predicate):
+            if hasattr(condition, "left") and isinstance(condition.left, exp.Column):  # pyright: ignore
+                col_name = condition.left.name.lower()  # pyright: ignore
+                # Common indexed columns
+                if col_name in {"created_at", "updated_at", "email", "username", "status", "type"}:
+                    return True
+        return False
+
+    @staticmethod
+    def _extract_affected_tables(expression: "exp.Expression") -> "list[str]":
+        """Extract table names affected by the statement.
+
+        Args:
+            expression: The SQL expression
+
+        Returns:
+            List of affected table names
+        """
+        tables = []
+
+        # For DML statements
+        if isinstance(expression, (exp.Insert, exp.Update, exp.Delete)):
+            if hasattr(expression, "this") and expression.this:
+                table_expr = expression.this
+                if isinstance(table_expr, exp.Table):
+                    tables.append(table_expr.name)
+
+        # For DDL statements
+        elif (
+            isinstance(expression, (exp.Create, exp.Drop, exp.Alter))
+            and hasattr(expression, "this")
+            and expression.this
+        ):
+            # For CREATE TABLE, the table is in expression.this.this
+            if isinstance(expression, exp.Create) and isinstance(expression.this, exp.Schema):
+                if hasattr(expression.this, "this") and expression.this.this:
+                    table_expr = expression.this.this
+                    if isinstance(table_expr, exp.Table):
+                        tables.append(table_expr.name)
+            # For DROP/ALTER, table is directly in expression.this
+            elif isinstance(expression.this, (exp.Table, exp.Identifier)):
+                tables.append(expression.this.name)
+
+        return tables

sqlspec/statement/pipelines/validators/_parameter_style.py

@@ -0,0 +1,297 @@
+"""Parameter style validation for SQL statements."""
+
+import logging
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from sqlglot import exp
+
+from sqlspec.exceptions import MissingParameterError, RiskLevel, SQLValidationError
+from sqlspec.statement.pipelines.base import ProcessorProtocol
+from sqlspec.statement.pipelines.result_types import ValidationError
+from sqlspec.typing import is_dict
+
+if TYPE_CHECKING:
+    from sqlspec.statement.pipelines.context import SQLProcessingContext
+
+logger = logging.getLogger("sqlspec.validators.parameter_style")
+
+__all__ = ("ParameterStyleValidator",)
+
+
+class UnsupportedParameterStyleError(SQLValidationError):
+    """Raised when a parameter style is not supported by the current database."""
+
+
+class MixedParameterStyleError(SQLValidationError):
+    """Raised when mixed parameter styles are detected but not allowed."""
+
+
+class ParameterStyleValidator(ProcessorProtocol):
+    """Validates that parameter styles are supported by the database configuration.
+
+    This validator checks:
+    1. Whether detected parameter styles are in the allowed list
+    2. Whether mixed parameter styles are used when not allowed
+    3. Provides helpful error messages about supported styles
+    """
+
+    def __init__(self, risk_level: "RiskLevel" = RiskLevel.HIGH, fail_on_violation: bool = True) -> None:
+        """Initialize the parameter style validator.
+
+        Args:
+            risk_level: Risk level for unsupported parameter styles
+            fail_on_violation: Whether to raise exception on violation
+        """
+        self.risk_level = risk_level
+        self.fail_on_violation = fail_on_violation
+
+    def process(self, expression: "Optional[exp.Expression]", context: "SQLProcessingContext") -> None:
+        """Validate parameter styles in SQL.
+
+        Args:
+            expression: The SQL expression being validated
+            context: SQL processing context with config
+
+        Returns:
+            A ProcessorResult with the outcome of the validation.
+        """
+        if expression is None:
+            return
+
+        if context.current_expression is None:
+            error = ValidationError(
+                message="ParameterStyleValidator received no expression.",
+                code="no-expression",
+                risk_level=RiskLevel.CRITICAL,
+                processor="ParameterStyleValidator",
+                expression=None,
+            )
+            context.validation_errors.append(error)
+            return
+
+        try:
+            config = context.config
+            param_info = context.parameter_info
+
+            # First check parameter styles if configured
+            has_style_errors = False
+            if config.allowed_parameter_styles is not None and param_info:
+                unique_styles = {p.style for p in param_info}
+
+                # Check for mixed styles first (before checking individual styles)
+                if len(unique_styles) > 1 and not config.allow_mixed_parameter_styles:
+                    detected_style_strs = [str(s) for s in unique_styles]
+                    detected_styles = ", ".join(sorted(detected_style_strs))
+                    msg = f"Mixed parameter styles detected ({detected_styles}) but not allowed."
+                    if self.fail_on_violation:
+                        self._raise_mixed_style_error(msg)
+                    error = ValidationError(
+                        message=msg,
+                        code="mixed-parameter-styles",
+                        risk_level=self.risk_level,
+                        processor="ParameterStyleValidator",
+                        expression=expression,
+                    )
+                    context.validation_errors.append(error)
+                    has_style_errors = True
+
+                # Check for disallowed styles
+                disallowed_styles = {str(s) for s in unique_styles if not config.validate_parameter_style(s)}
+                if disallowed_styles:
+                    disallowed_str = ", ".join(sorted(disallowed_styles))
+                    # Defensive handling to avoid "expected str instance, NoneType found"
+                    if config.allowed_parameter_styles:
+                        allowed_styles_strs = [str(s) for s in config.allowed_parameter_styles]
+                        allowed_str = ", ".join(allowed_styles_strs)
+                        msg = f"Parameter style(s) {disallowed_str} not supported. Allowed: {allowed_str}"
+                    else:
+                        msg = f"Parameter style(s) {disallowed_str} not supported."
+
+                    if self.fail_on_violation:
+                        self._raise_unsupported_style_error(msg)
+                    error = ValidationError(
+                        message=msg,
+                        code="unsupported-parameter-style",
+                        risk_level=self.risk_level,
+                        processor="ParameterStyleValidator",
+                        expression=expression,
+                    )
+                    context.validation_errors.append(error)
+                    has_style_errors = True
+
+            # Check for missing parameters if:
+            # 1. We have parameter info
+            # 2. Style validation is enabled (allowed_parameter_styles is not None)
+            # 3. No style errors were found
+            # 4. We have merged parameters OR the original SQL had placeholders
+            logger.debug(
+                "Checking missing parameters: param_info=%s, extracted=%s, had_placeholders=%s, merged=%s",
+                len(param_info) if param_info else 0,
+                len(context.extracted_parameters_from_pipeline) if context.extracted_parameters_from_pipeline else 0,
+                context.input_sql_had_placeholders,
+                context.merged_parameters is not None,
+            )
+            # Skip validation if we have no merged parameters and the SQL didn't originally have placeholders
+            # This handles the case where literals were parameterized by transformers
+            if (
+                param_info
+                and config.allowed_parameter_styles is not None
+                and not has_style_errors
+                and (context.merged_parameters is not None or context.input_sql_had_placeholders)
+            ):
+                self._validate_missing_parameters(context, expression)
+
+        except (UnsupportedParameterStyleError, MixedParameterStyleError, MissingParameterError):
+            raise
+        except Exception as e:
+            logger.warning("Parameter style validation failed: %s", e)
+            error = ValidationError(
+                message=f"Parameter style validation failed: {e}",
+                code="validation-error",
+                risk_level=RiskLevel.LOW,
+                processor="ParameterStyleValidator",
+                expression=expression,
+            )
+            context.validation_errors.append(error)
+
+    @staticmethod
+    def _raise_mixed_style_error(msg: "str") -> "None":
+        """Raise MixedParameterStyleError with the given message."""
+        raise MixedParameterStyleError(msg)
+
+    @staticmethod
+    def _raise_unsupported_style_error(msg: "str") -> "None":
+        """Raise UnsupportedParameterStyleError with the given message."""
+        raise UnsupportedParameterStyleError(msg)
+
+    def _validate_missing_parameters(self, context: "SQLProcessingContext", expression: exp.Expression) -> None:
+        """Validate that all required parameters have values provided."""
+        param_info = context.parameter_info
+        if not param_info:
+            return
+
+        merged_params = self._prepare_merged_parameters(context, param_info)
+
+        if merged_params is None:
+            self._handle_no_parameters(context, expression, param_info)
+        elif isinstance(merged_params, (list, tuple)):
+            self._handle_positional_parameters(context, expression, param_info, merged_params)
+        elif is_dict(merged_params):
+            self._handle_named_parameters(context, expression, param_info, merged_params)
+        elif len(param_info) > 1:
+            self._handle_single_value_multiple_params(context, expression, param_info)
+
+    @staticmethod
+    def _prepare_merged_parameters(context: "SQLProcessingContext", param_info: list[Any]) -> Any:
+        """Prepare merged parameters for validation."""
+        merged_params = context.merged_parameters
+
+        # If we have extracted parameters from transformers (like ParameterizeLiterals),
+        # use those for validation instead of the original merged_parameters
+        if context.extracted_parameters_from_pipeline and not context.input_sql_had_placeholders:
+            # Use extracted parameters as they represent the actual values to be used
+            merged_params = context.extracted_parameters_from_pipeline
+        has_positional_colon = any(p.style.value == "positional_colon" for p in param_info)
+        if has_positional_colon and not isinstance(merged_params, (list, tuple, dict)) and merged_params is not None:
+            return [merged_params]
+        return merged_params
+
+    def _report_error(self, context: "SQLProcessingContext", expression: exp.Expression, message: str) -> None:
+        """Report a missing parameter error."""
+        if self.fail_on_violation:
+            raise MissingParameterError(message)
+        error = ValidationError(
+            message=message,
+            code="missing-parameters",
+            risk_level=self.risk_level,
+            processor="ParameterStyleValidator",
+            expression=expression,
+        )
+        context.validation_errors.append(error)
+
+    def _handle_no_parameters(
+        self, context: "SQLProcessingContext", expression: exp.Expression, param_info: list[Any]
+    ) -> None:
+        """Handle validation when no parameters are provided."""
+        if context.extracted_parameters_from_pipeline:
+            return
+        missing = [p.name or p.placeholder_text or f"param_{p.ordinal}" for p in param_info]
+        msg = f"Missing required parameters: {', '.join(str(m) for m in missing)}"
+        self._report_error(context, expression, msg)
+
+    def _handle_positional_parameters(
+        self,
+        context: "SQLProcessingContext",
+        expression: exp.Expression,
+        param_info: list[Any],
+        merged_params: "Union[list[Any], tuple[Any, ...]]",
+    ) -> None:
+        """Handle validation for positional parameters."""
+        has_named = any(p.style.value in {"named_colon", "named_at"} for p in param_info)
+        if has_named:
+            missing_named = [
+                p.name or p.placeholder_text for p in param_info if p.style.value in {"named_colon", "named_at"}
+            ]
+            if missing_named:
+                msg = f"Missing required parameters: {', '.join(str(m) for m in missing_named if m)}"
+                self._report_error(context, expression, msg)
+                return
+
+        has_positional_colon = any(p.style.value == "positional_colon" for p in param_info)
+        if has_positional_colon:
+            self._validate_oracle_numeric_params(context, expression, param_info, merged_params)
+        elif len(merged_params) < len(param_info):
+            msg = f"Expected {len(param_info)} parameters but got {len(merged_params)}"
+            self._report_error(context, expression, msg)
+
+    def _validate_oracle_numeric_params(
+        self,
+        context: "SQLProcessingContext",
+        expression: exp.Expression,
+        param_info: list[Any],
+        merged_params: "Union[list[Any], tuple[Any, ...]]",
+    ) -> None:
+        """Validate Oracle-style numeric parameters."""
+        missing_indices: list[str] = []
+        provided_count = len(merged_params)
+        for p in param_info:
+            if p.style.value != "positional_colon" or not p.name:
+                continue
+            try:
+                idx = int(p.name)
+                if not (idx < provided_count or (idx > 0 and (idx - 1) < provided_count)):
+                    missing_indices.append(p.name)
+            except (ValueError, TypeError):
+                pass
+        if missing_indices:
+            msg = f"Missing required parameters: :{', :'.join(missing_indices)}"
+            self._report_error(context, expression, msg)
+
+    def _handle_named_parameters(
+        self,
+        context: "SQLProcessingContext",
+        expression: exp.Expression,
+        param_info: list[Any],
+        merged_params: dict[str, Any],
+    ) -> None:
+        """Handle validation for named parameters."""
+        missing: list[str] = []
+        for p in param_info:
+            param_name = p.name
+            if param_name not in merged_params:
+                is_synthetic = any(key.startswith(("_arg_", "param_")) for key in merged_params)
+                is_named_style = p.style.value not in {"qmark", "numeric"}
+                if (not is_synthetic or is_named_style) and param_name:
+                    missing.append(param_name)
+
+        if missing:
+            msg = f"Missing required parameters: {', '.join(missing)}"
+            self._report_error(context, expression, msg)
+
+    def _handle_single_value_multiple_params(
+        self, context: "SQLProcessingContext", expression: exp.Expression, param_info: list[Any]
+    ) -> None:
+        """Handle validation for a single value provided for multiple parameters."""
+        missing = [p.name or p.placeholder_text or f"param_{p.ordinal}" for p in param_info[1:]]
+        msg = f"Missing required parameters: {', '.join(str(m) for m in missing)}"
+        self._report_error(context, expression, msg)