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 timed out or was canceled.

Raised when:

• Statement timeout exceeded (SQLSTATE 57014)

• Query canceled by user/operator

• Lock wait timeout exceeded (MySQL 1205)

• Oracle user requested cancel (ORA-01013)

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
+-- 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