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.BackendNotRegisteredError

Bases: SQLSpecError

Raised when a requested storage backend key is not registered.

__init__(backend_key)

Initialize SQLSpecError.

Parameters:

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

• detail – detail of the exception.

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 (e.g., network, permission, API error).

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.SQLFileParseError

Bases: SQLSpecError

Raised when a SQL file cannot be parsed.

__init__(name, path, original_error)

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.

Migration

class sqlspec.exceptions.MigrationError

Bases: SQLSpecError

Base exception for migration-related errors.

class sqlspec.exceptions.InvalidVersionFormatError

Bases: MigrationError

Raised when a migration version format is invalid.

Invalid formats include versions that don’t match sequential (0001) or timestamp (YYYYMMDDHHmmss) patterns, or timestamps with invalid dates.

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

Serialization

class sqlspec.exceptions.SerializationError

Bases: SQLSpecError

Encoding or decoding of an object failed.

Events

class sqlspec.exceptions.EventChannelError

Bases: SQLSpecError

Raised when event channel operations fail.

Inheritance Tree

SQLSpecError
+-- ImproperConfigurationError
+-- ConfigResolverError
+-- BackendNotRegisteredError
+-- MissingDependencyError
+-- EventChannelError
+-- SQLParsingError
+-- SQLBuilderError
|   +-- DialectNotSupportedError
+-- SQLConversionError
+-- SerializationError
+-- DatabaseConnectionError
|   +-- PermissionDeniedError
|   +-- ConnectionTimeoutError
+-- TransactionError
|   +-- SerializationConflictError
|   +-- TransactionRetryError
|   +-- DeadlockError
+-- RepositoryError
|   +-- NotFoundError
|   +-- MultipleResultsFoundError
|   +-- IntegrityError
|       +-- UniqueViolationError
|       +-- ForeignKeyViolationError
|       +-- CheckViolationError
|       +-- NotNullViolationError
+-- DataError
+-- OperationalError
|   +-- QueryTimeoutError
+-- StackExecutionError
+-- StorageOperationFailedError
|   +-- FileNotFoundInStorageError
+-- StorageCapabilityError
+-- SQLFileNotFoundError
+-- SQLFileParseError
+-- MigrationError
    +-- InvalidVersionFormatError
    +-- 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 (e.g., “23505” → UniqueViolationError) 2. 2-character class match (e.g., “23” → IntegrityError)

Parameters:

sqlstate (str | None) – 5-character SQLSTATE code (e.g., “23505”)

Return type:

type[SQLSpecError] | None

Returns:

Matching exception class or None if not mapped