velocity-python 0.0.109__py3-none-any.whl → 0.0.155__py3-none-any.whl

velocity/db/core/engine.py

@@ -1,7 +1,7 @@
 import inspect
-import sys
 import re
-import traceback
+import os
+from contextlib import contextmanager
 from functools import wraps
 from velocity.db import exceptions
 from velocity.db.core.transaction import Transaction
@@ -19,43 +19,12 @@ class Engine:
 
     MAX_RETRIES = 100
 
-    def __init__(self, driver, config, sql, connect_timeout=5):
+    def __init__(self, driver, config, sql, connect_timeout=5, schema_locked=False):
         self.__config = config
         self.__sql = sql
         self.__driver = driver
         self.__connect_timeout = connect_timeout
-        
-        # Set up error code mappings from the SQL class
-        self._setup_error_mappings()
-
-    def _setup_error_mappings(self):
-        """
-        Set up error code to exception class mappings from the SQL driver.
-        """
-        self.error_codes = {}
-        
-        # Map error codes to exception class names
-        sql_attrs = [
-            ('ApplicationErrorCodes', 'DbApplicationError'),
-            ('DatabaseMissingErrorCodes', 'DbDatabaseMissingError'),
-            ('TableMissingErrorCodes', 'DbTableMissingError'), 
-            ('ColumnMissingErrorCodes', 'DbColumnMissingError'),
-            ('ForeignKeyMissingErrorCodes', 'DbForeignKeyMissingError'),
-            ('ConnectionErrorCodes', 'DbConnectionError'),
-            ('DuplicateKeyErrorCodes', 'DbDuplicateKeyError'),
-            ('RetryTransactionCodes', 'DbRetryTransaction'),
-            ('TruncationErrorCodes', 'DbTruncationError'),
-            ('LockTimeoutErrorCodes', 'DbLockTimeoutError'),
-            ('DatabaseObjectExistsErrorCodes', 'DbObjectExistsError'),
-            ('DataIntegrityErrorCodes', 'DbDataIntegrityError')
-        ]
-        
-        for attr_name, exception_class in sql_attrs:
-            if hasattr(self.sql, attr_name):
-                codes = getattr(self.sql, attr_name)
-                if codes:  # Only add non-empty lists
-                    for code in codes:
-                        self.error_codes[str(code)] = exception_class
+        self.__schema_locked = schema_locked
 
     def __str__(self):
         return f"[{self.sql.server}] engine({self.config})"
@@ -208,18 +177,18 @@ class Engine:
                 while True:
                     try:
                         return function(*args, **kwds)
-                    except exceptions.DbRetryTransaction as e:
+                    except exceptions.DbRetryTransaction:
                         retry_count += 1
                         if retry_count > self.MAX_RETRIES:
                             raise
                         _tx.rollback()
-                    except exceptions.DbLockTimeoutError as e:
+                    except exceptions.DbLockTimeoutError:
                         lock_timeout_count += 1
                         if lock_timeout_count > self.MAX_RETRIES:
                             raise
                         _tx.rollback()
                         continue
-                    except:
+                    except Exception:
                         raise
         finally:
             setattr(_tx, "_exec_function_depth", depth)
@@ -239,6 +208,29 @@ class Engine:
     def sql(self):
         return self.__sql
 
+    @property
+    def schema_locked(self):
+        """Returns True if schema modifications are locked."""
+        return self.__schema_locked
+
+    def lock_schema(self):
+        """Lock schema to prevent automatic modifications."""
+        self.__schema_locked = True
+
+    def unlock_schema(self):
+        """Unlock schema to allow automatic modifications."""
+        self.__schema_locked = False
+
+    @contextmanager
+    def unlocked_schema(self):
+        """Temporarily unlock schema for automatic creation."""
+        original_state = self.__schema_locked
+        self.__schema_locked = False
+        try:
+            yield self
+        finally:
+            self.__schema_locked = original_state
+
     @property
     def version(self):
         """
@@ -359,833 +351,187 @@ class Engine:
 
     def process_error(self, exception, sql=None, parameters=None):
         """
