Exceptions

Complete exception hierarchy for SQLSpec. All exceptions inherit from SQLSpecError.

Base

class sqlspec.exceptions.SQLSpecError

Bases: Exception

Base exception class for SQLSpec exceptions.

__init__(*args, detail='')

Initialize SQLSpecError.

Parameters:

• *args (Any) -- args are converted to str before passing to Exception

• detail (str) -- detail of the exception.

Configuration

class sqlspec.exceptions.ImproperConfigurationError

Bases: SQLSpecError

Raised when configuration is invalid or incomplete.

class sqlspec.exceptions.ConfigResolverError

Bases: SQLSpecError

Exception raised when config resolution fails.

class sqlspec.exceptions.MissingDependencyError

Bases: SQLSpecError

Raised when a required dependency is not installed.

__init__(package, install_package=None)

Initialize SQLSpecError.

Parameters:

• *args -- args are converted to str before passing to Exception

• detail -- detail of the exception.

Connection

class sqlspec.exceptions.DatabaseConnectionError

Bases: SQLSpecError

Database connection error (invalid credentials, network failure, etc.).

class sqlspec.exceptions.ConnectionTimeoutError

Bases: DatabaseConnectionError

Database connection attempt timed out.

Raised when:

• TCP connection timeout to database server

• DNS resolution timeout

• SSL/TLS handshake timeout

• Oracle connect timeout (ORA-12170)

class sqlspec.exceptions.PermissionDeniedError

Bases: DatabaseConnectionError

Database access denied due to insufficient privileges.

Raised when:

• User lacks privileges for the operation (SQLSTATE 42501)

• Invalid credentials provided (SQLSTATE 28000/28P01)

• Database access denied (MySQL 1044/1045/1142)

• Oracle insufficient privileges (ORA-01031)

Transaction

class sqlspec.exceptions.TransactionError

Bases: SQLSpecError

Transaction error (rollback, deadlock, serialization failure).

class sqlspec.exceptions.SerializationConflictError

Bases: TransactionError

Serialization conflict (SQLSTATE 40001) requiring retry.

class sqlspec.exceptions.TransactionRetryError

Bases: TransactionError

Transaction failed after retries were exhausted.

class sqlspec.exceptions.DeadlockError

Bases: TransactionError

Deadlock detected during transaction execution.

Raised when:

• PostgreSQL deadlock detected (SQLSTATE 40P01)

• MySQL deadlock detected (Error 1213)

• Oracle deadlock detected (ORA-00060)

• SQLite database locked (SQLITE_LOCKED)

Applications should typically retry the transaction when this error occurs.

Repository

class sqlspec.exceptions.RepositoryError

Bases: SQLSpecError

Base repository exception type.

class sqlspec.exceptions.NotFoundError

Bases: RepositoryError

An identity does not exist.

class sqlspec.exceptions.MultipleResultsFoundError

Bases: RepositoryError

A single database result was required but more than one were found.

Integrity

class sqlspec.exceptions.IntegrityError

Bases: RepositoryError

Data integrity error.

class sqlspec.exceptions.UniqueViolationError

Bases: IntegrityError

A unique constraint was violated.

class sqlspec.exceptions.ForeignKeyViolationError

Bases: IntegrityError

A foreign key constraint was violated.

class sqlspec.exceptions.CheckViolationError

Bases: IntegrityError

A check constraint was violated.

class sqlspec.exceptions.NotNullViolationError

Bases: IntegrityError

A not-null constraint was violated.

SQL Processing

class sqlspec.exceptions.SQLParsingError

Bases: SQLSpecError

Issues parsing SQL statements.

__init__(message=None)

Initialize SQLSpecError.

Parameters:

• *args -- args are converted to str before passing to Exception

• detail -- detail of the exception.

class sqlspec.exceptions.SQLBuilderError

Bases: SQLSpecError

Issues Building or Generating SQL statements.

__init__(message=None)

Initialize SQLSpecError.

Parameters:

• *args -- args are converted to str before passing to Exception

• detail -- detail of the exception.

class sqlspec.exceptions.SQLConversionError

Bases: SQLSpecError

Issues converting SQL statements.

__init__(message=None)

Initialize SQLSpecError.

Parameters:

• *args -- args are converted to str before passing to Exception

• detail -- detail of the exception.

class sqlspec.exceptions.DialectNotSupportedError

Bases: SQLBuilderError

Raised when a SQL dialect does not support a specific feature.

Execution

class sqlspec.exceptions.OperationalError

Bases: SQLSpecError

Operational database error (timeout, disk full, resource limit).

class sqlspec.exceptions.QueryTimeoutError

Bases: OperationalError

Query execution exceeded a timeout or deadline.

Raised when:

• Lock wait timeout exceeded (MySQL 1205)

• Statement or service deadline exceeded

class sqlspec.exceptions.OperationCancelledError

Bases: OperationalError

Database operation was explicitly cancelled by a caller or operator.

