mafw.db.migration.errors

Migration-specific exception hierarchy.

All migration errors subclass MAFwException so that callers can catch the whole family with the framework base exception, mirroring the existing MAFw error style (for example InvalidConfigurationError and UnsupportedDatabaseError).

The migration service converts expected conditions (an empty diff, a pending conflict, an unsupported-only diff) into MigrationOutcome values and reserves these exceptions for genuine faults. Each exception carries the names of the affected objects/fields so that both the CLI and the processor can emit actionable diagnostics.

Added in version 2.4.

author:

Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)

Exceptions

MigrationApplicationError(message[, version])	Raised when the application of a migration script fails.
MigrationConfigurationError(message[, fields])	Raised when the migration configuration is missing or invalid.
MigrationConflictingTableNameError(...)	Raised when two or more discovered models declare the same table name.
MigrationError	Base class for every schema-migration error.
MigrationHistoryInconsistencyError(message)	Raised when the migration history and the directory are inconsistent.
MigrationUnresolvedDirectoryError(directory)	Raised when the effective migration directory cannot be resolved.
PartialMigrationError(message[, version, ...])	Raised when a migration fails partway on a backend without transactional DDL.

exception mafw.db.migration.errors.MigrationApplicationError(message: str, version: str | None = None)

Bases: MigrationError

Raised when the application of a migration script fails.

The affected script is identified by its version so that the operator can locate and review it. On a transactional backend the schema changes made by the failing script are rolled back and no history entry is recorded.

Parameters:

• message (str) – The human-readable error message.

• version (str, Optional) – The version identifier of the failed migration script.

Added in version 2.4.

version

The version identifier of the failed migration script.

exception mafw.db.migration.errors.MigrationConfigurationError(message: str, fields: Iterable[str] | None = None)

Bases: MigrationError

Raised when the migration configuration is missing or invalid.

Typical causes are a missing or unreadable steering file, a missing database configuration section, or missing model-module information required for model discovery.

Parameters:

• message (str) – The human-readable error message.

• fields (Iterable[str], Optional) – The names of the invalid configuration fields, when known.

Added in version 2.4.

fields: tuple[str, ...]

The names of the invalid configuration fields.

exception mafw.db.migration.errors.MigrationConflictingTableNameError(table_name: str, model_names: Iterable[str])

Bases: MigrationError

Raised when two or more discovered models declare the same table name.

Parameters:

• table_name (str) – The shared table name that caused the collision.

• model_names (Iterable[str]) – The names of every model declaring the shared table name.

Added in version 2.4.

model_names: tuple[str, ...]

The names of every model declaring the shared table name.

table_name

The shared table name that caused the collision.

exception mafw.db.migration.errors.MigrationError

Bases: MAFwException

Base class for every schema-migration error.

Added in version 2.4.

exception mafw.db.migration.errors.MigrationHistoryInconsistencyError(message: str, scripts: Iterable[str] | None = None)

Bases: MigrationError

Raised when the migration history and the directory are inconsistent.

Examples are a history entry with no corresponding script in the directory, a recorded script whose content changed relative to the directory, or a script that is out of recorded sequence order.

Parameters:

• message (str) – The human-readable error message.

• scripts (Iterable[str], Optional) – The identifiers of the affected scripts, when known.

Added in version 2.4.

scripts: tuple[str, ...]

The identifiers of the affected scripts.

exception mafw.db.migration.errors.MigrationUnresolvedDirectoryError(directory: str)

Bases: MigrationError

Raised when the effective migration directory cannot be resolved.

This happens when the resolved directory does not exist or is not a readable directory. The operation is aborted before any script or history record is created or modified.

Parameters:

directory (str) – The directory path that could not be resolved.

Added in version 2.4.

directory

The directory path that could not be resolved.

exception mafw.db.migration.errors.PartialMigrationError(message: str, version: str | None = None, last_statement: str | None = None)

Bases: MigrationApplicationError

Raised when a migration fails partway on a backend without transactional DDL.

On such a backend (notably MySQL) a mid-script failure cannot be rolled back transactionally, so the database is left in a partially migrated state. The error names the last successfully applied statement so the operator can recover manually.

Parameters:

• message (str) – The human-readable error message.

• version (str, Optional) – The version identifier of the failed migration script.

• last_statement (str, Optional) – The last SQL statement that applied successfully.

Added in version 2.4.

last_statement

The last SQL statement that applied successfully before the failure.