-        Process database errors and raise appropriate velocity exceptions.
-        Enhanced for robustness with exception chaining and comprehensive error handling.
-        
-        Args:
-            exception: The original exception from the database driver
-            sql: The SQL statement that caused the error (optional)
-            parameters: The parameters passed to the SQL statement (optional)
-            
-        Raises:
-            The appropriate velocity exception with proper chaining
+        Central method to parse driver exceptions and re-raise them as our custom exceptions.
         """
         logger = logging.getLogger(__name__)
-        
-        # Enhanced logging with context - more readable format
-        sql_preview = sql[:100] + "..." if sql and len(sql) > 100 else sql or "None"
-        
-        logger.error(
-            f"🔴 Database Error Detected\n"
-            f"   Exception Type: {type(exception).__name__}\n"
-            f"   SQL Statement: {sql_preview}\n"
-            f"   Processing error for classification..."
-        )
-        
-        # Safely get error code and message with fallbacks
-        try:
-            # Try PostgreSQL-specific error code first, then use SQL driver's get_error method
-            error_code = getattr(exception, 'pgcode', None)
-            if not error_code and hasattr(self.sql, 'get_error'):
-                try:
-                    error_code, error_message_from_driver = self.sql.get_error(exception)
-                    if error_message_from_driver:
-                        error_message = error_message_from_driver
-                except Exception as get_error_exception:
-                    logger.warning(f"⚠️  SQL driver get_error failed: {get_error_exception}")
-                    error_code = None
-        except Exception as e:
-            logger.warning(f"⚠️  Unable to extract database error code: {e}")
-            error_code = None
-            
+
+        # If it's already a velocity exception, just re-raise it
+        if isinstance(exception, exceptions.DbException):
+            raise exception
+
+        # Get error code and message from the SQL driver
         try:
-            error_message = str(exception)
-        except Exception as e:
-            logger.warning(f"⚠️  Unable to convert exception to string: {e}")
-            error_message = f"<Error converting exception: {type(exception).__name__}>"
-        
-        # Primary error classification by error code
-        if error_code and hasattr(self, 'error_codes') and str(error_code) in self.error_codes:
-            error_class = self.error_codes[str(error_code)]
-            logger.info(f"✅ Successfully classified error: {error_code} → {error_class}")
-            try:
-                raise self._create_exception_with_chaining(
-                    error_class, error_message, exception, sql, parameters
-                )
-            except Exception as creation_error:
-                logger.error(f"❌ Failed to create {error_class} exception: {creation_error}")
-                # Fall through to regex classification
-        
-        # Secondary error classification by message patterns (regex fallback)
-        error_message_lower = error_message.lower()
-        
-        # Enhanced connection error patterns
-        connection_patterns = [
-            r'connection.*refused|could not connect',
-            r'network.*unreachable|network.*down',
-            r'broken pipe|connection.*broken',
-            r'timeout.*connection|connection.*timeout',
-            r'server.*closed.*connection|connection.*lost',
-            r'no route to host|host.*unreachable',
-            r'connection.*reset|reset.*connection'
-        ]
-        
-        # Enhanced duplicate key patterns  
-        duplicate_patterns = [
-            r'duplicate.*key.*value|unique.*constraint.*violated',
-            r'duplicate.*entry|key.*already.*exists',
-            r'violates.*unique.*constraint',
-            r'unique.*violation|constraint.*unique'
-        ]
-        
-        # Enhanced permission/authorization patterns
-        permission_patterns = [
-            r'permission.*denied|access.*denied|authorization.*failed',
-            r'insufficient.*privileges|privilege.*denied',
-            r'not.*authorized|unauthorized.*access',
-            r'authentication.*failed|login.*failed'
-        ]
-        
-        # Enhanced database/table not found patterns
-        not_found_patterns = [
-            r'database.*does.*not.*exist|unknown.*database',
-            r'table.*does.*not.*exist|relation.*does.*not.*exist',
-            r'no.*such.*database|database.*not.*found',
-            r'schema.*does.*not.*exist|unknown.*table'
-        ]
-        
-        # Enhanced column missing patterns
-        column_missing_patterns = [
-            r'column.*does.*not.*exist',
-            r'unknown.*column|column.*not.*found',
-            r'no.*such.*column|invalid.*column.*name'
-        ]
-        
-        # Enhanced syntax error patterns
-        syntax_patterns = [
-            r'syntax.*error|invalid.*syntax',
-            r'malformed.*query|bad.*sql.*grammar',
-            r'unexpected.*token|parse.*error'
-        ]
-        
-        # Enhanced deadlock/timeout patterns
-        deadlock_patterns = [
-            r'deadlock.*detected|lock.*timeout',
-            r'timeout.*waiting.*for.*lock|query.*timeout',
-            r'lock.*wait.*timeout|deadlock.*found'
-        ]
-        
-        # Comprehensive pattern matching with error class mapping
-        pattern_mappings = [
-            (connection_patterns, 'DbConnectionError'),
-            (duplicate_patterns, 'DbDuplicateKeyError'), 
-            (permission_patterns, 'DbPermissionError'),
-            (not_found_patterns, 'DbTableMissingError'),
-            (column_missing_patterns, 'DbColumnMissingError'),
-            (syntax_patterns, 'DbSyntaxError'),
-            (deadlock_patterns, 'DbDeadlockError')
-        ]
-        
-        # Apply pattern matching
-        for patterns, error_class in pattern_mappings:
-            for pattern in patterns:
-                try:
-                    if re.search(pattern, error_message_lower):
-                        logger.info(f"✅ Classified error by pattern match: '{pattern}' → {error_class}")
-                        raise self._create_exception_with_chaining(
-                            error_class, error_message, exception, sql, parameters
-                        )
-                except re.error as regex_error:
-                    logger.warning(f"⚠️  Regex pattern error for '{pattern}': {regex_error}")
-                    continue
-                except Exception as pattern_error:
-                    logger.error(f"❌ Error applying pattern '{pattern}': {pattern_error}")
-                    continue
-        
-        # Fallback: return generic database error with full context
-        available_codes = list(getattr(self, 'error_codes', {}).keys()) if hasattr(self, 'error_codes') else []
-        logger.warning(
-            f"⚠️  Unable to classify database error automatically\n"
-            f"   → Falling back to generic DatabaseError\n"
-            f"   → Error Code: {error_code or 'Unknown'}\n"
-            f"   → Available Classifications: {available_codes or 'None configured'}"
-        )
-        
-        raise self._create_exception_with_chaining(
-            'DatabaseError', error_message, exception, sql, parameters
-        )
-    
-    def _format_human_readable_error(self, error_class, message, original_exception, sql=None, parameters=None, format_type='console'):
-        """
-        Format a human-readable error message with proper context and formatting.
-        
-        Args:
-            error_class: The name of the exception class
-            message: The raw error message
-            original_exception: The original exception
-            sql: The SQL statement (optional)
-            parameters: The SQL parameters (optional)
-            format_type: 'console' for terminal output, 'email' for HTML email format
-            
-        Returns:
-            A nicely formatted, human-readable error message
-        """
-        if format_type == 'email':
-            return self._format_email_error(error_class, message, original_exception, sql, parameters)
-        else:
-            return self._format_console_error(error_class, message, original_exception, sql, parameters)
-    
-    def _format_console_error(self, error_class, message, original_exception, sql=None, parameters=None):
-        """
-        Format error message for console/terminal output with Unicode box drawing.
-        """
-        # Map error classes to user-friendly descriptions
-        error_descriptions = {
-            'DbColumnMissingError': 'Column Not Found',
-            'DbTableMissingError': 'Table Not Found', 
-            'DbDatabaseMissingError': 'Database Not Found',
-            'DbForeignKeyMissingError': 'Foreign Key Constraint Violation',
-            'DbDuplicateKeyError': 'Duplicate Key Violation',
-            'DbConnectionError': 'Database Connection Failed',
-            'DbDataIntegrityError': 'Data Integrity Violation',
-            'DbQueryError': 'Query Execution Error',
-            'DbTransactionError': 'Transaction Error',
-            'DbTruncationError': 'Data Truncation Error',
-            'DatabaseError': 'Database Error'
-        }
-        
-        # Get user-friendly error type
-        friendly_type = error_descriptions.get(error_class, error_class.replace('Db', '').replace('Error', ' Error'))
-        
-        # Clean up the original message
-        clean_message = str(message).strip()
-        
-        # Extract specific details from PostgreSQL errors
-        details = self._extract_error_details(original_exception, clean_message)
-        
-        # Build the formatted message
-        lines = []
-        lines.append(f"╭─ {friendly_type} ─" + "─" * max(0, 60 - len(friendly_type)))
-        lines.append("│")
-        
-        # Add the main error description
-        if details.get('description'):
-            lines.append(f"│ {details['description']}")
-        else:
-            lines.append(f"│ {clean_message}")
-        lines.append("│")
-        
-        # Add error code if available
-        error_code = getattr(original_exception, 'pgcode', None)
-        if error_code:
-            lines.append(f"│ Error Code: {error_code}")
-        
-        # Add specific details if available
-        if details.get('column'):
-            lines.append(f"│ Column: {details['column']}")
-        if details.get('table'):
-            lines.append(f"│ Table: {details['table']}")
-        if details.get('constraint'):
-            lines.append(f"│ Constraint: {details['constraint']}")
-        if details.get('hint'):
-            lines.append(f"│ Hint: {details['hint']}")
+            error_code, error_message = self.sql.get_error(exception)
+        except Exception:
+            error_code, error_message = None, str(exception)
+
+        msg = str(exception).strip().lower()
+
+        # Create enhanced error message with SQL query and context
+        enhanced_message = str(exception)
+        
+        # Add specific guidance for common WHERE clause errors
+        exception_str_lower = str(exception).lower()
+        if "argument of where must be type boolean" in exception_str_lower:
+            enhanced_message += (
+                "\n\n*** WHERE CLAUSE ERROR ***\n"
+                "This error typically occurs when a WHERE clause contains a bare value "
+                "instead of a proper boolean expression.\n"
+                "Common fixes:\n"
+                "  - Change WHERE 1001 to WHERE sys_id = 1001\n"
+                "  - Change WHERE {'column': value} format in dictionaries\n"
+                "  - Ensure string WHERE clauses are complete SQL expressions"
+            )
         
-        # Add SQL context if available
         if sql:
-            lines.append("│")
-            lines.append("│ SQL Statement:")
-            # Show complete SQL without truncation for debugging
-            for line in sql.split('\n'):
-                lines.append(f"│   {line.strip()}")
-        
-        # Add parameters if available
-        if parameters is not None:
-            lines.append("│")
-            lines.append(f"│ Parameters: {parameters}")
-        
-        # Add debugging section with copy-paste ready format
-        if sql or parameters is not None:
-            lines.append("│")
-            lines.append("│ ┌─ DEBUG COPY-PASTE SECTION ─────────────────────────────")
-            
-            if sql and parameters is not None:
-                # Format for direct copy-paste into database console
-                lines.append("│ │")
-                lines.append("│ │ Complete SQL with Parameters:")
-                lines.append("│ │ " + "─" * 45)
-                
-                # Show the raw SQL
-                lines.append("│ │ Raw SQL:")
-                for line in sql.split('\n'):
-                    lines.append(f"│ │   {line}")
-                
-                lines.append("│ │")
-                lines.append(f"│ │ Raw Parameters: {parameters}")
-                
-                # Try to create an executable version
-                lines.append("│ │")
-                lines.append("│ │ Executable Format (for PostgreSQL):")
-                lines.append("│ │ " + "─" * 35)
-                
-                try:
-                    # Create a version with parameters substituted for testing
-                    executable_sql = self._format_executable_sql(sql, parameters)
-                    for line in executable_sql.split('\n'):
-                        lines.append(f"│ │   {line}")
-                except Exception:
-                    lines.append("│ │   [Unable to format executable SQL]")
-                    for line in sql.split('\n'):
-                        lines.append(f"│ │   {line}")
-                    lines.append(f"│ │   -- Parameters: {parameters}")
-                
-            elif sql:
-                lines.append("│ │")
-                lines.append("│ │ SQL Statement (no parameters):")
-                lines.append("│ │ " + "─" * 30)
-                for line in sql.split('\n'):
-                    lines.append(f"│ │   {line}")
-            
-            lines.append("│ │")
-            lines.append("│ └─────────────────────────────────────────────────────────")
-        
-        # Add detailed call stack information for debugging
-        stack_info = self._extract_call_stack_info()
-        if stack_info:
-            lines.append("│")
-            lines.append("│ ┌─ CALL STACK ANALYSIS ──────────────────────────────────")
-            lines.append("│ │")
-            
-            if stack_info.get('top_level_call'):
-                lines.append("│ │ Top-Level Function (most helpful for debugging):")
-                lines.append("│ │ " + "─" * 48)
-                call = stack_info['top_level_call']
-                lines.append(f"│ │   Function: {call['function']}")
-                lines.append(f"│ │   File: {call['file']}")
-                lines.append(f"│ │   Line: {call['line']}")
-                if call.get('code'):
-                    lines.append(f"│ │   Code: {call['code'].strip()}")
-            
-            if stack_info.get('relevant_calls'):
-                lines.append("│ │")
-                lines.append("│ │ Relevant Call Chain (excluding middleware):")
-                lines.append("│ │ " + "─" * 44)
-                for i, call in enumerate(stack_info['relevant_calls'][:5], 1):  # Show top 5
-                    lines.append(f"│ │   {i}. {call['function']} in {call['file']}:{call['line']}")
-                    if call.get('code'):
-                        lines.append(f"│ │      → {call['code'].strip()}")
-            
-            if stack_info.get('lambda_context'):
-                lines.append("│ │")
-                lines.append("│ │ AWS Lambda Context:")
-                lines.append("│ │ " + "─" * 19)
-                for key, value in stack_info['lambda_context'].items():
-                    lines.append(f"│ │   {key}: {value}")
+            enhanced_message += (
+                f"\n\nSQL Query:\n{self._format_sql_with_params(sql, parameters)}"
+            )
             
-            lines.append("│ │")
-            lines.append("│ └─────────────────────────────────────────────────────────")
-        
-        lines.append("│")
-        lines.append("╰" + "─" * 70)
-        
-        return '\n'.join(lines)
+        # Add call stack context for better debugging
+        import traceback
+        stack_trace = traceback.format_stack()
+        # Get the last few frames that aren't in the error handling itself
+        relevant_frames = [frame for frame in stack_trace if 'process_error' not in frame and 'logging' not in frame][-3:]
+        if relevant_frames:
+            enhanced_message += "\n\nCall Context:\n" + "".join(relevant_frames)
+
+        # Format SQL for logging
+        formatted_sql_info = ""
+        if sql:
+            formatted_sql_info = f" sql={self._format_sql_with_params(sql, parameters)}"
+
+        # logger.warning(
+        #     "Database error caught. Attempting to transform: code=%s message=%s%s",
+        #     error_code,
+        #     error_message,
+        #     formatted_sql_info,
+        # )
+
+        # Direct error code mapping
+        if error_code in self.sql.ApplicationErrorCodes:
+            raise exceptions.DbApplicationError(enhanced_message) from exception
+        if error_code in self.sql.ColumnMissingErrorCodes:
+            raise exceptions.DbColumnMissingError(enhanced_message) from exception
+        if error_code in self.sql.TableMissingErrorCodes:
+            raise exceptions.DbTableMissingError(enhanced_message) from exception
+        if error_code in self.sql.DatabaseMissingErrorCodes:
+            raise exceptions.DbDatabaseMissingError(enhanced_message) from exception
+        if error_code in self.sql.ForeignKeyMissingErrorCodes:
+            raise exceptions.DbForeignKeyMissingError(enhanced_message) from exception
+        if error_code in self.sql.TruncationErrorCodes:
+            raise exceptions.DbTruncationError(enhanced_message) from exception
+        if error_code in self.sql.DataIntegrityErrorCodes:
+            raise exceptions.DbDataIntegrityError(enhanced_message) from exception
+        if error_code in self.sql.ConnectionErrorCodes:
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if error_code in self.sql.DuplicateKeyErrorCodes:
+            raise exceptions.DbDuplicateKeyError(enhanced_message) from exception
+        if error_code in self.sql.DatabaseObjectExistsErrorCodes:
+            raise exceptions.DbObjectExistsError(enhanced_message) from exception
+        if error_code in self.sql.LockTimeoutErrorCodes:
+            raise exceptions.DbLockTimeoutError(enhanced_message) from exception
+        if error_code in self.sql.RetryTransactionCodes:
+            raise exceptions.DbRetryTransaction(enhanced_message) from exception
+
+        # Regex-based fallback patterns
+        if re.search(r"key \(sys_id\)=\(\d+\) already exists.", msg, re.M):
+            raise exceptions.DbDuplicateKeyError(enhanced_message) from exception
+        if re.findall(r"database.*does not exist", msg, re.M):
+            raise exceptions.DbDatabaseMissingError(enhanced_message) from exception
+        if re.findall(r"no such database", msg, re.M):
+            raise exceptions.DbDatabaseMissingError(enhanced_message) from exception
+        if re.findall(r"already exists", msg, re.M):
+            raise exceptions.DbObjectExistsError(enhanced_message) from exception
+        if re.findall(r"server closed the connection unexpectedly", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if re.findall(r"no connection to the server", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if re.findall(r"connection timed out", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if re.findall(r"could not connect to server", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if re.findall(r"cannot connect to server", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if re.findall(r"connection already closed", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if re.findall(r"cursor already closed", msg, re.M):
+            raise exceptions.DbConnectionError(enhanced_message) from exception
+        if "no such table:" in msg:
+            raise exceptions.DbTableMissingError(enhanced_message) from exception
 
-    def _format_email_error(self, error_class, message, original_exception, sql=None, parameters=None):
-        """
-        Format error message for email delivery with HTML formatting.
-        """
-        # Map error classes to user-friendly descriptions
-        error_descriptions = {
-            'DbColumnMissingError': 'Column Not Found',
-            'DbTableMissingError': 'Table Not Found', 
-            'DbDatabaseMissingError': 'Database Not Found',
-            'DbForeignKeyMissingError': 'Foreign Key Constraint Violation',
-            'DbDuplicateKeyError': 'Duplicate Key Violation',
-            'DbConnectionError': 'Database Connection Failed',
-            'DbDataIntegrityError': 'Data Integrity Violation',
-            'DbQueryError': 'Query Execution Error',
-            'DbTransactionError': 'Transaction Error',
-            'DbTruncationError': 'Data Truncation Error',
-            'DatabaseError': 'Database Error'
-        }
-        
-        # Get user-friendly error type
-        friendly_type = error_descriptions.get(error_class, error_class.replace('Db', '').replace('Error', ' Error'))
-        
-        # Clean up the original message
-        clean_message = str(message).strip()
-        
-        # Extract specific details from PostgreSQL errors
-        details = self._extract_error_details(original_exception, clean_message)
-        
-        # Get error code
-        error_code = getattr(original_exception, 'pgcode', None)
-        
-        # Get stack info
-        stack_info = self._extract_call_stack_info()
-        
-        # Build HTML email format
-        html_parts = []
-        
-        # Email header
-        html_parts.append("""
-<html>
-<head>
-    <style>
-        body { font-family: 'Courier New', monospace; margin: 20px; }
-        .error-container { border: 2px solid #dc3545; border-radius: 8px; padding: 20px; background-color: #f8f9fa; }
-        .error-header { background-color: #dc3545; color: white; padding: 10px; border-radius: 5px; font-weight: bold; font-size: 16px; margin-bottom: 15px; }
-        .error-section { margin: 15px 0; padding: 10px; background-color: #ffffff; border-left: 4px solid #007bff; }
-        .section-title { font-weight: bold; color: #007bff; margin-bottom: 8px; }
-        .code-block { background-color: #f1f3f4; padding: 10px; border-radius: 4px; font-family: 'Courier New', monospace; margin: 5px 0; white-space: pre-wrap; }
-        .highlight { background-color: #fff3cd; padding: 2px 4px; border-radius: 3px; }
-        .stack-call { margin: 5px 0; padding: 5px; background-color: #e9ecef; border-radius: 3px; }
-        .copy-section { background-color: #d1ecf1; border: 1px solid #bee5eb; padding: 15px; border-radius: 5px; margin: 10px 0; }
-    </style>
-</head>
-<body>
-    <div class="error-container">
-""")
-        
-        # Error header
-        html_parts.append(f'        <div class="error-header">🚨 {friendly_type}</div>')
-        
-        # Main error description
-        description = details.get('description', clean_message)
-        html_parts.append(f'        <div class="error-section"><strong>{description}</strong></div>')
-        
-        # Error details section
-        if error_code or details.get('column') or details.get('table') or details.get('constraint'):
-            html_parts.append('        <div class="error-section">')
-            html_parts.append('            <div class="section-title">Error Details:</div>')
-            if error_code:
-                html_parts.append(f'            <div><strong>Error Code:</strong> <span class="highlight">{error_code}</span></div>')
-            if details.get('column'):
-                html_parts.append(f'            <div><strong>Column:</strong> <span class="highlight">{details["column"]}</span></div>')
-            if details.get('table'):
-                html_parts.append(f'            <div><strong>Table:</strong> <span class="highlight">{details["table"]}</span></div>')
-            if details.get('constraint'):
-                html_parts.append(f'            <div><strong>Constraint:</strong> <span class="highlight">{details["constraint"]}</span></div>')
-            if details.get('hint'):
-                html_parts.append(f'            <div><strong>Hint:</strong> {details["hint"]}</div>')
-            html_parts.append('        </div>')
-        
-        # SQL and Parameters section
-        if sql or parameters is not None:
-            html_parts.append('        <div class="copy-section">')
-            html_parts.append('            <div class="section-title">📋 Debug Information (Copy-Paste Ready)</div>')
-            
-            if sql:
-                html_parts.append('            <div><strong>SQL Statement:</strong></div>')
-                html_parts.append(f'            <div class="code-block">{self._html_escape(sql)}</div>')
-            
-            if parameters is not None:
-                html_parts.append(f'            <div><strong>Parameters:</strong> <code>{self._html_escape(str(parameters))}</code></div>')
-            
-            # Executable SQL
-            if sql and parameters is not None:
-                try:
-                    executable_sql = self._format_executable_sql(sql, parameters)
-                    html_parts.append('            <div><strong>Executable SQL (for testing):</strong></div>')
-                    html_parts.append(f'            <div class="code-block">{self._html_escape(executable_sql)}</div>')
-                except Exception:
-                    pass
-            
-            html_parts.append('        </div>')
-        
-        # Call stack section  
-        if stack_info and stack_info.get('top_level_call'):
-            html_parts.append('        <div class="error-section">')
-            html_parts.append('            <div class="section-title">🔍 Source Code Location</div>')
-            
-            call = stack_info['top_level_call']
-            html_parts.append('            <div class="stack-call">')
-            html_parts.append(f'                <strong>Function:</strong> {call["function"]}<br>')
-            html_parts.append(f'                <strong>File:</strong> {call["file"]}<br>')
-            html_parts.append(f'                <strong>Line:</strong> {call["line"]}')
-            if call.get('code'):
-                html_parts.append(f'<br>                <strong>Code:</strong> <code>{self._html_escape(call["code"].strip())}</code>')
-            html_parts.append('            </div>')
-            
-            # Show relevant call chain
-            if stack_info.get('relevant_calls') and len(stack_info['relevant_calls']) > 1:
-                html_parts.append('            <div><strong>Call Chain:</strong></div>')
-                for i, call in enumerate(stack_info['relevant_calls'][:4], 1):
-                    html_parts.append('            <div class="stack-call">')
-                    html_parts.append(f'                {i}. <strong>{call["function"]}</strong> in {call["file"]}:{call["line"]}')
-                    html_parts.append('            </div>')
-            
-            html_parts.append('        </div>')
-        
-        # Lambda context
-        if stack_info and stack_info.get('lambda_context'):
-            html_parts.append('        <div class="error-section">')
-            html_parts.append('            <div class="section-title">⚡ AWS Lambda Context</div>')
-            for key, value in stack_info['lambda_context'].items():
-                html_parts.append(f'            <div><strong>{key.title()}:</strong> {value}</div>')
-            html_parts.append('        </div>')
-        
-        # Email footer
-        html_parts.append("""
-    </div>
-</body>
-</html>
-""")
-        
-        return ''.join(html_parts)
-
-    def _html_escape(self, text):
-        """Escape HTML special characters."""
-        if not text:
-            return ""
-        return (str(text)
-                .replace('&', '&amp;')
-                .replace('<', '&lt;')
-                .replace('>', '&gt;')
-                .replace('"', '&quot;')
-                .replace("'", '&#x27;'))
-
-    def _format_executable_sql(self, sql, parameters):
+        logger.error(
+            "Unhandled/Unknown Error in engine.process_error",
+            exc_info=True,
+            extra={
+                "error_code": error_code,
+                "error_msg": error_message,
+                "sql_stmt": sql,
+                "sql_params": parameters,
+            },
+        )
+
+        # If we can't classify it, re-raise with enhanced message
+        raise type(exception)(enhanced_message) from exception
+
+    def _format_sql_with_params(self, sql, parameters):
         """
-        Format SQL with parameters substituted for easy copy-paste debugging.
-        
-        Args:
-            sql: The SQL statement with placeholders
-            parameters: The parameters to substitute
-            
-        Returns:
-            SQL statement with parameters properly formatted for execution
+        Format SQL query with parameters merged for easy copy-paste debugging.
         """
+        if not sql:
+            return "No SQL provided"
+
         if not parameters:
             return sql
-            
+
         try:
             # Handle different parameter formats
             if isinstance(parameters, (list, tuple)):
-                # For positional parameters (%s style)
-                formatted_sql = sql
-                
-                # Replace %s placeholders with properly formatted values
+                # Convert parameters to strings and handle None values
+                formatted_params = []
                 for param in parameters:
-                    if isinstance(param, str):
+                    if param is None:
+                        formatted_params.append("NULL")
+                    elif isinstance(param, str):
                         # Escape single quotes and wrap in quotes
-                        formatted_param = f"'{param.replace(chr(39), chr(39)+chr(39))}'"
-                    elif isinstance(param, (int, float)):
-                        formatted_param = str(param)
-                    elif param is None:
-                        formatted_param = 'NULL'
+                        escaped = param.replace("'", "''")
+                        formatted_params.append(f"'{escaped}'")
                     elif isinstance(param, bool):
-                        formatted_param = 'TRUE' if param else 'FALSE'
+                        formatted_params.append("TRUE" if param else "FALSE")
                     else:
-                        # For other types, try to convert to string and quote
-                        formatted_param = f"'{str(param).replace(chr(39), chr(39)+chr(39))}'"
-                    
-                    # Replace first occurrence of %s
-                    formatted_sql = formatted_sql.replace('%s', formatted_param, 1)
-                
+                        formatted_params.append(str(param))
+
+                # Replace %s placeholders with actual values
+                formatted_sql = sql
+                for param in formatted_params:
+                    formatted_sql = formatted_sql.replace("%s", param, 1)
+
                 return formatted_sql
-                
+
             elif isinstance(parameters, dict):
-                # For named parameters (%(name)s style)
+                # Handle named parameters
                 formatted_sql = sql
                 for key, value in parameters.items():
-                    placeholder = f'%({key})s'
-                    if isinstance(value, str):
-                        formatted_value = f"'{value.replace(chr(39), chr(39)+chr(39))}'"
-                    elif isinstance(value, (int, float)):
-                        formatted_value = str(value)
-                    elif value is None:
-                        formatted_value = 'NULL'
+                    if value is None:
+                        replacement = "NULL"
+                    elif isinstance(value, str):
+                        escaped = value.replace("'", "''")
+                        replacement = f"'{escaped}'"
                     elif isinstance(value, bool):
-                        formatted_value = 'TRUE' if value else 'FALSE'
+                        replacement = "TRUE" if value else "FALSE"
                     else:
-                        formatted_value = f"'{str(value).replace(chr(39), chr(39)+chr(39))}'"
-                    
-                    formatted_sql = formatted_sql.replace(placeholder, formatted_value)
-                
+                        replacement = str(value)
+
+                    # Replace %(key)s or :key patterns
+                    formatted_sql = formatted_sql.replace(f"%({key})s", replacement)
+                    formatted_sql = formatted_sql.replace(f":{key}", replacement)
+
                 return formatted_sql
-            
             else:
-                # Fallback: just append parameters as comment
                 return f"{sql}\n-- Parameters: {parameters}"
-                
-        except Exception:
-            # If formatting fails, return original with parameters as comment
-            return f"{sql}\n-- Parameters: {parameters}"
 
-    def _extract_call_stack_info(self):
-        """
-        Extract relevant call stack information for debugging, filtering out 
-        middleware and focusing on the most useful frames.
-        
-        Returns:
-            Dictionary with call stack analysis
-        """
-        import traceback
-        import os
-        
-        try:
-            # Get the current stack
-            stack = traceback.extract_stack()
-            
-            # Common middleware/decorator patterns to filter out
-            middleware_patterns = [
-                'decorator',
-                'wrapper',
-                'new_function',
-                'exec_function',
-                '_execute',
-                'process_error',
-                '_create_exception',
-                '_format_human_readable',
-                '__enter__',
-                '__exit__',
-                'contextlib',
-                'functools'
-            ]
-            
-            # Lambda/AWS specific patterns
-            lambda_patterns = [
-                'lambda_handler',
-                'handler',
-                'bootstrap',
-                'runtime'
-            ]
-            
-            relevant_calls = []
-            top_level_call = None
-            lambda_context = {}
-            
-            # Analyze stack frames from top to bottom (most recent first)
-            for frame in reversed(stack[:-4]):  # Skip the last few frames (this method, etc.)
-                file_path = frame.filename
-                function_name = frame.name
-                line_number = frame.lineno
-                code_line = frame.line or ""
-                
-                # Extract just the filename
-                filename = os.path.basename(file_path)
-                
-                # Skip internal Python and library frames
-                if any(skip in file_path.lower() for skip in [
-                    'python3', 'site-packages', '/usr/', '/opt/python',
-                    'psycopg2', 'boto3', 'botocore'
-                ]):
-                    continue
-                
-                # Capture Lambda context if found
-                if any(pattern in function_name.lower() for pattern in lambda_patterns):
-                    lambda_context.update({
-                        'handler': function_name,
-                        'file': filename,
-                        'line': line_number
-                    })
-                
-                # Skip middleware/decorator frames but keep track of meaningful ones
-                is_middleware = any(pattern in function_name.lower() for pattern in middleware_patterns)
-                
-                if not is_middleware:
-                    call_info = {
-                        'function': function_name,
-                        'file': filename,
-                        'line': line_number,
-                        'code': code_line,
-                        'full_path': file_path
-                    }
-                    
-                    relevant_calls.append(call_info)
-                    
-                    # The first non-middleware call is likely the most important
-                    if not top_level_call:
-                        # Look for application-level calls (not in velocity internals)
-                        if not any(internal in file_path for internal in [
-                            'velocity/db/', 'velocity/aws/', 'velocity/misc/'
-                        ]):
-                            top_level_call = call_info
-            
-            # If no clear top-level call found, use the first relevant call
-            if not top_level_call and relevant_calls:
-                top_level_call = relevant_calls[0]
-            
-            # Look for handler functions in the stack
-            handler_calls = [call for call in relevant_calls 
-                           if any(pattern in call['function'].lower() 
-                                for pattern in ['handler', 'main', 'process', 'action'])]
-            
-            if handler_calls and not top_level_call:
-                top_level_call = handler_calls[0]
-            
-            return {
-                'top_level_call': top_level_call,
-                'relevant_calls': relevant_calls,
-                'lambda_context': lambda_context if lambda_context else None
-            }
-            
-        except Exception:
-            # If stack analysis fails, return minimal info
-            return None
-
-    def _extract_error_details(self, exception, message):
-        """
-        Extract specific details from database errors for better formatting.
-        
-        Args:
-            exception: The original database exception
-            message: The error message string
-            
-        Returns:
-            Dictionary with extracted details
-        """
-        import re
-        
-        details = {}
-        
-        # PostgreSQL specific error parsing
-        if hasattr(exception, 'pgcode'):
-            # Column does not exist
-            if 'column' in message.lower() and 'does not exist' in message.lower():
-                match = re.search(r'column "([^"]+)" does not exist', message, re.IGNORECASE)
-                if match:
-                    details['column'] = match.group(1)
-                    details['description'] = f'The column "{match.group(1)}" was not found in the table.'
-            
-            # Table does not exist  
-            elif 'relation' in message.lower() and 'does not exist' in message.lower():
-                match = re.search(r'relation "([^"]+)" does not exist', message, re.IGNORECASE)
-                if match:
-                    details['table'] = match.group(1)
-                    details['description'] = f'The table "{match.group(1)}" was not found in the database.'
-            
-            # Foreign key violation
-            elif 'foreign key constraint' in message.lower():
-                match = re.search(r'violates foreign key constraint "([^"]+)"', message, re.IGNORECASE)
-                if match:
-                    details['constraint'] = match.group(1)
-                    details['description'] = 'A foreign key constraint was violated.'
-                    details['hint'] = 'Make sure the referenced record exists.'
-            
-            # Unique constraint violation
-            elif 'unique constraint' in message.lower() or 'duplicate key' in message.lower():
-                match = re.search(r'violates unique constraint "([^"]+)"', message, re.IGNORECASE)
-                if match:
-                    details['constraint'] = match.group(1)
-                    details['description'] = 'A unique constraint was violated (duplicate key).'
-                    details['hint'] = 'The value you are trying to insert already exists.'
-            
-            # Connection errors
-            elif any(term in message.lower() for term in ['connection', 'connect', 'server']):
-                details['description'] = 'Failed to connect to the database server.'
-                details['hint'] = 'Check your database connection settings and network connectivity.'
-            
-            # Data type errors
-            elif 'invalid input syntax' in message.lower():
-                details['description'] = 'Invalid data format provided.'
-                details['hint'] = 'Check that your data matches the expected format for the column type.'
-        
-        return details
-
-    def _create_exception_with_chaining(self, error_class, message, original_exception, sql=None, parameters=None, format_type=None):
-        """
-        Create a velocity exception with proper exception chaining and human-readable formatting.
-        
-        Args:
-            error_class: The name of the exception class to create
-            message: The error message
-            original_exception: The original exception to chain
-            sql: The SQL statement (optional)
-            parameters: The SQL parameters (optional)
-            format_type: 'console', 'email', or None (auto-detect)
-            
-        Returns:
-            The created exception with proper chaining and formatting
-        """
-        logger = logging.getLogger(__name__)
-        
-        try:
-            # Import the exception class dynamically
-            exception_module = __import__('velocity.db.exceptions', fromlist=[error_class])
-            ExceptionClass = getattr(exception_module, error_class)
-            
-            # Auto-detect format if not specified
-            if format_type is None:
-                format_type = self._detect_output_format()
-            
-            # Create human-readable, formatted message
-            formatted_message = self._format_human_readable_error(
-                error_class, message, original_exception, sql, parameters, format_type
+        except Exception as e:
+            # If formatting fails, return original SQL with parameters shown separately
+            return (
+                f"{sql}\n-- Parameters (formatting failed): {parameters}\n-- Error: {e}"
             )
-            
-            # For email format, also create a console version for logging
-            if format_type == 'email':
-                console_message = self._format_human_readable_error(
-                    error_class, message, original_exception, sql, parameters, 'console'
-                )
-                # Log the console version for server logs
-                logger.error(f"Database Error (Console Format):\n{console_message}")
-                
-                # Create custom exception with both formats
-                new_exception = ExceptionClass(formatted_message)
-                new_exception.console_format = console_message
-                new_exception.email_format = formatted_message
-            else:
-                new_exception = ExceptionClass(formatted_message)
-                
-            # Only set __cause__ if original_exception is not None and derives from BaseException
-            if isinstance(original_exception, BaseException):
-                new_exception.__cause__ = original_exception  # Preserve exception chain
-            
-            return new_exception
-            
-        except (ImportError, AttributeError) as e:
-            logger.error(f"Could not import exception class {error_class}: {e}")
-            # Fallback to generic database error
-            try:
-                exception_module = __import__('velocity.db.exceptions', fromlist=['DatabaseError'])
-                DatabaseError = getattr(exception_module, 'DatabaseError')
-                
-                # Auto-detect format if not specified for fallback too
-                if format_type is None:
-                    format_type = self._detect_output_format()
-                
-                # Still format the fallback nicely
-                formatted_message = self._format_human_readable_error(
-                    'DatabaseError', message, original_exception, sql, parameters, format_type
-                )
-                
-                fallback_exception = DatabaseError(formatted_message)
-                # Only set __cause__ if original_exception is not None and derives from BaseException
-                if isinstance(original_exception, BaseException):
-                    fallback_exception.__cause__ = original_exception
-                return fallback_exception
-            except Exception as fallback_error:
-                logger.critical(f"Failed to create fallback exception: {fallback_error}")
-                # Last resort: return the original exception
-                return original_exception
-
-    def _detect_output_format(self):
-        """
-        Detect whether we should use console or email formatting based on context.
-        
-        Returns:
-            'email' if in email/notification context, 'console' otherwise
-        """
-        import inspect
-        
-        # Look at the call stack for email-related functions
-        stack = inspect.stack()
-        
-        email_indicators = [
-            'email', 'mail', 'notification', 'alert', 'send', 'notify',
-            'smtp', 'message', 'recipient', 'subject', 'body'
-        ]
-        
-        for frame_info in stack:
-            function_name = frame_info.function.lower()
-            filename = frame_info.filename.lower()
-            
-            # Check if we're in an email-related context
-            if any(indicator in function_name or indicator in filename 
-                   for indicator in email_indicators):
-                return 'email'
-        
-        # Default to console format
-        return 'console'