Error Codes
A specific exception type for each failure mode, so callers can catch the case they can handle and let the rest surface.
Exception hierarchy
Everything raised by the core layer inherits from DbliftError. Catch a base class to handle a whole family, or a leaf for one condition.
ParserError — SQL parsing
| Exception | Raised when |
|---|---|
UnsupportedDialectError | The requested SQL dialect is not supported. |
ParserNotAvailableError | A parser could not be loaded for the dialect. |
ExecutionError — migration execution
| Exception | Raised when |
|---|---|
TransactionAbortedError | The database transaction is in an aborted state. |
CallbackExecutionError | A migration callback failed. |
NoSqlWriteNotSupportedError | A write statement was sent to a document store's read-only query API. Schema and data changes go through the vendor SDK from a Python migration. |
ValidationError — validation and setup
| Exception | Raised when |
|---|---|
ConnectionClosedError | The database connection closed unexpectedly. |
UnsupportedMigrationFormatError | A migration's format cannot run on the target dialect. Carries the code DBLIFT-NOSQL-001. |
SchemaCreationError | A test schema could not be created. |
ConfigurationError covers configuration that cannot be built or validated. It subclasses both ValueError and AttributeError, so existing handlers for either still catch it.
Stable diagnostic codes
A diagnostic code is quoted in the message and safe to match on.
| Code | Exception | Cause |
|---|---|---|
DBLIFT-NOSQL-001 | UnsupportedMigrationFormatError | A .sql migration aimed at a dialect whose quirks declare no SQL migration support. Document stores such as Cosmos DB and MongoDB have no SQL DDL — write the migration as a Python script driving the vendor SDK. |
DBLIFT-NOSQL-002 | NoSqlQueryLanguageUnsupportedError | A string was passed to context.execute() on a store with no query language (MongoDB). Use collection APIs instead. |
Driver error categories
Raw driver exceptions are classified before they reach a log or a report. Each dialect contributes its own patterns through its quirks; a dialect-agnostic set catches the rest.
network · timeout · locking · authentication · authorization · schema · constraint · sql_syntax · resource · internal · unknown
Connection failures are reduced to one user-facing line, and the trailing [SQL: …] block SQLAlchemy appends is stripped, so a failure setting up the history table never leaks internal DDL into output. Where available, the five-character SQLState is preserved.