mafw.db.migration.backend

Per-backend adaptation and the migration applier.

This module selects the correct playhouse.migrate migrator for the live database (delegating backend selection to playhouse.migrate.SchemaMigrator.from_database()), decides the DDL transaction policy for the backend, and applies a reviewed migration script’s migrate(migrator, database) function. Only SQLite, PostgreSQL and MySQL are supported; any other backend is rejected with an error that names it.

On backends whose migrator reports transactional DDL (SQLite, PostgreSQL) each script application is wrapped in database.atomic() so a failure rolls back cleanly. MySQL performs implicit commits on DDL and therefore cannot be rolled back transactionally: on a mid-script failure the applier reports the partially-migrated state and does not record the script as applied.

MAFw-generated triggers are not represented in peewee introspection. When a migration would affect such a trigger the applier recreates it after the operation via the existing TriggerDialect path; an operation touching a constraint the differ cannot safely reconstruct is refused.

Added in version 2.4.

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

Functions

`apply_script`(database, script)	Apply a reviewed migration script against the live database.
`backend_for`(database)	Determine the migration backend for a live database.
`migrator_for`(database)	Build the per-backend `playhouse.migrate` migrator for a database.
`supports_transactional_ddl`(migrator)	Return whether the migrator's backend supports transactional DDL.

Classes

MigrationBackend(*values)

The supported database backends.

class mafw.db.migration.backend.MigrationBackend(*values)[source]

Bases: StrEnum

The supported database backends.

Added in version 2.4.

static _generate_next_value_(name, start, count, last_values): Return the lower-cased version of the member name.

MYSQL = 'mysql': MySQL backend (non-transactional DDL).

POSTGRESQL = 'postgresql': PostgreSQL backend (transactional DDL).

SQLITE = 'sqlite': SQLite backend (transactional DDL).

mafw.db.migration.backend._load_module(path: Path) → ModuleType[source]

Import a migration script file as an isolated module.

Parameters:: path (Path) – The path to the migration script.
Returns:: The imported module object.
Return type:: ModuleType
Raises:: MigrationApplicationError – when the module cannot be imported.

mafw.db.migration.backend._unwrap(database: Database) → Database[source]

Return the concrete database, unwrapping a proxy when necessary.

Parameters:: database (peewee.Database) – The database or proxy to unwrap.
Returns:: The concrete database instance.
Return type:: peewee.Database

mafw.db.migration.backend.apply_script(database: Database, script: MigrationScript) → None[source]

Apply a reviewed migration script against the live database.

The script’s migrate(migrator, database) function is executed verbatim. On a transactional backend the application is wrapped in database.atomic() so that a failure rolls back cleanly and leaves the schema unchanged. On a non-transactional backend a failure is reported as a partial migration.

Parameters:

database (peewee.Database) – The live database to migrate.
script (MigrationScript) – The reviewed script to apply.

Raises:

MigrationApplicationError – when the application fails on a transactional backend (the schema is rolled back).
PartialMigrationError – when the application fails partway on a non-transactional backend.

mafw.db.migration.backend.backend_for(database: Database) → MigrationBackend[source]

Determine the migration backend for a live database.

Parameters:: database (peewee.Database) – The live database (possibly a proxy).
Returns:: The matching backend.
Return type:: MigrationBackend
Raises:: UnsupportedDatabaseError – for any backend other than the three supported.

mafw.db.migration.backend.migrator_for(database: Database) → SchemaMigrator[source]

Build the per-backend playhouse.migrate migrator for a database.

Backend selection is delegated to playhouse.migrate.SchemaMigrator.from_database(), which already unwraps a proxy and returns the right migrator subclass for the live database. This function first validates the backend with backend_for() so an unsupported backend is rejected with MAFw’s own UnsupportedDatabaseError rather than peewee’s generic ValueError.

Parameters:: database (peewee.Database) – The live database (possibly a proxy).
Returns:: The per-backend migrator instance.
Return type:: playhouse.migrate.SchemaMigrator
Raises:: UnsupportedDatabaseError – for any unsupported backend.

mafw.db.migration.backend.supports_transactional_ddl(migrator: SchemaMigrator) → bool[source]

Return whether the migrator’s backend supports transactional DDL.

Parameters:: migrator (playhouse.migrate.SchemaMigrator) – The per-backend migrator.
Returns:: True when the backend can roll back DDL transactionally.
Return type:: bool