sqlspec 0.13.1__tar.gz → 0.14.1__tar.gz

{sqlspec-0.13.1 → sqlspec-0.14.1}/.gitignore

@@ -50,3 +50,7 @@ GEMINI.*.md
 .cursorrules
 CLAUDE*.md
 *CLAUDE*.md
+requirements/*
+tools/*.json
+benchmarks/
+.benchmark

{sqlspec-0.13.1 → sqlspec-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.13.1
+Version: 0.14.1
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.13.1 → sqlspec-0.14.1}/pyproject.toml

@@ -7,7 +7,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.9, <4.0"
-version = "0.13.1"
+version = "0.14.1"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -48,6 +48,7 @@ uuid = ["uuid-utils"]
 
 
 [dependency-groups]
+benchmarks = ["sqlalchemy", "psutil", "types-psutil"]
 build = ["bump-my-version"]
 dev = [
   { include-group = "extras" },
@@ -55,6 +56,7 @@ dev = [
   { include-group = "doc" },
   { include-group = "test" },
   { include-group = "build" },
+  { include-group = "benchmarks" },
 ]
 doc = [
   "auto-pytabs[sphinx]>=0.5.0",
@@ -106,6 +108,9 @@ test = [
   "pytest-xdist>=3.6.1",
 ]
 
+[project.scripts]
+sqlspec = "sqlspec.__main__:run_cli"
+
 [build-system]
 build-backend = "hatchling.build"
 requires = ["hatchling"]
@@ -126,7 +131,7 @@ packages = ["sqlspec"]
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.13.1"
+current_version = "0.14.1"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec-0.14.1/sqlspec/__init__.py

@@ -0,0 +1,67 @@
+"""SQLSpec: Safe and elegant SQL query building for Python."""
+
+from sqlspec import adapters, base, driver, exceptions, extensions, loader, statement, typing, utils
+from sqlspec.__metadata__ import __version__
+from sqlspec._sql import SQLFactory
+from sqlspec.base import SQLSpec
+from sqlspec.config import AsyncDatabaseConfig, SyncDatabaseConfig
+from sqlspec.exceptions import (
+    NotFoundError,
+    ParameterError,
+    SQLBuilderError,
+    SQLFileNotFoundError,
+    SQLFileParseError,
+    SQLParsingError,
+    SQLValidationError,
+)
+from sqlspec.loader import SQLFile, SQLFileLoader
+from sqlspec.statement.builder import Column, ColumnExpression, Delete, FunctionColumn, Insert, Merge, Select, Update
+from sqlspec.statement.result import ArrowResult, SQLResult
+from sqlspec.statement.sql import SQL, SQLConfig
+from sqlspec.typing import ConnectionT, DictRow, ModelDTOT, ModelT, RowT, StatementParameters
+
+sql = SQLFactory()
+
+__all__ = (
+    "SQL",
+    "ArrowResult",
+    "AsyncDatabaseConfig",
+    "Column",
+    "ColumnExpression",
+    "ConnectionT",
+    "Delete",
+    "DictRow",
+    "FunctionColumn",
+    "Insert",
+    "Merge",
+    "ModelDTOT",
+    "ModelT",
+    "NotFoundError",
+    "ParameterError",
+    "RowT",
+    "SQLBuilderError",
+    "SQLConfig",
+    "SQLFile",
+    "SQLFileLoader",
+    "SQLFileNotFoundError",
+    "SQLFileParseError",
+    "SQLParsingError",
+    "SQLResult",
+    "SQLSpec",
+    "SQLValidationError",
+    "Select",
+    "StatementParameters",
+    "SyncDatabaseConfig",
+    "Update",
+    "__version__",
+    "adapters",
+    "base",
+    "driver",
+    "exceptions",
+    "extensions",
+    "loader",
+    "sql",
+    "statement",
+    "typing",
+    "utils",
+)

sqlspec-0.14.1/sqlspec/__main__.py

@@ -0,0 +1,12 @@
+from sqlspec.cli import add_migration_commands as build_cli_interface
+
+__all__ = ("run_cli",)
+
+
+def run_cli() -> None:  # pragma: no cover
+    """SQLSpec CLI"""
+    build_cli_interface()()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run_cli()

{sqlspec-0.13.1 → sqlspec-0.14.1}/sqlspec/adapters/adbc/config.py

@@ -6,6 +6,7 @@ from dataclasses import replace
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Optional
 
 from sqlspec.adapters.adbc.driver import AdbcConnection, AdbcDriver
+from sqlspec.adapters.adbc.transformers import AdbcPostgresTransformer
 from sqlspec.config import NoPoolSyncConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.statement.sql import SQLConfig
@@ -69,41 +70,6 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
     - Cloud database integrations
     """
 
-    __slots__ = (
-        "_dialect",
-        "account",
-        "adbc_driver_manager_entrypoint",
-        "authorization_header",
-        "autocommit",
-        "batch_size",
-        "conn_kwargs",
-        "connection_timeout",
-        "database",
-        "dataset_id",
-        "db_kwargs",
-        "default_row_type",
-        "driver_name",
-        "extras",
-        "grpc_options",
-        "isolation_level",
-        "on_connection_create",
-        "password",
-        "pool_instance",
-        "project_id",
-        "query_timeout",
-        "role",
-        "schema",
-        "ssl_ca",
-        "ssl_cert",
-        "ssl_key",
-        "ssl_mode",
-        "statement_config",
-        "token",
-        "uri",
-        "username",
-        "warehouse",
-    )
-
     is_async: ClassVar[bool] = False
     supports_connection_pooling: ClassVar[bool] = False
     driver_type: type[AdbcDriver] = AdbcDriver
@@ -114,7 +80,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
     supported_parameter_styles: ClassVar[tuple[str, ...]] = ("qmark",)
     """ADBC parameter styles depend on the underlying driver."""
 
-    preferred_parameter_style: ClassVar[str] = "qmark"
+    default_parameter_style: ClassVar[str] = "qmark"
     """ADBC default parameter style is ? (qmark)."""
 
     def __init__(
@@ -251,7 +217,6 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
         self.statement_config = statement_config or SQLConfig()
         self.default_row_type = default_row_type
         self.on_connection_create = on_connection_create
-        self._dialect: DialectType = None
         super().__init__()
 
     def _resolve_driver_name(self) -> str:
@@ -381,7 +346,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
         """Get parameter styles based on the underlying driver.
 
         Returns:
-            Tuple of (supported_parameter_styles, preferred_parameter_style)
+            Tuple of (supported_parameter_styles, default_parameter_style)
         """
         try:
             driver_path = self._resolve_driver_name()
@@ -400,7 +365,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
 
         except Exception:
             # If we can't determine driver, use defaults
-            return (self.supported_parameter_styles, self.preferred_parameter_style)
+            return (self.supported_parameter_styles, self.default_parameter_style)
         return (("qmark",), "qmark")
 
     def create_connection(self) -> AdbcConnection:
@@ -467,9 +432,20 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
                         statement_config = replace(
                             statement_config,
                             allowed_parameter_styles=supported_styles,
-                            target_parameter_style=preferred_style,
+                            default_parameter_style=preferred_style,
                         )
 
+                    # Add ADBC PostgreSQL transformer if needed
+                    if self._get_dialect() == "postgres":
+                        # Get the default transformers from the pipeline
+                        pipeline = statement_config.get_statement_pipeline()
+                        existing_transformers = list(pipeline.transformers)
+
+                        # Append our transformer to the existing ones
+                        existing_transformers.append(AdbcPostgresTransformer())
+
+                        statement_config = replace(statement_config, transformers=existing_transformers)
+
                 driver = self.driver_type(connection=connection, config=statement_config)
                 yield driver
 

{sqlspec-0.13.1 → sqlspec-0.14.1}/sqlspec/adapters/adbc/driver.py

@@ -12,12 +12,13 @@ from sqlspec.driver import SyncDriverAdapterProtocol
 from sqlspec.driver.connection import managed_transaction_sync
 from sqlspec.driver.mixins import (
     SQLTranslatorMixin,
+    SyncAdapterCacheMixin,
     SyncPipelinedExecutionMixin,
     SyncStorageMixin,
     ToSchemaMixin,
     TypeCoercionMixin,
 )
-from sqlspec.driver.parameters import normalize_parameter_sequence
+from sqlspec.driver.parameters import convert_parameter_sequence
 from sqlspec.exceptions import wrap_exceptions
 from sqlspec.statement.parameters import ParameterStyle
 from sqlspec.statement.result import ArrowResult, SQLResult
@@ -37,6 +38,7 @@ AdbcConnection = Connection
 
 class AdbcDriver(
     SyncDriverAdapterProtocol["AdbcConnection", RowT],
+    SyncAdapterCacheMixin,
     SQLTranslatorMixin,
     TypeCoercionMixin,
     SyncStorageMixin,
@@ -60,7 +62,6 @@ class AdbcDriver(
     supports_native_arrow_export: ClassVar[bool] = True
     supports_native_parquet_export: ClassVar[bool] = False  # Not implemented yet
     supports_native_parquet_import: ClassVar[bool] = True
-    __slots__ = ("default_parameter_style", "dialect", "supported_parameter_styles")
 
     def __init__(
         self,
@@ -181,7 +182,7 @@ class AdbcDriver(
         self, statement: SQL, connection: Optional["AdbcConnection"] = None, **kwargs: Any
     ) -> SQLResult[RowT]:
         if statement.is_script:
-            sql, _ = statement.compile(placeholder_style=ParameterStyle.STATIC)
+            sql, _ = self._get_compiled_sql(statement, ParameterStyle.STATIC)
             return self._execute_script(sql, connection=connection, **kwargs)
 
         detected_styles = {p.style for p in statement.parameter_info}
@@ -197,7 +198,7 @@ class AdbcDriver(
                     target_style = style
                     break
 
-        sql, params = statement.compile(placeholder_style=target_style)
+        sql, params = self._get_compiled_sql(statement, target_style)
         params = self._process_parameters(params)
         if statement.is_many:
             return self._execute_many(sql, params, connection=connection, **kwargs)
@@ -211,17 +212,21 @@ class AdbcDriver(
         conn = connection if connection is not None else self._connection(None)
 
         with managed_transaction_sync(conn, auto_commit=True) as txn_conn:
-            normalized_params = normalize_parameter_sequence(parameters)
-            if normalized_params is not None and not isinstance(normalized_params, (list, tuple)):
-                cursor_params = [normalized_params]
+            converted_params = convert_parameter_sequence(parameters)
+            if converted_params is not None and not isinstance(converted_params, (list, tuple)):
+                cursor_params = [converted_params]
             else:
-                cursor_params = normalized_params
+                cursor_params = converted_params
 
             with self._get_cursor(txn_conn) as cursor:
                 try:
+                    # ADBC PostgreSQL has issues with NULL parameters in some cases
+                    # The transformer handles all-NULL cases, but mixed NULL/non-NULL
+                    # can still cause "Can't map Arrow type 'na' to Postgres type" errors
                     cursor.execute(sql, cursor_params or [])
                 except Exception as e:
-                    # Rollback transaction on error for PostgreSQL to avoid "current transaction is aborted" errors
+                    # Rollback transaction on error for PostgreSQL to avoid
+                    # "current transaction is aborted" errors
                     if self.dialect == "postgres":
                         with contextlib.suppress(Exception):
                             cursor.execute("ROLLBACK")
@@ -261,11 +266,22 @@ class AdbcDriver(
 
         with managed_transaction_sync(conn, auto_commit=True) as txn_conn:
             # Normalize parameter list using consolidated utility
-            normalized_param_list = normalize_parameter_sequence(param_list)
+            converted_param_list = convert_parameter_sequence(param_list)
+
+            # Handle empty parameter list case for PostgreSQL
+            if not converted_param_list and self.dialect == "postgres":
+                # Return empty result without executing
+                return SQLResult(
+                    statement=SQL(sql, _dialect=self.dialect),
+                    data=[],
+                    rows_affected=0,
+                    operation_type="EXECUTE",
+                    metadata={"status_message": "OK"},
+                )
 
             with self._get_cursor(txn_conn) as cursor:
                 try:
-                    cursor.executemany(sql, normalized_param_list or [])
+                    cursor.executemany(sql, converted_param_list or [])
                 except Exception as e:
                     if self.dialect == "postgres":
                         with contextlib.suppress(Exception):
@@ -290,18 +306,28 @@ class AdbcDriver(
         with managed_transaction_sync(conn, auto_commit=True) as txn_conn:
             # ADBC drivers don't support multiple statements in a single execute
             statements = self._split_script_statements(script)
+            suppress_warnings = kwargs.get("_suppress_warnings", False)
 
             executed_count = 0
+            total_rows = 0
             with self._get_cursor(txn_conn) as cursor:
                 for statement in statements:
                     if statement.strip():
-                        self._execute_single_script_statement(cursor, statement)
+                        # Validate each statement unless warnings suppressed
+                        if not suppress_warnings:
+                            # Run validation through pipeline
+                            temp_sql = SQL(statement, config=self.config)
+                            temp_sql._ensure_processed()
+                            # Validation errors are logged as warnings by default
+
+                        rows = self._execute_single_script_statement(cursor, statement)
                         executed_count += 1
+                        total_rows += rows
 
             return SQLResult(
                 statement=SQL(script, _dialect=self.dialect).as_script(),
                 data=[],
-                rows_affected=0,
+                rows_affected=total_rows,
                 operation_type="SCRIPT",
                 metadata={"status_message": "SCRIPT EXECUTED"},
                 total_statements=executed_count,
@@ -316,18 +342,19 @@ class AdbcDriver(
             statement: The SQL statement to execute
 
         Returns:
-            1 if successful, 0 if failed
+            Number of rows affected
         """
         try:
             cursor.execute(statement)
         except Exception as e:
-            # Rollback transaction on error for PostgreSQL to avoid "current transaction is aborted" errors
+            # Rollback transaction on error for PostgreSQL to avoid
+            # "current transaction is aborted" errors
             if self.dialect == "postgres":
                 with contextlib.suppress(Exception):
                     cursor.execute("ROLLBACK")
             raise e from e
         else:
-            return 1
+            return cursor.rowcount or 0
 
     def _fetch_arrow_table(self, sql: SQL, connection: "Optional[Any]" = None, **kwargs: Any) -> "ArrowResult":
         """ADBC native Arrow table fetching.

sqlspec-0.14.1/sqlspec/adapters/adbc/transformers.py

@@ -0,0 +1,108 @@
+"""ADBC-specific AST transformers for handling driver limitations."""
+
+from typing import Optional
+
+from sqlglot import exp
+
+from sqlspec.protocols import ProcessorProtocol
+from sqlspec.statement.pipelines.context import SQLProcessingContext
+
+__all__ = ("AdbcPostgresTransformer",)
+
+
+class AdbcPostgresTransformer(ProcessorProtocol):
+    """Transformer to handle ADBC PostgreSQL driver limitations.
+
+    This transformer addresses specific issues with the ADBC PostgreSQL driver:
+    1. Empty parameter lists in executemany() causing "no parameter $1" errors
+    2. NULL parameters causing "Can't map Arrow type 'na' to Postgres type" errors
+
+    The transformer works at the AST level to properly handle these edge cases.
+    """
+
+    def __init__(self) -> None:
+        self.has_placeholders = False
+        self.all_params_null = False
+        self.is_empty_params = False
+        self.has_null_params = False
+        self.null_param_indices: list[int] = []
+
+    def process(self, expression: Optional[exp.Expression], context: SQLProcessingContext) -> Optional[exp.Expression]:
+        """Process the SQL expression to handle ADBC limitations."""
+        if not expression:
+            return expression
+
+        # Check if we have an empty parameter list for executemany
+        # Look at the merged_parameters in the context
+        params = context.merged_parameters
+
+        # For execute_many, check if we have an empty list
+        if isinstance(params, list) and len(params) == 0:
+            self.is_empty_params = True
+
+        # Check for NULL parameters
+        if params:
+            if isinstance(params, (list, tuple)):
+                # Track which parameters are NULL
+                self.null_param_indices = [i for i, p in enumerate(params) if p is None]
+                self.has_null_params = len(self.null_param_indices) > 0
+                self.all_params_null = len(self.null_param_indices) == len(params)
+
+                # For ADBC PostgreSQL, we need to replace NULL parameters with literals
+                # and remove them from the parameter list
+                if self.has_null_params:
+                    # Create new parameter list without NULLs
+                    new_params = [p for p in params if p is not None]
+                    context.merged_parameters = new_params
+
+            elif isinstance(params, dict):
+                # For dict parameters, track which ones are NULL
+                null_keys = [k for k, v in params.items() if v is None]
+                self.has_null_params = len(null_keys) > 0
+                self.all_params_null = len(null_keys) == len(params)
+
+                if self.has_null_params:
+                    # Remove NULL parameters from dict
+                    context.merged_parameters = {k: v for k, v in params.items() if v is not None}
+
+        # Transform the AST if needed
+        if self.is_empty_params:
+            # For empty parameters, we should skip transformation and let the driver handle it
+            # The driver already has logic to return empty result for empty params
+            return expression
+
+        if self.has_null_params:
+            # Transform placeholders to NULL literals where needed
+            self._parameter_index = 0  # Track current parameter position
+            return expression.transform(self._transform_node)
+
+        return expression
+
+    def _transform_node(self, node: exp.Expression) -> exp.Expression:
+        """Transform individual AST nodes."""
+        # Handle parameter nodes (e.g., $1, $2, etc. in PostgreSQL)
+        if isinstance(node, exp.Parameter):
+            # Access the parameter value directly from the AST node
+            # The 'this' attribute contains a Literal node, whose 'this' contains the actual value
+            if node.this and isinstance(node.this, exp.Literal):
+                try:
+                    param_index = int(node.this.this) - 1  # Convert to 0-based index
+                    # Check if this parameter should be NULL
+                    if param_index in self.null_param_indices:
+                        return exp.Null()
+                    # Renumber the parameter based on how many NULLs came before it
+                    nulls_before = sum(1 for idx in self.null_param_indices if idx < param_index)
+                    new_index = param_index - nulls_before + 1  # Convert back to 1-based
+                    return exp.Parameter(this=exp.Literal.number(new_index))
+                except (ValueError, IndexError):
+                    pass
+
+        # Handle placeholder nodes for other dialects
+        elif isinstance(node, exp.Placeholder):
+            # For placeholders, we need to track position
+            if self._parameter_index in self.null_param_indices:
+                self._parameter_index += 1
+                return exp.Null()
+            self._parameter_index += 1
+
+        return node

{sqlspec-0.13.1 → sqlspec-0.14.1}/sqlspec/adapters/aiosqlite/config.py

@@ -16,8 +16,6 @@ from sqlspec.typing import DictRow, Empty
 if TYPE_CHECKING:
     from typing import Literal
 
-    from sqlglot.dialects.dialect import DialectType
-
 
 __all__ = ("CONNECTION_FIELDS", "AiosqliteConfig")
 
@@ -34,21 +32,6 @@ class AiosqliteConfig(AsyncDatabaseConfig[AiosqliteConnection, None, AiosqliteDr
     Note: Aiosqlite doesn't support connection pooling, so pool_instance is always None.
     """
 
-    __slots__ = (
-        "_dialect",
-        "cached_statements",
-        "check_same_thread",
-        "database",
-        "default_row_type",
-        "detect_types",
-        "extras",
-        "isolation_level",
-        "pool_instance",
-        "statement_config",
-        "timeout",
-        "uri",
-    )
-
     is_async: ClassVar[bool] = True
     supports_connection_pooling: ClassVar[bool] = False
 
@@ -59,7 +42,7 @@ class AiosqliteConfig(AsyncDatabaseConfig[AiosqliteConnection, None, AiosqliteDr
     supported_parameter_styles: ClassVar[tuple[str, ...]] = ("qmark", "named_colon")
     """AIOSQLite supports ? (qmark) and :name (named_colon) parameter styles."""
 
-    preferred_parameter_style: ClassVar[str] = "qmark"
+    default_parameter_style: ClassVar[str] = "qmark"
     """AIOSQLite's native parameter style is ? (qmark)."""
 
     def __init__(
@@ -102,7 +85,6 @@ class AiosqliteConfig(AsyncDatabaseConfig[AiosqliteConnection, None, AiosqliteDr
         # Store other config
         self.statement_config = statement_config or SQLConfig()
         self.default_row_type = default_row_type
-        self._dialect: DialectType = None
 
         super().__init__()
 
@@ -179,7 +161,7 @@ class AiosqliteConfig(AsyncDatabaseConfig[AiosqliteConnection, None, AiosqliteDr
                 statement_config = replace(
                     statement_config,
                     allowed_parameter_styles=self.supported_parameter_styles,
-                    target_parameter_style=self.preferred_parameter_style,
+                    default_parameter_style=self.default_parameter_style,
                 )
             yield self.driver_type(connection=connection, config=statement_config)