sql-testing-library 0.6.0__tar.gz → 0.7.1__tar.gz

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.7.1 (2025-06-06)
+
+### Fix
+
+- **array**: array handling logic + sql logging improvement (#95)
+
+## 0.7.0 (2025-06-06)
+
+### Feat
+
+- **sqllogging**: added support for logging sql logs for debugging failed tests (#94)
+
 ## 0.6.0 (2025-06-05)
 
 ### Feat

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sql-testing-library
-Version: 0.6.0
+Version: 0.7.1
 Summary: A powerful Python framework for unit testing SQL queries across BigQuery, Snowflake, Redshift, Athena, and Trino with mock data
 License: MIT
 Keywords: sql,testing,unit-testing,mock-data,database-testing,bigquery,snowflake,redshift,athena,trino,data-engineering,etl-testing,sql-validation,query-testing
@@ -108,6 +108,7 @@ For more details on our journey and the engineering challenges we solved, read t
 - **CTE or Physical Tables**: Automatic fallback for query size limits
 - **Type-Safe Results**: Deserialize results to Pydantic models
 - **Pytest Integration**: Seamless testing with `@sql_test` decorator
+- **SQL Logging**: Comprehensive SQL logging with formatted output, error traces, and temp table queries
 
 ## Data Types Support
 

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/README.md

@@ -51,6 +51,7 @@ For more details on our journey and the engineering challenges we solved, read t
 - **CTE or Physical Tables**: Automatic fallback for query size limits
 - **Type-Safe Results**: Deserialize results to Pydantic models
 - **Pytest Integration**: Seamless testing with `@sql_test` decorator
+- **SQL Logging**: Comprehensive SQL logging with formatted output, error traces, and temp table queries
 
 ## Data Types Support
 

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "sql-testing-library"
-version = "0.6.0"
+version = "0.7.1"
 description = "A powerful Python framework for unit testing SQL queries across BigQuery, Snowflake, Redshift, Athena, and Trino with mock data"
 authors = ["Gurmeet Saran <gurmeetx@gmail.com>", "Kushal Thakkar <kushal.thakkar@gmail.com>"]
 maintainers = ["Gurmeet Saran <gurmeetx@gmail.com>", "Kushal Thakkar <kushal.thakkar@gmail.com>"]

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_adapters/athena.py

@@ -4,7 +4,7 @@ import logging
 import time
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, List, Optional, Type, Union, get_args
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union, get_args
 
 
 if TYPE_CHECKING:
@@ -136,6 +136,20 @@ class AthenaAdapter(DatabaseAdapter):
 
         return qualified_table_name
 
+    def create_temp_table_with_sql(self, mock_table: BaseMockTable) -> Tuple[str, str]:
+        """Create a temporary table and return both table name and SQL."""
+        timestamp = int(time.time() * 1000)
+        temp_table_name = f"temp_{mock_table.get_table_name()}_{timestamp}"
+        qualified_table_name = f"{self.database}.{temp_table_name}"
+
+        # Generate CTAS statement (CREATE TABLE AS SELECT)
+        ctas_sql = self._generate_ctas_sql(temp_table_name, mock_table)
+
+        # Execute CTAS query
+        self.execute_query(ctas_sql)
+
+        return qualified_table_name, ctas_sql
+
     def cleanup_temp_tables(self, table_names: List[str]) -> None:
         """Clean up temporary tables."""
         for full_table_name in table_names:

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_adapters/base.py

@@ -1,7 +1,7 @@
 """Base database adapter interface."""
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, List, Optional
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple
 
 
 if TYPE_CHECKING:
@@ -30,6 +30,15 @@ class DatabaseAdapter(ABC):
         """Create a temporary table with mock data. Returns temp table name."""
         pass
 
+    @abstractmethod
+    def create_temp_table_with_sql(self, mock_table: BaseMockTable) -> Tuple[str, str]:
+        """Create a temporary table and return both table name and SQL.
+
+        Returns:
+            Tuple of (temp_table_name, create_table_sql)
+        """
+        pass
+
     @abstractmethod
     def cleanup_temp_tables(self, table_names: List[str]) -> None:
         """Clean up temporary tables."""

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_adapters/bigquery.py

@@ -3,7 +3,7 @@
 import logging
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, List, Optional, Type, Union, get_args
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union, get_args
 
 
 if TYPE_CHECKING:
@@ -88,6 +88,54 @@ class BigQueryAdapter(DatabaseAdapter):
 
         return table_id
 
+    def create_temp_table_with_sql(self, mock_table: BaseMockTable) -> Tuple[str, str]:
+        """Create temporary table and return both table name and SQL."""
+        import time
+
+        temp_table_name = f"temp_{mock_table.get_table_name()}_{int(time.time() * 1000)}"
+        table_id = f"{self.project_id}.{self.dataset_id}.{temp_table_name}"
+
+        # Generate CREATE TABLE SQL
+        schema = self._get_bigquery_schema(mock_table)
+        column_defs = []
+        for field in schema:
+            column_defs.append(f"`{field.name}` {field.field_type}")
+
+        columns_sql = ",\n  ".join(column_defs)
+        create_sql = f"CREATE TABLE `{table_id}` (\n  {columns_sql}\n)"
+
+        # Get insert SQL for the data
+        df = mock_table.to_dataframe()
+        if not df.empty:
+            # Generate INSERT statement
+            values_rows = []
+            for _, row in df.iterrows():
+                values = []
+                for col in df.columns:
+                    value = row[col]
+                    col_type = mock_table.get_column_types().get(col, str)
+                    formatted_value = self.format_value_for_cte(value, col_type)
+                    values.append(formatted_value)
+                values_rows.append(f"({', '.join(values)})")
+
+            values_sql = ",\n".join(values_rows)
+            insert_sql = f"INSERT INTO `{table_id}` VALUES\n{values_sql}"
+            full_sql = f"{create_sql};\n\n{insert_sql};"
+        else:
+            full_sql = create_sql + ";"
+
+        # Actually create the table
+        table = bigquery.Table(table_id, schema=schema)
+        table = self.client.create_table(table)
+
+        # Insert data if any
+        if not df.empty:
+            job_config = bigquery.LoadJobConfig()
+            job = self.client.load_table_from_dataframe(df, table, job_config=job_config)
+            job.result()
+
+        return table_id, full_sql
+
     def cleanup_temp_tables(self, table_names: List[str]) -> None:
         """Delete temporary tables."""
         for table_name in table_names:
@@ -130,7 +178,19 @@ class BigQueryAdapter(DatabaseAdapter):
                 if non_none_types:
                     col_type = non_none_types[0]
 
-            bq_type = type_mapping.get(col_type, bigquery.enums.SqlTypeNames.STRING)
-            schema.append(bigquery.SchemaField(col_name, bq_type))
+            # Handle List/Array types
+            if hasattr(col_type, "__origin__") and col_type.__origin__ is list:
+                # Get the element type from List[T]
+                element_type = get_args(col_type)[0] if get_args(col_type) else str
+
+                # Map element type to BigQuery type
+                element_bq_type = type_mapping.get(element_type, bigquery.enums.SqlTypeNames.STRING)
+
+                # Create field with mode=REPEATED for arrays
+                schema.append(bigquery.SchemaField(col_name, element_bq_type, mode="REPEATED"))
+            else:
+                # Handle scalar types
+                bq_type = type_mapping.get(col_type, bigquery.enums.SqlTypeNames.STRING)
+                schema.append(bigquery.SchemaField(col_name, bq_type))
 
         return schema

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_adapters/redshift.py

@@ -3,7 +3,7 @@
 import time
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, List, Optional, Type, Union, get_args
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union, get_args
 
 
 if TYPE_CHECKING:
@@ -122,6 +122,20 @@ class RedshiftAdapter(DatabaseAdapter):
         # Return just the table name, no schema prefix needed for temp tables
         return temp_table_name
 
+    def create_temp_table_with_sql(self, mock_table: BaseMockTable) -> Tuple[str, str]:
+        """Create a temporary table and return both table name and SQL."""
+        timestamp = int(time.time() * 1000)
+        temp_table_name = f"temp_{mock_table.get_table_name()}_{timestamp}"
+
+        # Generate CTAS statement (CREATE TABLE AS SELECT)
+        ctas_sql = self._generate_ctas_sql(temp_table_name, mock_table)
+
+        # Execute CTAS query
+        self.execute_query(ctas_sql)
+
+        # Return just the table name and the SQL
+        return temp_table_name, ctas_sql
+
     def cleanup_temp_tables(self, table_names: List[str]) -> None:
         """Clean up temporary tables."""
         # Redshift temporary tables are automatically dropped at the end of the session

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_adapters/snowflake.py

@@ -4,7 +4,7 @@ import logging
 import time
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, List, Optional, Type, Union, get_args
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union, get_args
 
 
 if TYPE_CHECKING:
@@ -152,6 +152,27 @@ class SnowflakeAdapter(DatabaseAdapter):
 
         return qualified_table_name
 
+    def create_temp_table_with_sql(self, mock_table: BaseMockTable) -> Tuple[str, str]:
+        """Create a temporary table and return both table name and SQL."""
+        timestamp = int(time.time() * 1000)
+        temp_table_name = f"TEMP_{mock_table.get_table_name()}_{timestamp}"
+
+        # Use the adapter's configured database and schema for temporary tables
+        # This avoids permission issues with creating schemas in other databases
+        target_schema = self.schema
+
+        # For temporary tables, Snowflake doesn't support full database qualification
+        # Return schema.table format for temporary tables
+        qualified_table_name = f"{target_schema}.{temp_table_name}"
+
+        # Generate CTAS statement (CREATE TABLE AS SELECT)
+        ctas_sql = self._generate_ctas_sql(temp_table_name, mock_table, target_schema)
+
+        # Execute CTAS query
+        self.execute_query(ctas_sql)
+
+        return qualified_table_name, ctas_sql
+
     def cleanup_temp_tables(self, table_names: List[str]) -> None:
         """Clean up temporary tables."""
         for full_table_name in table_names:

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_adapters/trino.py

@@ -4,7 +4,7 @@ import logging
 import time
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type, Union, get_args
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Type, Union, get_args
 
 
 if TYPE_CHECKING:
@@ -132,6 +132,22 @@ class TrinoAdapter(DatabaseAdapter):
 
         return qualified_table_name
 
+    def create_temp_table_with_sql(self, mock_table: BaseMockTable) -> Tuple[str, str]:
+        """Create a temporary table and return both table name and SQL."""
+        timestamp = int(time.time() * 1000)
+        temp_table_name = f"temp_{mock_table.get_table_name()}_{timestamp}"
+
+        # In Trino, tables are qualified with catalog and schema
+        qualified_table_name = f"{self.catalog}.{self.schema}.{temp_table_name}"
+
+        # Generate CTAS statement (CREATE TABLE AS SELECT)
+        ctas_sql = self._generate_ctas_sql(temp_table_name, mock_table)
+
+        # Execute CTAS query
+        self.execute_query(ctas_sql)
+
+        return qualified_table_name, ctas_sql
+
     def cleanup_temp_tables(self, table_names: List[str]) -> None:
         """Clean up temporary tables."""
         for full_table_name in table_names:

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_core.py

@@ -1,5 +1,6 @@
 """Core SQL testing framework."""
 
+import os
 from dataclasses import dataclass
 from typing import (
     TYPE_CHECKING,
@@ -27,6 +28,7 @@ from ._exceptions import (
     TypeConversionError,
 )
 from ._mock_table import BaseMockTable
+from ._sql_logger import SQLLogger
 
 
 # Type for adapter types
@@ -34,6 +36,9 @@ AdapterType = Literal["bigquery", "athena", "redshift", "trino", "snowflake"]
 
 T = TypeVar("T")
 
+# Global storage for SQL execution data (used by pytest plugin)
+sql_test_execution_data: Dict[str, Dict[str, Any]] = {}
+
 
 @dataclass
 class SQLTestCase(Generic[T]):
@@ -48,6 +53,7 @@ class SQLTestCase(Generic[T]):
     use_physical_tables: bool = False
     description: Optional[str] = None
     adapter_type: Optional[AdapterType] = None
+    log_sql: Optional[bool] = None
     # Backward compatibility
     execution_database: Optional[str] = None
 
@@ -84,21 +90,34 @@ class SQLTestCase(Generic[T]):
 class SQLTestFramework:
     """Main framework for executing SQL tests."""
 
-    def __init__(self, adapter: DatabaseAdapter) -> None:
+    def __init__(self, adapter: DatabaseAdapter, sql_logger: Optional[SQLLogger] = None) -> None:
         self.adapter = adapter
         self.type_converter = self.adapter.get_type_converter()
         self.temp_tables: List[str] = []
+        self.sql_logger = sql_logger or SQLLogger()
 
-    def run_test(self, test_case: SQLTestCase[T]) -> List[T]:
+    def run_test(
+        self, test_case: SQLTestCase[T], test_context: Optional[Dict[str, Any]] = None
+    ) -> List[T]:
         """
         Execute a test case and return deserialized results.
 
         Args:
             test_case: The test case to execute
+            test_context: Optional context dictionary with test metadata
 
         Returns:
             List of result objects of type test_case.result_class
         """
+        import time
+
+        # Track execution time
+        start_time = time.time()
+        final_query = ""
+        error_message = None
+        row_count = None
+        temp_table_queries: List[str] = []  # Track temp table creation queries
+
         try:
             # Validate required fields
             if test_case.mock_tables is None:
@@ -130,7 +149,7 @@ class SQLTestFramework:
             if test_case.use_physical_tables:
                 # Create physical temporary tables
                 final_query = self._execute_with_physical_tables(
-                    test_case.query, table_mapping, test_case.mock_tables
+                    test_case.query, table_mapping, test_case.mock_tables, temp_table_queries
                 )
             else:
                 # Generate query with CTEs
@@ -150,8 +169,134 @@ class SQLTestFramework:
             # Execute query
             result_df = self.adapter.execute_query(final_query)
 
+            # Track row count
+            row_count = len(result_df) if result_df is not None else 0
+
             # Convert results to typed objects
-            return self._deserialize_results(result_df, test_case.result_class)
+            results = self._deserialize_results(result_df, test_case.result_class)
+
+            # Log SQL if enabled (success case)
+            execution_time = time.time() - start_time
+
+            # Store execution data for potential logging on test failure
+            if test_context:
+                test_id = test_context.get("test_id")
+                if test_id:
+                    sql_test_execution_data[test_id] = {
+                        "sql": final_query,
+                        "test_name": test_context.get("test_name", "unknown_test"),
+                        "test_class": test_context.get("test_class"),
+                        "test_file": test_context.get("test_file"),
+                        "metadata": {
+                            "query": test_case.query,
+                            "default_namespace": test_case.default_namespace,
+                            "mock_tables": test_case.mock_tables,
+                            "adapter_type": self.adapter.__class__.__name__.replace(
+                                "Adapter", ""
+                            ).lower(),
+                            "use_physical_tables": test_case.use_physical_tables,
+                            "execution_time": execution_time,
+                            "row_count": row_count,
+                            "error": None,
+                            "temp_table_queries": temp_table_queries,
+                        },
+                        "sql_logger": self.sql_logger,
+                        "log_sql": test_case.log_sql,
+                    }
+
+            if self.sql_logger.should_log(test_case.log_sql):
+                # Get test context info
+                test_name = (
+                    test_context.get("test_name", "unknown_test")
+                    if test_context
+                    else "unknown_test"
+                )
+                test_class = test_context.get("test_class") if test_context else None
+                test_file = test_context.get("test_file") if test_context else None
+
+                metadata = {
+                    "query": test_case.query,
+                    "default_namespace": test_case.default_namespace,
+                    "mock_tables": test_case.mock_tables,
+                    "adapter_type": self.adapter.get_sqlglot_dialect(),
+                    "adapter_name": self.adapter.__class__.__name__.replace("Adapter", "").lower(),
+                    "use_physical_tables": test_case.use_physical_tables,
+                    "execution_time": execution_time,
+                    "row_count": row_count,
+                    "error": None,
+                    "temp_table_queries": temp_table_queries,
+                }
+
+                # Log SQL immediately
+                log_path = self.sql_logger.log_sql(
+                    sql=final_query,
+                    test_name=test_name,
+                    test_class=test_class,
+                    test_file=test_file,
+                    failed=False,
+                    metadata=metadata,
+                )
+
+                # Print log location if environment variable is set
+                if os.environ.get("SQL_TEST_LOG_ALL", "").lower() in ("true", "1", "yes"):
+                    import sys
+
+                    print(f"\nSQL logged to: file://{log_path}", file=sys.stderr)  # noqa: T201
+                    sys.stderr.flush()
+
+            return results
+
+        except Exception as e:
+            # Store exception information for potential logging by pytest hook
+            execution_time = time.time() - start_time
+
+            # Capture full error details including traceback
+            import traceback
+
+            error_message = str(e)
+            error_traceback = traceback.format_exc()
+
+            # Store execution data for pytest hook to potentially log
+            if test_context and test_case.log_sql is not False:
+                test_id = test_context.get("test_id")
+                if test_id:
+                    # Update the execution data with error information
+                    if test_id in sql_test_execution_data:
+                        sql_test_execution_data[test_id]["metadata"]["error"] = error_message
+                        sql_test_execution_data[test_id]["metadata"]["error_traceback"] = (
+                            error_traceback
+                        )
+                        sql_test_execution_data[test_id]["metadata"]["execution_time"] = (
+                            execution_time
+                        )
+                        sql_test_execution_data[test_id]["metadata"]["row_count"] = row_count
+                    else:
+                        # If we haven't stored data yet (error happened early), store it now
+                        sql_test_execution_data[test_id] = {
+                            "sql": final_query if "final_query" in locals() else test_case.query,
+                            "test_name": test_context.get("test_name", "unknown_test"),
+                            "test_class": test_context.get("test_class"),
+                            "test_file": test_context.get("test_file"),
+                            "metadata": {
+                                "query": test_case.query,
+                                "default_namespace": test_case.default_namespace,
+                                "mock_tables": test_case.mock_tables,
+                                "adapter_type": self.adapter.get_sqlglot_dialect(),
+                                "adapter_name": self.adapter.__class__.__name__.replace(
+                                    "Adapter", ""
+                                ).lower(),
+                                "use_physical_tables": test_case.use_physical_tables,
+                                "execution_time": execution_time,
+                                "row_count": row_count,
+                                "error": error_message,
+                                "error_traceback": error_traceback,
+                                "temp_table_queries": temp_table_queries,
+                            },
+                            "sql_logger": self.sql_logger,
+                            "log_sql": test_case.log_sql,
+                        }
+
+            raise
 
         finally:
             # Cleanup any temporary tables
@@ -439,15 +584,48 @@ class SQLTestFramework:
         query: str,
         table_mapping: Dict[str, BaseMockTable],
         mock_tables: List[BaseMockTable],
+        temp_table_queries: List[str],
     ) -> str:
         """Execute query using physical temporary tables."""
         # Create physical tables
         replacement_mapping = {}
 
         for original_name, mock_table in table_mapping.items():
-            temp_table_name = self.adapter.create_temp_table(mock_table)
-            self.temp_tables.append(temp_table_name)
-            replacement_mapping[original_name] = temp_table_name
+            try:
+                # Check if adapter has method to get temp table SQL
+                if hasattr(self.adapter, "create_temp_table_with_sql"):
+                    temp_table_name, create_sql = self.adapter.create_temp_table_with_sql(
+                        mock_table
+                    )
+                    temp_table_queries.append(create_sql)
+                else:
+                    temp_table_name = self.adapter.create_temp_table(mock_table)
+                    # Try to generate approximate SQL for logging
+                    temp_table_queries.append(
+                        f"-- CREATE TEMP TABLE {temp_table_name} (SQL not captured)"
+                    )
+
+                self.temp_tables.append(temp_table_name)
+                replacement_mapping[original_name] = temp_table_name
+            except Exception:
+                # If table creation fails, still try to capture the SQL for debugging
+                if hasattr(self.adapter, "create_temp_table_with_sql") and hasattr(
+                    mock_table, "get_table_name"
+                ):
+                    try:
+                        temp_table_name, ctas_sql = self.adapter.create_temp_table_with_sql(
+                            mock_table
+                        )
+                        temp_table_queries.append(ctas_sql)
+                        replacement_mapping[original_name] = temp_table_name
+                    except Exception:
+                        # If even SQL generation fails, add a placeholder
+                        temp_table_queries.append(
+                            f"-- CREATE TEMP TABLE for {original_name} (SQL generation failed)"
+                        )
+                        replacement_mapping[original_name] = f"temp_{original_name}_failed"
+                # Re-raise the original exception
+                raise
 
         # Replace table names and return modified query
         return self._replace_table_names_in_query(query, replacement_mapping)

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_pytest_plugin.py

@@ -10,7 +10,7 @@ import pytest
 from _pytest.nodes import Item
 
 from ._adapters.base import DatabaseAdapter
-from ._core import AdapterType, SQLTestCase, SQLTestFramework
+from ._core import AdapterType, SQLTestCase, SQLTestFramework, sql_test_execution_data
 from ._mock_table import BaseMockTable
 
 
@@ -335,12 +335,16 @@ class SQLTestDecorator:
 # Global instance
 _sql_test_decorator = SQLTestDecorator()
 
+# Global SQL execution context for logging
+_sql_execution_context: Dict[str, Any] = {}
+
 
 def sql_test(
     mock_tables: Optional[List[BaseMockTable]] = None,
     result_class: Optional[Type[T]] = None,
     use_physical_tables: Optional[bool] = None,
     adapter_type: Optional[AdapterType] = None,
+    log_sql: Optional[bool] = None,
 ) -> Callable[[Callable[[], SQLTestCase[T]]], Callable[[], List[T]]]:
     """
     Decorator to mark a function as a SQL test.
@@ -360,6 +364,8 @@ def sql_test(
                      (e.g., 'bigquery', 'athena').
                      If provided, overrides adapter_type in SQLTestCase and uses config
                      from [sql_testing.{adapter_type}] section.
+        log_sql: Optional flag to log the generated SQL to a file.
+                 If provided, overrides log_sql in SQLTestCase.
     """
 
     def decorator(func: Callable[[], SQLTestCase[T]]) -> Callable[[], List[T]]:
@@ -396,15 +402,54 @@ def sql_test(
             if adapter_type is not None:
                 test_case.adapter_type = adapter_type
 
+            if log_sql is not None:
+                test_case.log_sql = log_sql
+
             # Get framework and execute test
             framework = _sql_test_decorator.get_framework(test_case.adapter_type)
-            results: List[T] = framework.run_test(test_case)
+
+            # Create test context for logging
+            test_context = {}
+
+            # Try to get test metadata from the current pytest context
+            import inspect
+
+            frame = inspect.currentframe()
+            while frame:
+                frame_locals = frame.f_locals
+                if "item" in frame_locals and hasattr(frame_locals["item"], "name"):
+                    item = frame_locals["item"]
+                    test_context["test_name"] = item.name
+                    test_context["test_class"] = item.cls.__name__ if item.cls else None
+                    test_context["test_file"] = (
+                        str(item.fspath) if hasattr(item, "fspath") else None
+                    )
+                    # Create a unique test ID
+                    test_context["test_id"] = str(id(item))
+                    break
+                frame = frame.f_back
+
+            # If we couldn't get test context from stack, try to get it from function name
+            if not test_context:
+                test_context["test_name"] = func.__name__
+                test_context["test_file"] = inspect.getfile(func) if func is not None else None
+                # Create a unique test ID
+                test_context["test_id"] = f"{func.__name__}_{id(func)}"
+
+            results: List[T] = framework.run_test(test_case, test_context)
 
             return results
 
         # Mark function as SQL test
         wrapper._sql_test_decorated = True  # type: ignore
         wrapper._original_func = func  # type: ignore
+        wrapper._decorator_params = {  # type: ignore
+            "mock_tables": mock_tables,
+            "result_class": result_class,
+            "use_physical_tables": use_physical_tables,
+            "adapter_type": adapter_type,
+            "log_sql": log_sql,
+        }
 
         return wrapper
 
@@ -449,3 +494,52 @@ def pytest_runtest_call(item: Item) -> None:
     else:
         # Use default pytest execution
         item.runtest()
+
+
+def pytest_runtest_makereport(item: Item, call: Any) -> None:
+    """Hook to log SQL when tests fail (including assertion failures)."""
+    # We want to log after the test call phase
+    if call.when == "call":
+        test_id = str(id(item))
+
+        if call.excinfo is not None:
+            # Test failed - check if we have SQL execution data for this test
+            if test_id in sql_test_execution_data:
+                data = sql_test_execution_data[test_id]
+                sql_logger = data["sql_logger"]
+                log_sql = data.get("log_sql")
+
+                # Only log if log_sql is not False
+                if log_sql is not False:
+                    # Capture the assertion error details
+                    import traceback
+
+                    metadata = data["metadata"].copy()
+                    # Update error info with the actual pytest error
+                    # (might be different from stored error)
+                    metadata["error"] = str(call.excinfo.value)
+                    metadata["error_traceback"] = "".join(
+                        traceback.format_exception(
+                            call.excinfo.type, call.excinfo.value, call.excinfo.tb
+                        )
+                    )
+
+                    # Log the SQL
+                    log_path = sql_logger.log_sql(
+                        sql=data["sql"],
+                        test_name=data["test_name"],
+                        test_class=data["test_class"],
+                        test_file=data["test_file"],
+                        failed=True,
+                        metadata=metadata,
+                    )
+
+                    # Print log location
+                    import sys
+
+                    print(f"\nSQL logged to: file://{log_path}", file=sys.stderr)  # noqa: T201
+                    sys.stderr.flush()
+
+        # Clean up the stored data after the test (whether it passed or failed)
+        if test_id in sql_test_execution_data:
+            del sql_test_execution_data[test_id]

sql_testing_library-0.7.1/src/sql_testing_library/_sql_logger.py

@@ -0,0 +1,385 @@
+"""SQL logging functionality for test cases."""
+
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from sqlglot import parse_one
+
+from ._mock_table import BaseMockTable
+
+
+class SQLLogger:
+    """Handles SQL logging for test cases."""
+
+    # Class variable to store the run directory for the current test session
+    _run_directory: Optional[Path] = None
+    _run_id: Optional[str] = None
+
+    def __init__(self, log_dir: Optional[str] = None) -> None:
+        """Initialize SQL logger.
+
+        Args:
+            log_dir: Directory to store SQL log files. If None, uses .sql_logs in project root.
+        """
+        if log_dir is None:
+            # Check environment variable first
+            env_log_dir = os.environ.get("SQL_TEST_LOG_DIR")
+            if env_log_dir:
+                self.log_dir = Path(env_log_dir)
+            else:
+                # Try to find the project root by looking for specific project files
+                current_path = Path.cwd()
+
+                # Look for definitive project root markers (in order of preference)
+                # These are files that typically only exist at project root
+                root_markers = ["pyproject.toml", "setup.py", "setup.cfg", "tox.ini"]
+
+                # Search up the directory tree for project root
+                project_root = None
+                search_path = current_path
+
+                while search_path != search_path.parent:
+                    # Check for root markers
+                    if any((search_path / marker).exists() for marker in root_markers):
+                        project_root = search_path
+                        break
+
+                    # Also check for .git directory (but not .git file which could be a submodule)
+                    if (search_path / ".git").is_dir():
+                        project_root = search_path
+                        break
+
+                    search_path = search_path.parent
+
+                # If we found a project root, use it; otherwise fall back to current directory
+                if project_root:
+                    self.log_dir = project_root / ".sql_logs"
+                else:
+                    # Fall back to current directory if project root not found
+                    self.log_dir = Path(".sql_logs")
+        else:
+            self.log_dir = Path(log_dir)
+
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        self._logged_files: List[str] = []
+
+    def _ensure_run_directory(self) -> Path:
+        """Ensure run directory exists, creating it if necessary.
+
+        Returns:
+            Path to the run directory
+        """
+        # Create run directory if not already created for this session
+        if SQLLogger._run_directory is None:
+            # Generate run ID with timestamp
+            timestamp = datetime.now().strftime("%Y%m%dT%H%M%S")
+            SQLLogger._run_id = f"runid_{timestamp}"
+            SQLLogger._run_directory = self.log_dir / SQLLogger._run_id
+            SQLLogger._run_directory.mkdir(parents=True, exist_ok=True)
+        return SQLLogger._run_directory
+
+    def should_log(self, log_sql: Optional[bool] = None) -> bool:
+        """Determine if SQL should be logged based on environment and parameters.
+
+        Args:
+            log_sql: Explicit parameter from test case
+
+        Returns:
+            True if SQL should be logged
+        """
+        # If explicitly set in test case, use that
+        if log_sql is not None:
+            return log_sql
+
+        # Check environment variable
+        return os.environ.get("SQL_TEST_LOG_ALL", "").lower() in ("true", "1", "yes")
+
+    def generate_filename(
+        self,
+        test_name: str,
+        test_class: Optional[str] = None,
+        test_file: Optional[str] = None,
+        failed: bool = False,
+    ) -> str:
+        """Generate a unique filename for the SQL log.
+
+        Args:
+            test_name: Name of the test function
+            test_class: Name of the test class (if any)
+            test_file: Path to the test file
+            failed: Whether the test failed
+
+        Returns:
+            Generated filename
+        """
+        # Clean test name for filesystem (including square brackets)
+        clean_name = re.sub(r'[<>:"/\\|?*\[\]]', "_", test_name)
+
+        # Build filename components
+        components = []
+
+        # Add test file name (without path and extension)
+        if test_file:
+            file_base = Path(test_file).stem
+            components.append(file_base)
+
+        # Add class name if present
+        if test_class:
+            clean_class = re.sub(r'[<>:"/\\|?*\[\]]', "_", test_class)
+            components.append(clean_class)
+
+        # Add test name
+        components.append(clean_name)
+
+        # Add status indicator
+        if failed:
+            components.append("FAILED")
+
+        # Add timestamp for uniqueness
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")[:-3]  # Milliseconds
+        components.append(timestamp)
+
+        # Join with double underscore for clarity
+        filename = "__".join(components) + ".sql"
+
+        return filename
+
+    def format_sql(self, sql: str, dialect: Optional[str] = None) -> str:
+        """Format SQL query for better readability.
+
+        Args:
+            sql: SQL query to format
+            dialect: SQL dialect (e.g., 'bigquery', 'athena')
+
+        Returns:
+            Formatted SQL
+        """
+        try:
+            # Parse and format using sqlglot
+            parsed = parse_one(sql, dialect=dialect)
+            # IMPORTANT: Pass dialect to sql() to preserve dialect-specific syntax
+            formatted = parsed.sql(pretty=True, pad=2, dialect=dialect)
+            return formatted
+        except Exception:
+            # If formatting fails, return original
+            return sql
+
+    def create_metadata_header(
+        self,
+        test_name: str,
+        test_class: Optional[str] = None,
+        test_file: Optional[str] = None,
+        query: str = "",
+        default_namespace: Optional[str] = None,
+        mock_tables: Optional[List[BaseMockTable]] = None,
+        adapter_type: Optional[str] = None,
+        use_physical_tables: bool = False,
+        execution_time: Optional[float] = None,
+        row_count: Optional[int] = None,
+        error: Optional[str] = None,
+        error_traceback: Optional[str] = None,
+        temp_table_queries: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Create a metadata header for the SQL file.
+
+        Returns:
+            Formatted metadata header as SQL comments
+        """
+        lines = [
+            "-- SQL Test Case Log",
+            "-- " + "=" * 78,
+            f"-- Generated: {datetime.now().isoformat()}",
+            f"-- Run ID: {SQLLogger._run_id}",
+            f"-- Test Name: {test_name}",
+        ]
+
+        if test_class:
+            lines.append(f"-- Test Class: {test_class}")
+
+        if test_file:
+            lines.append(f"-- Test File: {test_file}")
+
+        if adapter_type:
+            lines.append(f"-- Adapter: {adapter_type}")
+
+        # Show adapter name if different from sqlglot dialect
+        adapter_name = kwargs.get("adapter_name")
+        if adapter_name and adapter_name != adapter_type:
+            lines.append(f"-- Database: {adapter_name}")
+
+        if default_namespace:
+            lines.append(f"-- Default Namespace: {default_namespace}")
+
+        lines.append(f"-- Use Physical Tables: {use_physical_tables}")
+
+        if execution_time is not None:
+            lines.append(f"-- Execution Time: {execution_time:.3f} seconds")
+
+        if row_count is not None:
+            lines.append(f"-- Result Rows: {row_count}")
+
+        if error:
+            lines.extend(
+                [
+                    "-- Status: FAILED",
+                    "-- Error:",
+                ]
+            )
+            for line in error.strip().split("\n"):
+                lines.append(f"-- {line}")
+
+            # Add full error traceback if available
+            if error_traceback:
+                lines.extend(
+                    [
+                        "",
+                        "-- Full Error Details:",
+                        "-- " + "-" * 78,
+                    ]
+                )
+                # Add each line of the traceback as a SQL comment
+                for line in error_traceback.strip().split("\n"):
+                    lines.append(f"-- {line}")
+        else:
+            lines.append("-- Status: SUCCESS")
+
+        # Add mock tables information
+        if mock_tables:
+            lines.extend(
+                [
+                    "",
+                    "-- Mock Tables:",
+                    "-- " + "-" * 78,
+                ]
+            )
+            for table in mock_tables:
+                lines.append(f"-- Table: {table.get_table_name()}")
+                # Get row count from data
+                if hasattr(table, "data") and table.data:
+                    lines.append(f"--   Rows: {len(table.data)}")
+                # Get column names from first row or column types
+                if hasattr(table, "get_column_types"):
+                    columns = list(table.get_column_types().keys())
+                    if columns:
+                        lines.append(f"--   Columns: {', '.join(columns)}")
+
+        # Add original query
+        lines.extend(
+            [
+                "",
+                "-- Original Query:",
+                "-- " + "-" * 78,
+            ]
+        )
+        # Comment out each line of the original query
+        for line in query.split("\n"):
+            lines.append(f"-- {line}")
+
+        # Add temp table queries if physical tables were used
+        if use_physical_tables and temp_table_queries:
+            lines.extend(
+                [
+                    "",
+                    "-- Temporary Table Creation Queries:",
+                    "-- " + "-" * 78,
+                    "",
+                ]
+            )
+            for i, temp_query in enumerate(temp_table_queries, 1):
+                lines.append(f"-- Query {i}:")
+                lines.append("")
+                # Format the temp table SQL
+                formatted_temp_sql = self.format_sql(temp_query, dialect=adapter_type)
+                lines.append(formatted_temp_sql)
+                lines.append("")
+
+        lines.extend(
+            [
+                "",
+                "-- Transformed Query:",
+                "-- " + "=" * 78,
+                "",
+            ]
+        )
+
+        return "\n".join(lines)
+
+    def log_sql(
+        self,
+        sql: str,
+        test_name: str,
+        test_class: Optional[str] = None,
+        test_file: Optional[str] = None,
+        failed: bool = False,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Log SQL to a file and return the file path.
+
+        Args:
+            sql: The transformed SQL query to log
+            test_name: Name of the test
+            test_class: Test class name
+            test_file: Test file path
+            failed: Whether the test failed
+            metadata: Additional metadata to include
+
+        Returns:
+            Path to the created SQL file
+        """
+        # Generate filename
+        filename = self.generate_filename(test_name, test_class, test_file, failed)
+
+        # Ensure run directory exists (lazy creation)
+        run_directory = self._ensure_run_directory()
+        filepath = run_directory / filename
+
+        # Prepare metadata
+        if metadata is None:
+            metadata = {}
+
+        # Create header
+        header = self.create_metadata_header(
+            test_name=test_name, test_class=test_class, test_file=test_file, **metadata
+        )
+
+        # Format SQL
+        dialect = metadata.get("adapter_type")
+        formatted_sql = self.format_sql(sql, dialect)
+
+        # Write to file
+        content = header + formatted_sql
+        filepath.write_text(content, encoding="utf-8")
+
+        # Track logged file
+        self._logged_files.append(str(filepath))
+
+        # Return absolute path for clickable URLs
+        return str(filepath.absolute())
+
+    def get_logged_files(self) -> List[str]:
+        """Get list of files logged in this session."""
+        return self._logged_files.copy()
+
+    def clear_logged_files(self) -> None:
+        """Clear the list of logged files."""
+        self._logged_files = []
+
+    @classmethod
+    def get_run_directory(cls) -> Optional[Path]:
+        """Get the current run directory."""
+        return cls._run_directory
+
+    @classmethod
+    def get_run_id(cls) -> Optional[str]:
+        """Get the current run ID."""
+        return cls._run_id
+
+    @classmethod
+    def reset_run_directory(cls) -> None:
+        """Reset the run directory (useful for testing)."""
+        cls._run_directory = None
+        cls._run_id = None

{sql_testing_library-0.6.0 → sql_testing_library-0.7.1}/src/sql_testing_library/_sql_utils.py

@@ -82,6 +82,7 @@ def format_sql_value(value: Any, column_type: Type, dialect: str = "standard") -
     """
     from datetime import date, datetime
     from decimal import Decimal
+    from typing import get_args
 
     import pandas as pd
 
@@ -89,6 +90,42 @@ def format_sql_value(value: Any, column_type: Type, dialect: str = "standard") -
     # Note: pd.isna() doesn't work on lists/arrays, so check for None first
     # and only use pd.isna() on scalar values
     if value is None or (not isinstance(value, (list, tuple)) and pd.isna(value)):
+        # Check if column_type is a List type
+        if hasattr(column_type, "__origin__") and column_type.__origin__ is list:
+            # Get the element type from List[T]
+            element_type = get_args(column_type)[0] if get_args(column_type) else str
+
+            if dialect in ("athena", "trino"):
+                # Map Python types to SQL types for array elements
+                if element_type == Decimal:
+                    sql_element_type = "DECIMAL(38,9)"
+                elif element_type is int:
+                    sql_element_type = "INTEGER" if dialect == "athena" else "BIGINT"
+                elif element_type is float:
+                    sql_element_type = "DOUBLE"
+                elif element_type is bool:
+                    sql_element_type = "BOOLEAN"
+                elif element_type is date:
+                    sql_element_type = "DATE"
+                elif element_type == datetime:
+                    sql_element_type = "TIMESTAMP"
+                else:
+                    sql_element_type = "VARCHAR"
+
+                return f"CAST(NULL AS ARRAY({sql_element_type}))"
+            elif dialect == "bigquery":
+                # BigQuery doesn't need explicit NULL array casting
+                return "NULL"
+            elif dialect == "redshift":
+                # Redshift SUPER type handles NULL arrays
+                return "NULL::SUPER"
+            elif dialect == "snowflake":
+                # Snowflake VARIANT type handles NULL arrays
+                return "NULL::VARIANT"
+            else:
+                return "NULL"
+
+        # Handle non-array NULL values
         if dialect == "redshift":
             # Redshift needs type-specific NULL casting
             if column_type == Decimal: