mafw.db.migration.outcome

Structured result returned by every migration-service operation.

Every MigrationManager operation returns a single MigrationOutcome whose result field equals exactly one member of MigrationResult. The two front ends (the mafw db CLI and the SchemaMigrator processor) map this one structure to their own conventions, which guarantees that both entry points agree for identical inputs.

Added in version 2.4.

author:

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

Functions

failure(error, *[, messages])

Build a MigrationResult.FAILURE outcome from an error.

make_outcome(result, *[, diff, scripts, ...])

Construct a MigrationOutcome, normalizing iterables to tuples.

Classes

MigrationOutcome(result[, diff, scripts, ...])

The structured result of a single migration-service operation.

MigrationResult(*values)

The mutually exclusive result of a migration-service operation.
class mafw.db.migration.outcome.MigrationOutcome(result: MigrationResult, diff: SchemaDiff | None = None, scripts: tuple[MigrationScript, ...] = (), applied: tuple[MigrationHistoryEntry, ...] = (), pending: tuple[MigrationScript, ...] = (), messages: tuple[str, ...] = (), error: MigrationError | None = None, scoped_equivalence_only: bool = False, legacy: bool = False)[source]

Bases: object

The structured result of a single migration-service operation.

Parameters:

  • result (MigrationResult) – The single mutually exclusive result value.

  • diff (SchemaDiff, Optional) – The reported schema diff, when applicable.

  • scripts (tuple[MigrationScript, ...]) – The scripts generated or otherwise relevant to the operation.

  • applied (tuple[MigrationHistoryEntry, ...]) – The history entries recorded as applied, in chronological order.

  • pending (tuple[MigrationScript, ...]) – The pending scripts, in migration order.

  • messages (tuple[str, ...]) – Human-readable report lines.

  • error (MigrationError, Optional) – The error, populated if and only if result is FAILURE.

  • scoped_equivalence_only (bool) – True when an empty diff must not be read as full schema equivalence but only as synchronization scoped to the documented supported-difference types.

  • legacy (bool) – True when the target database has no migration history.

Added in version 2.4.

property is_failure: bool

Whether this outcome represents a failure.

class mafw.db.migration.outcome.MigrationResult(*values)[source]

Bases: StrEnum

The mutually exclusive result of a migration-service operation.

Exactly one member is set per MigrationOutcome.

Added in version 2.4.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

APPLIED = 'applied'

One or more migration scripts were applied successfully.

DIFFERENCE_DETECTED = 'difference_detected'

At least one difference was detected (read-only operations).

FAILURE = 'failure'

The operation failed; see the outcome’s error field.

GENERATED = 'generated'

Exactly one migration script was generated.

NO_CHANGE = 'no_change'

A diff was computed successfully and contains zero differences.

PENDING = 'pending'

One or more pending migrations exist (not yet applied).

UNSUPPORTED_OR_AMBIGUOUS = 'unsupported_or_ambiguous'

The diff contains only unsupported or ambiguous differences.

mafw.db.migration.outcome.failure(error: MigrationError, *, messages: Sequence[str] = ()) → MigrationOutcome[source]

Build a MigrationResult.FAILURE outcome from an error.

Parameters:

  • error (MigrationError) – The error identifying the cause of the failure.

  • messages (Sequence[str]) – Optional human-readable report lines.

Returns:

A failure outcome.

Return type:

MigrationOutcome

mafw.db.migration.outcome.make_outcome(result: MigrationResult, *, diff: SchemaDiff | None = None, scripts: Iterable[MigrationScript] = (), applied: Iterable[MigrationHistoryEntry] = (), pending: Iterable[MigrationScript] = (), messages: Iterable[str] = (), error: MigrationError | None = None, scoped_equivalence_only: bool = False, legacy: bool = False) → MigrationOutcome[source]

Construct a MigrationOutcome, normalizing iterables to tuples.

This helper guarantees exactly one result value and that error is populated if and only if result is MigrationResult.FAILURE.

Parameters:

  • result (MigrationResult) – The single mutually exclusive result value.

  • diff (SchemaDiff, Optional) – The reported schema diff, when applicable.

  • scripts (Iterable[MigrationScript]) – The scripts relevant to the operation.

  • applied (Iterable[MigrationHistoryEntry]) – The applied history entries, in chronological order.

  • pending (Iterable[MigrationScript]) – The pending scripts, in migration order.

  • messages (Iterable[str]) – Human-readable report lines.

  • error (MigrationError, Optional) – The error, required if and only if result is FAILURE.

  • scoped_equivalence_only (bool) – Whether an empty diff is scoped only.

  • legacy (bool) – Whether the database has no migration history.

Returns:

The constructed outcome.

Return type:

MigrationOutcome