feat: more granular exception mapping (#330)

- Introduced new exception classes: PermissionDeniedError, ConnectionTimeoutError, DeadlockError, and QueryTimeoutError to better categorize specific error scenarios.
- Updated create_mapped_exception functions in various adapters (BigQuery, DuckDB, MySQL, OracleDB, PostgreSQL, PyMySQL, Spanner, SQLite) to utilize the new exception classes for improved error handling.
- Enhanced error mapping logic to prioritize specific error codes and messages, ensuring more accurate exception classification.
- Added SQLSTATE to exception mapping for better database-agnostic error translation.
- Improved documentation for new exceptions and their use cases.

Author: cofin

pyproject.toml

@@ -13,7 +13,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.37.1"
+version = "0.38.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -182,6 +182,7 @@ exclude = [
 include = [
   "sqlspec/core/**/*.py",                  # Core module
   "sqlspec/builder/**/*.py",               # Builder module
+  "sqlspec/exceptions.py",                 # Exceptions module
   "sqlspec/loader.py",                     # Loader module
   "sqlspec/observability/**/*.py",         # Observability utilities
   "sqlspec/driver/**/*.py",                # Driver module
@@ -222,7 +223,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.37.1"
+current_version = "0.38.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec/adapters/adbc/core.py

@@ -15,15 +15,17 @@
 from sqlspec.exceptions import (
     CheckViolationError,
     DatabaseConnectionError,
-    DataError,
+    DeadlockError,
     ForeignKeyViolationError,
     ImproperConfigurationError,
     IntegrityError,
     NotNullViolationError,
+    PermissionDeniedError,
+    QueryTimeoutError,
     SQLParsingError,
     SQLSpecError,
-    TransactionError,
     UniqueViolationError,
+    map_sqlstate_to_exception,
 )
 from sqlspec.typing import Empty
 from sqlspec.utils.module_loader import import_string
@@ -424,15 +426,22 @@ def create_mapped_exception(error: Any) -> SQLSpecError:
     raising. This pattern is more robust for use in __exit__ handlers and
     avoids issues with exception control flow in different Python versions.
 
+    Mapping priority:
+    1. SQLSTATE codes (most reliable for ADBC drivers)
+    2. Error message patterns
+    3. Default SQLSpecError fallback
+
     Args:
         error: The ADBC exception to map
 
     Returns:
         A SQLSpec exception that wraps the original error
     """
-    sqlstate = error.sqlstate if has_sqlstate(error) and error.sqlstate is not None else None
+    sqlstate_attr = error.sqlstate if has_sqlstate(error) else None
+    sqlstate = sqlstate_attr if sqlstate_attr is not None else None
 
     if sqlstate:
+        # Use centralized SQLSTATE mapping for specific codes
         if sqlstate == "23505":
             return _create_adbc_error(error, UniqueViolationError, "unique constraint violation")
         if sqlstate == "23503":
@@ -441,20 +450,36 @@ def create_mapped_exception(error: Any) -> SQLSpecError:
             return _create_adbc_error(error, NotNullViolationError, "not-null constraint violation")
         if sqlstate == "23514":
             return _create_adbc_error(error, CheckViolationError, "check constraint violation")
-        if sqlstate.startswith("23"):
-            return _create_adbc_error(error, IntegrityError, "integrity constraint violation")
-        if sqlstate.startswith("42"):
-            return _create_adbc_error(error, SQLParsingError, "SQL parsing error")
-        if sqlstate.startswith("08"):
-            return _create_adbc_error(error, DatabaseConnectionError, "connection error")
-        if sqlstate.startswith("40"):
-            return _create_adbc_error(error, TransactionError, "transaction error")
-        if sqlstate.startswith("22"):
-            return _create_adbc_error(error, DataError, "data error")
+
+        # Deadlock and serialization errors
+        if sqlstate == "40P01":
+            return _create_adbc_error(error, DeadlockError, "deadlock detected")
+        if sqlstate == "40001":
+            return _create_adbc_error(error, DeadlockError, "serialization failure")
+
+        # Query timeout/cancellation
+        if sqlstate == "57014":
+            return _create_adbc_error(error, QueryTimeoutError, "query canceled")
+
+        # Permission errors
+        if sqlstate == "42501":
+            return _create_adbc_error(error, PermissionDeniedError, "insufficient privilege")
+        if sqlstate == "28000":
+            return _create_adbc_error(error, PermissionDeniedError, "invalid authorization")
+
+        # Use centralized mapping for SQLSTATE class prefixes
+        exc_class = map_sqlstate_to_exception(sqlstate)
+        if exc_class is not None and exc_class is not SQLSpecError:
+            description = _get_sqlstate_description(sqlstate)
+            return _create_adbc_error(error, exc_class, description)
+
+        # Fallback for unmapped SQLSTATE codes
         return _create_adbc_error(error, SQLSpecError, "database error")
 
+    # Message-based fallback when no SQLSTATE is available
     error_msg = str(error).lower()
 
+    # Constraint violations
     if "unique" in error_msg or "duplicate" in error_msg:
         return _create_adbc_error(error, UniqueViolationError, "unique constraint violation")
     if "foreign key" in error_msg:
@@ -465,13 +490,53 @@ def create_mapped_exception(error: Any) -> SQLSpecError:
         return _create_adbc_error(error, CheckViolationError, "check constraint violation")
     if "constraint" in error_msg:
         return _create_adbc_error(error, IntegrityError, "integrity constraint violation")
+
+    # Deadlock/lock patterns
+    if "deadlock" in error_msg:
+        return _create_adbc_error(error, DeadlockError, "deadlock detected")
+    if "serialization" in error_msg or "concurrent update" in error_msg:
+        return _create_adbc_error(error, DeadlockError, "serialization failure")
+
+    # Timeout/cancellation patterns
+    if "timeout" in error_msg or "cancel" in error_msg or "interrupt" in error_msg:
+        return _create_adbc_error(error, QueryTimeoutError, "query timeout")
+
+    # Permission patterns
+    if "permission" in error_msg or "denied" in error_msg or "unauthorized" in error_msg:
+        return _create_adbc_error(error, PermissionDeniedError, "permission denied")
+
+    # Syntax errors
     if "syntax" in error_msg:
         return _create_adbc_error(error, SQLParsingError, "SQL parsing error")
+
+    # Connection errors
     if "connection" in error_msg or "connect" in error_msg:
         return _create_adbc_error(error, DatabaseConnectionError, "connection error")
+
     return _create_adbc_error(error, SQLSpecError, "database error")
 
 
+_SQLSTATE_CLASS_CODE_LEN = 2
+
+# Module-level SQLSTATE descriptions (mypyc optimization - avoid dict creation per call)
+_SQLSTATE_DESCRIPTIONS: dict[str, str] = {
+    "23": "integrity constraint violation",
+    "40": "transaction error",
+    "42": "SQL syntax error",
+    "08": "connection error",
+    "22": "data error",
+    "28": "authorization error",
+    "57": "operational error",
+    "02": "no data",
+}
+
+
+def _get_sqlstate_description(sqlstate: str) -> str:
+    """Get a human-readable description for a SQLSTATE code class."""
+    class_code = sqlstate[:_SQLSTATE_CLASS_CODE_LEN] if len(sqlstate) >= _SQLSTATE_CLASS_CODE_LEN else sqlstate
+    return _SQLSTATE_DESCRIPTIONS.get(class_code, "database error")
+
+
 def _identity(value: Any) -> Any:
     return value
 

sqlspec/adapters/asyncmy/core.py

@@ -5,11 +5,15 @@
 from sqlspec.core import DriverParameterProfile, ParameterStyle, StatementConfig, build_statement_config_from_profile
 from sqlspec.exceptions import (
     CheckViolationError,
+    ConnectionTimeoutError,
     DatabaseConnectionError,
     DataError,
+    DeadlockError,
     ForeignKeyViolationError,
     IntegrityError,
     NotNullViolationError,
+    PermissionDeniedError,
+    QueryTimeoutError,
     SQLParsingError,
     SQLSpecError,
     TransactionError,
@@ -38,10 +42,27 @@
     "resolve_rowcount",
 )
 
+# MySQL error codes for constraint violations
 MYSQL_ER_DUP_ENTRY = 1062
 MYSQL_ER_NO_DEFAULT_FOR_FIELD = 1364
 MYSQL_ER_CHECK_CONSTRAINT_VIOLATED = 3819
 
+# MySQL error codes for permission/access errors
+MYSQL_ER_DBACCESS_DENIED = 1044
+MYSQL_ER_ACCESS_DENIED = 1045
+MYSQL_ER_TABLEACCESS_DENIED = 1142
+
+# MySQL error codes for transaction errors
+MYSQL_ER_LOCK_WAIT_TIMEOUT = 1205
+MYSQL_ER_LOCK_DEADLOCK = 1213
+
+# MySQL error codes for connection errors
+MYSQL_CR_CONNECTION_ERROR = 2002
+MYSQL_CR_CONN_HOST_ERROR = 2003
+MYSQL_CR_UNKNOWN_HOST = 2005
+MYSQL_CR_SERVER_GONE_ERROR = 2006
+MYSQL_CR_SERVER_LOST = 2013
+
 
 def _bool_to_int(value: bool) -> int:
     return int(value)
@@ -171,6 +192,12 @@ def create_mapped_exception(error: Any, *, logger: Any | None = None) -> "SQLSpe
     raising. This pattern is more robust for use in __exit__ handlers and
     avoids issues with exception control flow in different Python versions.
 
+    Mapping priority:
+    1. Specific error codes (most reliable for MySQL)
+    2. SQLSTATE codes (where available)
+    3. Generic error code ranges
+    4. Default SQLSpecError fallback
+
     Args:
         error: The AsyncMy exception to map
         logger: Optional logger for migration warnings
@@ -179,13 +206,16 @@ def create_mapped_exception(error: Any, *, logger: Any | None = None) -> "SQLSpe
         True to suppress expected migration errors, or a SQLSpec exception
     """
     error_code = error.args[0] if len(error.args) >= 1 and isinstance(error.args[0], int) else None
-    sqlstate = error.sqlstate if has_sqlstate(error) and error.sqlstate is not None else None
+    sqlstate_attr = error.sqlstate if has_sqlstate(error) else None
+    sqlstate = sqlstate_attr if sqlstate_attr is not None else None
 
+    # Migration-specific errors to suppress
     if error_code in {1061, 1091}:
         if logger is not None:
             logger.warning("AsyncMy MySQL expected migration error (ignoring): %s", error)
         return True
 
+    # Integrity constraint violations
     if sqlstate == "23505" or error_code == MYSQL_ER_DUP_ENTRY:
         return _create_mysql_error(error, sqlstate, error_code, UniqueViolationError, "unique constraint violation")
     if sqlstate == "23503" or error_code in {1216, 1217, 1451, 1452}:
@@ -198,20 +228,44 @@ def create_mapped_exception(error: Any, *, logger: Any | None = None) -> "SQLSpe
         return _create_mysql_error(error, sqlstate, error_code, CheckViolationError, "check constraint violation")
     if sqlstate and sqlstate.startswith("23"):
         return _create_mysql_error(error, sqlstate, error_code, IntegrityError, "integrity constraint violation")
+
+    # Permission/access errors (check specific codes first)
+    if error_code in {MYSQL_ER_DBACCESS_DENIED, MYSQL_ER_ACCESS_DENIED, MYSQL_ER_TABLEACCESS_DENIED}:
+        return _create_mysql_error(error, sqlstate, error_code, PermissionDeniedError, "access denied")
+    if sqlstate and sqlstate.startswith("28"):
+        return _create_mysql_error(error, sqlstate, error_code, PermissionDeniedError, "authorization error")
+
+    # Transaction errors (deadlock vs lock wait timeout)
+    if error_code == MYSQL_ER_LOCK_DEADLOCK:
+        return _create_mysql_error(error, sqlstate, error_code, DeadlockError, "deadlock detected")
+    if error_code == MYSQL_ER_LOCK_WAIT_TIMEOUT:
+        return _create_mysql_error(error, sqlstate, error_code, QueryTimeoutError, "lock wait timeout")
+    if sqlstate and sqlstate.startswith("40"):
+        return _create_mysql_error(error, sqlstate, error_code, TransactionError, "transaction error")
+
+    # SQL syntax errors
     if sqlstate and sqlstate.startswith("42"):
         return _create_mysql_error(error, sqlstate, error_code, SQLParsingError, "SQL syntax error")
+    if error_code in range(1064, 1100):
+        return _create_mysql_error(error, sqlstate, error_code, SQLParsingError, "SQL syntax error")
+
+    # Connection errors
     if sqlstate and sqlstate.startswith("08"):
         return _create_mysql_error(error, sqlstate, error_code, DatabaseConnectionError, "connection error")
-    if sqlstate and sqlstate.startswith("40"):
-        return _create_mysql_error(error, sqlstate, error_code, TransactionError, "transaction error")
+    if error_code == MYSQL_CR_SERVER_LOST:
+        return _create_mysql_error(error, sqlstate, error_code, ConnectionTimeoutError, "connection lost")
+    if error_code in {
+        MYSQL_CR_CONNECTION_ERROR,
+        MYSQL_CR_CONN_HOST_ERROR,
+        MYSQL_CR_UNKNOWN_HOST,
+        MYSQL_CR_SERVER_GONE_ERROR,
+    }:
+        return _create_mysql_error(error, sqlstate, error_code, DatabaseConnectionError, "connection error")
+
+    # Data errors
     if sqlstate and sqlstate.startswith("22"):
         return _create_mysql_error(error, sqlstate, error_code, DataError, "data error")
-    if error_code in {2002, 2003, 2005, 2006, 2013}:
-        return _create_mysql_error(error, sqlstate, error_code, DatabaseConnectionError, "connection error")
-    if error_code in {1205, 1213}:
-        return _create_mysql_error(error, sqlstate, error_code, TransactionError, "transaction error")
-    if error_code in range(1064, 1100):
-        return _create_mysql_error(error, sqlstate, error_code, SQLParsingError, "SQL syntax error")
+
     return _create_mysql_error(error, sqlstate, error_code, SQLSpecError, "database error")