feat(perf)!: parsing performance improvements (#349)

## Performance Changes

### Core Hotpath Optimizations
- String builder pattern for placeholder replacement 
- Native `pa.Table.from_pylist()` for Arrow dict-to-table conversion
- Column-oriented access with `zip(*cols)` transpose for batch-to-rows

### Driver & Serialization
- Batch-level type detection (check first row once, not per-row)
- Module-level singleton pattern for serializer fallbacks

### Caching Optimizations
- **Structural parameter fingerprinting**: Cache keys based on parameter STRUCTURE (keys, types) not VALUES
- blake2b hashing (50% faster than SHA256) for all cache keys

### Parse-Once Pipeline
- AST preservation through compilation pipeline
- Added `parsed_expression` field to `ParameterProcessingResult`

Author: cofin

pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.38.4"
+version = "0.39.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -240,7 +240,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.38.4"
+current_version = "0.39.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec/_serialization.py

@@ -105,6 +105,28 @@ def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         ...
 
 
+# Module-level singleton fallback serializers for performance
+# These avoid creating new instances on every fallback call in MsgspecSerializer
+_orjson_fallback: "OrjsonSerializer | None" = None
+_stdlib_fallback: "StandardLibSerializer | None" = None
+
+
+def _get_orjson_fallback() -> "OrjsonSerializer":
+    """Get singleton OrjsonSerializer instance for fallback use."""
+    global _orjson_fallback
+    if _orjson_fallback is None:
+        _orjson_fallback = OrjsonSerializer()
+    return _orjson_fallback
+
+
+def _get_stdlib_fallback() -> "StandardLibSerializer":
+    """Get singleton StandardLibSerializer instance for fallback use."""
+    global _stdlib_fallback
+    if _stdlib_fallback is None:
+        _stdlib_fallback = StandardLibSerializer()
+    return _stdlib_fallback
+
+
 class MsgspecSerializer(BaseJSONSerializer):
     """Msgspec-based JSON serializer."""
 
@@ -125,8 +147,8 @@ def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
             return self._encoder.encode(data).decode("utf-8")
         except (TypeError, ValueError):
             if ORJSON_INSTALLED:
-                return OrjsonSerializer().encode(data, as_bytes=as_bytes)
-            return StandardLibSerializer().encode(data, as_bytes=as_bytes)
+                return _get_orjson_fallback().encode(data, as_bytes=as_bytes)
+            return _get_stdlib_fallback().encode(data, as_bytes=as_bytes)
 
     def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         """Decode data using msgspec."""
@@ -136,16 +158,16 @@ def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
                     return self._decoder.decode(data)
                 except (TypeError, ValueError):
                     if ORJSON_INSTALLED:
-                        return OrjsonSerializer().decode(data, decode_bytes=decode_bytes)
-                    return StandardLibSerializer().decode(data, decode_bytes=decode_bytes)
+                        return _get_orjson_fallback().decode(data, decode_bytes=decode_bytes)
+                    return _get_stdlib_fallback().decode(data, decode_bytes=decode_bytes)
             return data
 
         try:
             return self._decoder.decode(data.encode("utf-8"))
         except (TypeError, ValueError):
             if ORJSON_INSTALLED:
-                return OrjsonSerializer().decode(data, decode_bytes=decode_bytes)
-            return StandardLibSerializer().decode(data, decode_bytes=decode_bytes)
+                return _get_orjson_fallback().decode(data, decode_bytes=decode_bytes)
+            return _get_stdlib_fallback().decode(data, decode_bytes=decode_bytes)
 
 
 class OrjsonSerializer(BaseJSONSerializer):

sqlspec/adapters/adbc/litestar/store.py

@@ -310,7 +310,39 @@ def _set(self, key: str, value: "str | bytes", expires_in: "int | timedelta | No
                 INSERT OR REPLACE INTO {self._table_name} (session_id, data, expires_at)
                 VALUES ({p1}, {p2}, {p3})
                 """
+            elif dialect in {"postgres", "postgresql"}:
+                # ADBC Arrow driver cannot infer type from Python None, causing 'na' type error.
+                # Use separate SQL statements for NULL vs non-NULL expires_at to avoid the issue.
+                if expires_at is None:
+                    sql = f"""
+                    INSERT INTO {self._table_name} (session_id, data, expires_at)
+                    VALUES ({p1}, {p2}, NULL)
+                    ON CONFLICT (session_id) DO UPDATE
+                    SET data = EXCLUDED.data, expires_at = NULL
+                    """
+                    with self._config.provide_session() as driver:
+                        driver.execute(sql, key, data)
+                        driver.commit()
+                    return
+                sql = f"""
+                INSERT INTO {self._table_name} (session_id, data, expires_at)
+                VALUES ({p1}, {p2}, {p3})
+                ON CONFLICT (session_id) DO UPDATE
+                SET data = EXCLUDED.data, expires_at = EXCLUDED.expires_at
+                """
             else:
+                # DuckDB: Same issue with Arrow 'na' type for None values
+                if expires_at is None:
+                    sql = f"""
+                    INSERT INTO {self._table_name} (session_id, data, expires_at)
+                    VALUES ({p1}, {p2}, NULL)
+                    ON CONFLICT (session_id) DO UPDATE
+                    SET data = EXCLUDED.data, expires_at = NULL
+                    """
+                    with self._config.provide_session() as driver:
+                        driver.execute(sql, key, data)
+                        driver.commit()
+                    return
                 sql = f"""
                 INSERT INTO {self._table_name} (session_id, data, expires_at)
                 VALUES ({p1}, {p2}, {p3})

sqlspec/adapters/pymysql/pool.py

@@ -161,12 +161,7 @@ def _close_thread_connection(self) -> None:
     @contextmanager
     def get_connection(self) -> "Generator[PyMysqlConnection, None, None]":
         connection = self._get_thread_connection()
-        try:
-            yield connection
-        finally:
-            with contextlib.suppress(Exception):
-                if connection.open and connection.get_autocommit() is False:
-                    connection.commit()
+        yield connection
 
     def close(self) -> None:
         self._close_thread_connection()

sqlspec/builder/_base.py

@@ -559,12 +559,17 @@ def _generate_builder_cache_key(self, config: "StatementConfig | None" = None) -
         if self._expression is None:
             self._expression = self._create_base_expression()
 
-        expr_sql: str = self._expression.sql() if self._expression else "None"
+        if self._expression:
+            expr_sql = self._expression.sql()
+            expr_hash = hashlib.blake2b(expr_sql.encode(), digest_size=8).hexdigest()
+        else:
+            expr_hash = "None"
+
         parameters_snapshot = sorted(self._parameters.items())
         parameters_hash = hashlib.sha256(str(parameters_snapshot).encode()).hexdigest()[:8]
 
         state_parts = [
-            f"expression:{expr_sql}",
+            f"expression_hash:{expr_hash}",
             f"parameters_hash:{parameters_hash}",
             f"ctes:{sorted(self._with_ctes.keys())}",
             f"dialect:{dialect_name}",

sqlspec/builder/_column.py

@@ -517,5 +517,5 @@ def desc(self) -> "exp.Ordered":
         return exp.Ordered(this=self._expression, desc=True)
 
     def __hash__(self) -> int:
-        """Hash based on the SQL expression."""
-        return hash(self._expression.sql())
+        """Hash based on the expression identity."""
+        return hash(id(self._expression))

sqlspec/core/cache.py

@@ -593,15 +593,16 @@ class CachedStatement:
 
     This class stores compiled SQL and parameters in an immutable format
     that can be safely shared between different parts of the system without
-    risk of mutation. Tuple parameters ensure no copying is needed.
+    risk of mutation. List parameters are preserved for execute_many operations
+    where drivers require list type.
     """
 
     __slots__ = ("compiled_sql", "expression", "parameters")
 
     def __init__(
         self,
         compiled_sql: str,
-        parameters: "tuple[Any, ...] | dict[str, Any] | None",
+        parameters: "tuple[Any, ...] | list[Any] | dict[str, Any] | None",
         expression: "exp.Expression | None",
     ) -> None:
         self.compiled_sql = compiled_sql

sqlspec/core/compiler.py

@@ -21,8 +21,9 @@
 from sqlspec.core.parameters import (
     ParameterProcessor,
     ParameterProfile,
-    fingerprint_parameters,
+    structural_fingerprint,
     validate_parameter_alignment,
+    value_fingerprint,
 )
 from sqlspec.utils.logging import get_logger, log_with_context
 from sqlspec.utils.type_guards import get_value_attribute
@@ -349,11 +350,26 @@ def compile(
         cache_key = self._make_cache_key(sql, parameters, is_many)
 
         if cache_key in self._cache:
-            result = self._cache[cache_key]
+            cached_result = self._cache[cache_key]
             del self._cache[cache_key]
-            self._cache[cache_key] = result
+            self._cache[cache_key] = cached_result
             self._cache_hits += 1
-            return result
+            # Structural fingerprinting means same SQL structure = same cache entry,
+            # but we must still process the caller's actual parameter values
+            dialect_str = str(self._config.dialect) if self._config.dialect else None
+            _, processed_params, _, _ = self._prepare_parameters(sql, parameters, is_many, dialect_str)
+            # Return cached compilation metadata with NEW parameters
+            return CompiledSQL(
+                compiled_sql=cached_result.compiled_sql,
+                execution_parameters=processed_params,
+                operation_type=cached_result.operation_type,
+                expression=cached_result.expression,
+                parameter_style=cached_result.parameter_style,
+                supports_many=cached_result.supports_many,
+                parameter_casts=cached_result.parameter_casts,
+                parameter_profile=cached_result.parameter_profile,
+                operation_profile=cached_result.operation_profile,
+            )
 
         self._cache_misses += 1
         result = self._compile_uncached(sql, parameters, is_many, expression)
@@ -602,13 +618,15 @@ def _finalize_compilation(
         if self._config.parameter_config.needs_static_script_compilation and processed_params is None:
             return processed_sql, processed_params, parameter_profile
         if ast_was_transformed and expression is not None:
+            # Pass the transformed expression through the pipeline to avoid re-parsing
             transformed_result = self._parameter_processor.process_for_execution(
                 sql=expression.sql(dialect=dialect_str),
                 parameters=parameters,
                 config=self._config.parameter_config,
                 dialect=dialect_str,
                 is_many=is_many,
                 wrap_types=self._config.enable_parameter_type_wrapping,
+                parsed_expression=expression,
             )
             final_sql = transformed_result.sql
             final_params = transformed_result.parameters
@@ -762,21 +780,28 @@ def _make_cache_key(self, sql: str, parameters: Any, is_many: bool = False) -> s
         Returns:
             Cache key string
         """
-
-        param_fingerprint = fingerprint_parameters(parameters)
+        # For static script compilation, parameter VALUES are embedded in the SQL string,
+        # so different values produce different compiled SQL. Must use value_fingerprint
+        # to avoid returning cached SQL with stale embedded values.
+        if self._config.parameter_config.needs_static_script_compilation:
+            param_fingerprint = value_fingerprint(parameters)
+        else:
+            # Use structural fingerprint (keys + types, not values) for better cache hit rates
+            param_fingerprint = structural_fingerprint(parameters, is_many)
         dialect_str = str(self._config.dialect) if self._config.dialect else None
-        param_style = self._config.parameter_config.default_parameter_style.value
-
-        hash_data = (
-            sql,
-            param_fingerprint,
-            param_style,
-            dialect_str,
-            self._config.enable_parsing,
-            self._config.enable_transformations,
-            is_many,
+        # Include both input and execution parameter styles to avoid cache collisions
+        # (e.g., MySQL asyncmy uses ? for input but %s for execution)
+        input_style = self._config.parameter_config.default_parameter_style.value
+        exec_style = (
+            self._config.parameter_config.default_execution_parameter_style.value
+            if self._config.parameter_config.default_execution_parameter_style
+            else input_style
         )
 
+        # Exclude enable_parsing and enable_transformations from hash_data as they are
+        # per-config static flags, not per-statement - they belong in pipeline key only
+        hash_data = (sql, param_fingerprint, input_style, exec_style, dialect_str, is_many)
+
         hash_str = hashlib.blake2b(repr(hash_data).encode("utf-8"), digest_size=8).hexdigest()
         return f"sql_{hash_str}"
 
@@ -924,7 +949,8 @@ def clear_cache(self) -> None:
 
     def _make_parse_cache_key(self, sql: str, dialect: "str | None") -> str:
         dialect_marker = dialect or "default"
-        hash_str = hashlib.sha256(f"{dialect_marker}:{sql}".encode()).hexdigest()[:16]
+        # Use blake2b instead of sha256 for faster hashing (~50% faster)
+        hash_str = hashlib.blake2b(f"{dialect_marker}:{sql}".encode(), digest_size=8).hexdigest()
         return f"parse_{hash_str}"
 
     @property

sqlspec/core/filters.py

@@ -582,8 +582,12 @@ def append_to_statement(self, statement: "SQL") -> "SQL":
         limit_placeholder = exp.Placeholder(this=limit_param_name)
         offset_placeholder = exp.Placeholder(this=offset_param_name)
 
+        # Prefer cached expression to avoid re-parsing
+        current_statement: exp.Expression
         if statement.statement_expression is not None:
             current_statement = statement.statement_expression.copy()
+        elif statement.raw_expression is not None:
+            current_statement = statement.raw_expression.copy()
         elif not statement.statement_config.enable_parsing:
             current_statement = exp.Select().from_(f"({statement.raw_sql})")
         else:
@@ -638,8 +642,12 @@ def append_to_statement(self, statement: "SQL") -> "SQL":
         col_expr = exp.column(self.field_name)
         order_expr = col_expr.desc() if converted_sort_order == "desc" else col_expr.asc()
 
+        # Prefer cached expression to avoid re-parsing
+        current_statement: exp.Expression
         if statement.statement_expression is not None:
             current_statement = statement.statement_expression.copy()
+        elif statement.raw_expression is not None:
+            current_statement = statement.raw_expression.copy()
         elif not statement.statement_config.enable_parsing:
             current_statement = exp.Select().from_(f"({statement.raw_sql})")
         else:

sqlspec/core/parameters/__init__.py

@@ -8,7 +8,7 @@
     validate_parameter_alignment,
 )
 from sqlspec.core.parameters._converter import ParameterConverter
-from sqlspec.core.parameters._processor import ParameterProcessor, fingerprint_parameters
+from sqlspec.core.parameters._processor import ParameterProcessor, structural_fingerprint, value_fingerprint
 from sqlspec.core.parameters._registry import (
     DRIVER_PARAMETER_PROFILES,
     build_statement_config_from_profile,
@@ -58,14 +58,15 @@
     "build_null_pruning_transform",
     "build_statement_config_from_profile",
     "collect_null_parameter_ordinals",
-    "fingerprint_parameters",
     "get_driver_profile",
     "is_iterable_parameters",
     "looks_like_execute_many",
     "normalize_parameter_key",
     "register_driver_profile",
     "replace_null_parameters_with_literals",
     "replace_placeholders_with_literals",
+    "structural_fingerprint",
     "validate_parameter_alignment",
+    "value_fingerprint",
     "wrap_with_type",
 )