OperationCancelledError and QueryTimeoutError are sibling operational errors. Catch OperationCancelledError for explicit caller or operator cancellation, and QueryTimeoutError for elapsed statement timeouts and deadlines. ADBC CANCELLED and TIMEOUT statuses follow this distinction. Callers that previously caught QueryTimeoutError for cancellation should catch both exceptions during migration, or catch OperationalError when the distinction is not relevant.

class sqlspec.exceptions.DataError

Bases: SQLSpecError

Invalid data type or format for database operation.

class sqlspec.exceptions.StackExecutionError

Bases: SQLSpecError

Raised when a statement stack operation fails.

__init__(operation_index, sql, original_error, *, adapter=None, mode='fail-fast', native_pipeline=None, downgrade_reason=None)

Initialize SQLSpecError.

Parameters:

• *args -- args are converted to str before passing to Exception

• detail -- detail of the exception.

Storage

class sqlspec.exceptions.StorageOperationFailedError

Bases: SQLSpecError

Raised when a storage backend operation fails.

class sqlspec.exceptions.StorageCapabilityError

Bases: SQLSpecError

Raised when a requested storage bridge capability is unavailable.

__init__(message, *, capability=None, remediation=None)

Initialize SQLSpecError.

Parameters:

• *args -- args are converted to str before passing to Exception

• detail -- detail of the exception.

class sqlspec.exceptions.FileNotFoundInStorageError

Bases: StorageOperationFailedError

Raised when a file or object is not found in the storage backend.

SQL Files

class sqlspec.exceptions.SQLFileNotFoundError

Bases: SQLSpecError

Raised when a SQL file cannot be found.

__init__(name, path=None)

Initialize the error.

Parameters:

• name (str) -- Name of the SQL file.

• path (str | None) -- Optional path where the file was expected.

class sqlspec.exceptions.SQLStatementNotFoundError

Bases: SQLFileNotFoundError

Raised when a named SQL statement is not loaded.

__init__(name, normalized_name, query_count)

Initialize the error.

Parameters:

• name (str) -- Name requested by the caller.

• normalized_name (str) -- Normalized statement name used for lookup.

• query_count (int) -- Number of SQL statements loaded in the registry.

class sqlspec.exceptions.SQLFileParseError

Bases: SQLSpecError

Raised when a SQL file cannot be parsed.

__init__(name, path, original_error, line=None)

Initialize the error.

Parameters:

• name (str) -- Name of the SQL file.

• path (str) -- Path to the SQL file.

• original_error (Exception) -- The underlying parsing error.

• line (int | None) -- Optional 1-based line number where the error was detected.

Migration

class sqlspec.exceptions.MigrationError

Bases: SQLSpecError

Base exception for migration-related errors.

class sqlspec.exceptions.OutOfOrderMigrationError

Bases: MigrationError

Raised when an out-of-order migration is detected in strict mode.

Out-of-order migrations occur when a pending migration has a timestamp earlier than already-applied migrations, typically from late-merging branches.

class sqlspec.exceptions.SquashValidationError

Bases: MigrationError

Raised when migration squash validation fails.

Squash validation errors occur when:

• Version range is invalid (start > end)

• Gap detected in version sequence

• Mixed migration types that cannot be squashed

• Target file already exists

Events

class sqlspec.exceptions.EventChannelError

Bases: SQLSpecError

Raised when event channel operations fail.

Inheritance Tree

SQLSpecError
+-- ImproperConfigurationError
+-- ConfigResolverError
+-- MissingDependencyError
+-- EventChannelError
+-- SQLParsingError
+-- SQLBuilderError
|   +-- DialectNotSupportedError
+-- SQLConversionError
+-- DatabaseConnectionError
|   +-- PermissionDeniedError
|   +-- ConnectionTimeoutError
+-- TransactionError
|   +-- SerializationConflictError
|   +-- TransactionRetryError
|   +-- DeadlockError
+-- RepositoryError
|   +-- NotFoundError
|   +-- MultipleResultsFoundError
|   +-- IntegrityError
|       +-- UniqueViolationError
|       +-- ForeignKeyViolationError
|       +-- CheckViolationError
|       +-- NotNullViolationError
+-- DataError
+-- OperationalError
|   +-- QueryTimeoutError
|   +-- OperationCancelledError
+-- StackExecutionError
+-- StorageOperationFailedError
|   +-- FileNotFoundInStorageError
+-- StorageCapabilityError
+-- SQLFileNotFoundError
|   +-- SQLStatementNotFoundError
+-- SQLFileParseError
+-- MigrationError
    +-- OutOfOrderMigrationError
    +-- SquashValidationError

SQLSTATE Mapping

sqlspec.exceptions.map_sqlstate_to_exception(sqlstate)

Map a SQLSTATE code to a SQLSpec exception class.

Checks in order of specificity:

1. Exact 5-character match

2. 2-character class match

Parameters:

sqlstate (str | None) -- 5-character SQLSTATE code

Return type:

type[SQLSpecError] | None

Returns:

Matching exception class or None if not mapped