GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • litestar-org/sqlspec
  • Home
  • Learn
  • Databases
  • Integrations
  • Reference
  • Playground
  • Project
  • SQLSpec
  • Configuration
  • Exceptions
  • Protocols
  • Typing
  • Drivers

This view

  • Original page
  • New address

GeezerVison is showing sqlspec.dev — Exceptions - SQLSpec

Exceptions¶

from sqlspec.exceptions import (
    CheckViolationError,
    ConfigResolverError,
    ConnectionTimeoutError,
    DatabaseConnectionError,
    DataError,
    DeadlockError,
    DialectNotSupportedError,
    EventChannelError,
    FileExistsInStorageError,
    FileNotFoundInStorageError,
    ForeignKeyViolationError,
    ImproperConfigurationError,
    IntegrityError,
    InvalidCursorError,
    MigrationError,
    MissingDependencyError,
    MultipleResultsFoundError,
    NotFoundError,
    NotNullViolationError,
    OperationalError,
    OperationCancelledError,
    OutOfOrderMigrationError,
    PermissionDeniedError,
    QueryTimeoutError,
    RepositoryError,
    SerializationConflictError,
    SQLBuilderError,
    SQLConversionError,
    SQLFileNotFoundError,
    SQLFileParseError,
    SQLFragmentNotFoundError,
    SQLParsingError,
    SQLSlotError,
    SQLSpecError,
    SQLStatementNotFoundError,
    SquashValidationError,
    StackExecutionError,
    StorageCapabilityError,
    StorageOperationFailedError,
    StoragePathTraversalError,
    TransactionError,
    UniqueViolationError,
    map_sqlstate_to_exception,
)

Normalized exception hierarchy raised across database drivers, query builders, SQL file loaders, migrations, and storage pipelines.

Base & Configuration Exceptions¶

SQLSpecError ¶

Bases: Exception

Base exception class for SQLSpec exceptions.

ImproperConfigurationError ¶

Bases: SQLSpecError

Raised when configuration is invalid or incomplete.

ConfigResolverError ¶

Bases: SQLSpecError

Exception raised when config resolution fails.

MissingDependencyError ¶

Bases: SQLSpecError

Raised when a required dependency is not installed.

DialectNotSupportedError ¶

Bases: SQLBuilderError

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

Integrity & Constraint Violations¶

IntegrityError ¶

Bases: RepositoryError

Data integrity error.

UniqueViolationError ¶

Bases: IntegrityError

A unique constraint was violated.

ForeignKeyViolationError ¶

Bases: IntegrityError

A foreign key constraint was violated.

NotNullViolationError ¶

Bases: IntegrityError

A not-null constraint was violated.

CheckViolationError ¶

Bases: IntegrityError

A check constraint was violated.

Execution, Concurrency & Operational Errors¶

OperationalError ¶

Bases: SQLSpecError

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

DatabaseConnectionError ¶

Bases: SQLSpecError

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

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)

QueryTimeoutError ¶

Bases: OperationalError

Query execution exceeded a timeout or deadline.

Raised when
  • Lock wait timeout exceeded (MySQL 1205)
  • Statement or service deadline exceeded

OperationCancelledError ¶

Bases: OperationalError

Database operation was explicitly cancelled by a caller or operator.

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)

TransactionError ¶

Bases: SQLSpecError

Transaction error (rollback, deadlock, serialization failure).

SerializationConflictError ¶

Bases: TransactionError

Serialization conflict (SQLSTATE 40001) requiring retry.

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.

DataError ¶

Bases: SQLSpecError

Invalid data type or format for database operation.

InvalidCursorError ¶

Bases: SQLSpecError

Raised when a pagination cursor is malformed, tampered with, or mismatched.

NotFoundError ¶

Bases: RepositoryError

An identity does not exist.

MultipleResultsFoundError ¶

Bases: RepositoryError

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

RepositoryError ¶

Bases: SQLSpecError

Base repository exception type.

StackExecutionError ¶

Bases: SQLSpecError

Raised when a statement stack operation fails.

SQL Parsing, File Loader, Migration & Storage Errors¶

SQLParsingError ¶

Bases: SQLSpecError

Issues parsing SQL statements.

SQLConversionError ¶

Bases: SQLSpecError

Issues converting SQL statements.

SQLBuilderError ¶

Bases: SQLSpecError

Issues Building or Generating SQL statements.

SQLFileNotFoundError ¶

Bases: SQLSpecError

Raised when a SQL file cannot be found.

SQLFileParseError ¶

Bases: SQLSpecError

Raised when a SQL file cannot be parsed.

SQLStatementNotFoundError ¶

Bases: SQLFileNotFoundError

Raised when a named SQL statement is not loaded.

SQLFragmentNotFoundError ¶

Bases: SQLStatementNotFoundError

Raised when a SQL fragment named by an include or lookup is not loaded.

SQLSlotError ¶

Bases: SQLSpecError

Raised when a SQL statement slot is missing, unknown, or conflicts.

MigrationError ¶

Bases: SQLSpecError

Base exception for migration-related errors.

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.

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

StorageOperationFailedError ¶

Bases: SQLSpecError

Raised when a storage backend operation fails.

FileNotFoundInStorageError ¶

Bases: StorageOperationFailedError

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

FileExistsInStorageError ¶

Bases: StorageOperationFailedError

Raised when writing to an existing object with overwrite disabled.

StorageCapabilityError ¶

Bases: SQLSpecError

Raised when a requested storage bridge capability is unavailable.

StoragePathTraversalError ¶

Bases: StorageOperationFailedError

Raised when a storage path would resolve outside its backend root.

EventChannelError ¶

Bases: SQLSpecError

Raised when event channel operations fail.

SQLSTATE Mapping Helper¶

SQLSTATE_EXCEPTION_MAP maps standard 5-character ANSI/PostgreSQL SQLSTATE codes ("23505", "40001", "40P01", "57014", etc.) to their corresponding SQLSpecError subclass.

map_sqlstate_to_exception ¶

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:

Name Type Description Default
sqlstate str | None

5-character SQLSTATE code

 required

Returns:

Type Description
type[SQLSpecError] | None

Matching exception class or None if not mapped
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.