django_evolution.utils.migrations

Utility functions for working with Django Migrations.

Functions

apply_migrations(executor, targets, plan, ...)

Apply migrations to the database.

clear_global_custom_migrations()

Clear the list of custom migrations.

create_pre_migrate_state(executor)

Create state needed before migrations are applied.

emit_post_migrate_or_sync(verbosity, ...)

Emit the post_migrate and/or post_sync signals.

emit_pre_migrate_or_sync(verbosity, ...)

Emit the pre_migrate and/or pre_sync signals.

filter_migration_targets(targets[, ...])

Filter migration execution targets based on the given criteria.

finalize_migrations(post_migrate_state)

Finalize any migrations operations.

has_migrations_module(app)

Return whether an app has a migrations module.

is_migration_initial(migration)

Return whether a migration is an initial migration.

record_applied_migrations(connection, migrations)

Record a list of applied migrations to the database.

register_global_custom_migrations(...)

Register a global list of custom migrations.

unrecord_applied_migrations(connection, ...)

Remove the recordings of applied migrations from the database.

Classes

MigrationExecutor(connection[, ...])

Load and execute migrations.

MigrationList()

A list of applied or pending migrations.

MigrationLoader(connection[, custom_migrations])

Loads migration files from disk.

class django_evolution.utils.migrations.MigrationList

Bases: object

A list of applied or pending migrations.

This is used to manage a list of migrations in a way that’s independent from the underlying representation used in Django. Migrations are tracked by app label and name, may be associated with a recorded migration database entry, and can be used to convert state to and from both signatures and Django migration state.

classmethod from_app_sig(app_sig)

Create a MigrationList based on an app signature.

Parameters:

app_sig (django_evolution.signature.AppSignature) – The app signature containing a list of applied migrations.

Returns:

The new migration list.

Return type:

MigrationList

classmethod from_names(app_label, migration_names)

Create a MigrationList based on a list of migration names.

New in version 2.1.

Parameters:
  • app_label (unicode) – The app label common to each migration name.

  • migration_names (list of unicode) – The list of migration names.

Returns:

The new migration list.

Return type:

MigrationList

classmethod from_database(connection, app_label=None)

Create a MigrationList based on recorded migrations.

Parameters:
  • connection (django.db.backends.base.BaseDatabaseWrapper) – The database connection used to query for migrations.

  • app_label (unicode, optional) – An app label to filter migrations by.

Returns:

The new migration list.

Return type:

MigrationList

__init__()

Initialize the list.

has_migration_info(app_label, name)

Return whether the list contains an entry for a migration.

Parameters:
  • app_label (unicode) – The label for the application that was migrated.

  • name (unicode) – The name of the migration.

Returns:

True if the migration is in the list. False if it is not.

Return type:

bool

add_migration_targets(targets)

Add a list of migration targets to the list.

Parameters:

targets (list of tuple) – The migration targets to each. Each is a tuple containing an app label and a migration name.

add_migration(migration)

Add a migration to the list.

This can only be called on Django 1.7 or higher.

Parameters:

migration (django.db.migrations.Migration) – The migration instance to add.

add_recorded_migration(recorded_migration)

Add a recorded migration to the list.

This can only be called on Django 1.7 or higher.

Parameters:

recorded_migration (django.db.migrations.recorder.MigrationRecorder.Migration) – The recorded migration model to add.

add_migration_info(app_label, name, migration=None, recorded_migration=None)

Add information on a migration to the list.

Parameters:
  • app_label (unicode) – The label for the application that was migrated.

  • name (unicode) – The name of the migration.

  • migration (django.db.migrations.Migration, optional) – An optional migration instance to associate with this entry.

  • recorded_migration (django.db.migrations.recorder.MigrationRecorder.Migration, optional) – An optional recorded migration to associate with this entry.

update(other)

Update the list with the contents of another list.

If there’s an entry in another list matching this one, and contains information that the entry in this list does not have, this list’s entry will be updated.

Parameters:

other (MigrationList) – The list of migrations to put into this list.

to_targets()

Return a set of migration targets based on this list.

Returns:

A set of migration targets. Each entry is a tuple containing the app label and name.

Return type:

set

get_app_labels()

Iterate through the app labels.

Results are sorted alphabetically.

Returns:

The sorted list of app labels with associated migrations.

Return type:

list of unicode

clone()

Clone the list.

Returns:

The cloned migration list.

Return type:

MigrationList

__bool__()

Return whether this list is truthy or falsy.

The list is truthy only if it has items.

Returns:

True if the list has items. False if it’s empty.

Return type:

bool

__len__()

Return the number of items in the list.

Returns:

The number of items in the list.

Return type:

int

__eq__(other)

Return whether this list is equal to another list.

The order of migrations is ignored when comparing lists.

Parameters:

other (MigrationList) – A list of migrations to compare to.

Returns:

True if the two lists have the same contents. False if there are differences in contents, or other is not a MigrationList.

Return type:

bool

__iter__()

Iterate through the list.

Entries are sorted first by app label, alphabetically, and then the order in which migrations were added for that app label.

Yields:

info – A dictionary containing the following keys:

app_label (unicode):

The app label for the migration.

name (unicode):

The name of the migration.

migration (django.db.migrations.Migration):

The optional migration instance.

recorded_migration (django.db.migrations.recorder.MigrationRecorder.Migration):

The optional recorded migration.

__add__(other)

Return a combined copy of this list and another list.

Parameters:

other (MigrationList) – The other list to add to this list.

Returns:

The new migration list containing contents of both lists.

Return type:

MigrationList

__sub__(other)

Return a copy of this list with another list’s contents excluded.

Parameters:

other (MigrationList) – The other list containing contents to exclude.

Returns:

The new migration list containing the contents of this list that don’t exist in the other list.

Return type:

MigrationList

__repr__()

Return a string representation of this list.

Returns:

The string representation.

Return type:

unicode

__hash__ = None
class django_evolution.utils.migrations.MigrationLoader(connection, custom_migrations=None, *args, **kwargs)

Bases: MigrationLoader

Loads migration files from disk.

This is a specialization of Django’s own MigrationLoader that allows for providing additional migrations not available on disk.

extra_applied_migrations

Migrations to mark as already applied. This can be used to augment the results calculated from the database.

Type:

MigrationList

__init__(connection, custom_migrations=None, *args, **kwargs)

Initialize the loader.

Parameters:
  • connection (django.db.backends.base.BaseDatabaseWrapper) – The connection to load applied migrations from.

  • custom_migrations (MigrationList, optional) – Custom migrations not available on disk.

  • *args (tuple) – Additional positional arguments for the parent class.

  • **kwargs (dict) – Additional keyword arguments for the parent class.

property applied_migrations

The migrations already applied.

This will contain both the migrations applied from the database and any set in extra_applied_migrations.

build_graph(reload_migrations=True)

Rebuild the migrations graph.

Parameters:

reload_migrations (bool, optional) – Whether to reload migration instances from disk. If False, the ones loaded before will be used.

load_disk()

Load migrations from disk.

This will also load any custom migrations.

class django_evolution.utils.migrations.MigrationExecutor(connection, custom_migrations=None, signal_sender=None)

Bases: MigrationExecutor

Load and execute migrations.

This is a specialization of Django’s own MigrationExecutor that allows for providing additional migrations not available on disk, and for emitting our own signals when processing migrations.

__init__(connection, custom_migrations=None, signal_sender=None)

Initialize the executor.

Changed in version 2.2: custom_migrations now defaults to any globally-registered custom migrations set in register_global_custom_migrations().

Parameters:
  • connection (django.db.backends.base.BaseDatabaseWrapper) – The connection to load applied migrations from.

  • custom_migrations (dict, optional) –

    Custom migrations not available on disk. Each key is a tuple of (app_label, migration_name), and each value is a migration.

    This defaults to any globally-registered custom migrations.

  • signal_sender (object, optional) – A custom sender to pass when sending signals. This defaults to this instance.

run_checks()

Perform checks on the migrations and any history.

Raises:
django_evolution.utils.migrations.register_global_custom_migrations(custom_migrations)

Register a global list of custom migrations.

These will be used by default when constructing a MigrationExecutor.

Only one list of custom migrations can be added at a time.

This is primarily useful for unit testing.

New in version 2.2.

Parameters:

custom_migrations (MigrationList) – The list of custom migrations.

Raises:

AssertionError – Custom migrations were already registered.

django_evolution.utils.migrations.clear_global_custom_migrations()

Clear the list of custom migrations.

New in version 2.2.

django_evolution.utils.migrations.has_migrations_module(app)

Return whether an app has a migrations module.

Parameters:

app (module) – The app module.

Returns:

True if the app has a migrations module. False if it does not.

Return type:

bool

django_evolution.utils.migrations.record_applied_migrations(connection, migrations)

Record a list of applied migrations to the database.

This can only be called when on Django 1.7 or higher.

Parameters:
  • connection (django.db.backends.base.BaseDatabaseWrapper) – The connection used to record applied migrations.

  • migrations (MigrationList) – The list of migration targets to record as applied.

django_evolution.utils.migrations.unrecord_applied_migrations(connection, app_label, migration_names=None)

Remove the recordings of applied migrations from the database.

This can only be called when on Django 1.7 or higher.

Parameters:
  • connection (django.db.backends.base.BaseDatabaseWrapper) – The connection used to unrecord applied migrations.

  • app_label (unicode) – The app label that the migrations pertain to.

  • migration_names (list of unicode, optional) – The list of migration names to unrecord. If not provided, all migrations for the app will be unrecorded.

django_evolution.utils.migrations.filter_migration_targets(targets, app_labels=None, exclude=None)

Filter migration execution targets based on the given criteria.

Parameters:
  • targets (list of tuple) – The migration targets to be executed.

  • app_labels (set of unicode, optional) – The app labels to limit the targets to.

  • exclude (set, optional) – Explicit targets to exclude.

Returns:

The resulting list of migration targets.

Return type:

list of tuple

django_evolution.utils.migrations.is_migration_initial(migration)

Return whether a migration is an initial migration.

Initial migrations are those that set up an app or models for the first time. Generally, they should be limited to model creations, or to those adding fields to a (non-migration-aware) model for the first time. They also should not have any dependencies on other migrations within the same app.

An initial migration should be able to be safely soft-applied (in other words, ignored if the model already appears to exist in the database).

Migrations on Django 1.9+ may declare themselves as explicitly initial or explicitly not initial.

Parameters:

migration (django.db.migrations.Migration) – The migration to check.

Returns:

True if the migration appears to be an initial migration. False if it does not.

Return type:

bool

django_evolution.utils.migrations.create_pre_migrate_state(executor)

Create state needed before migrations are applied.

The return value is dependent on the version of Django.

Parameters:

executor (django.db.migrations.executor.MigrationExecutor) – The migration executor that will handle the migrations.

Returns:

The state needed for applying migrations.

Return type:

django.db.migrations.state.ProjectState

django_evolution.utils.migrations.apply_migrations(executor, targets, plan, pre_migrate_state)

Apply migrations to the database.

Migrations will be applied using the fake_initial mode, which means that any initial migrations (those constructing the models for an app) will be skipped if the models already appear in the database. This is to avoid issues with applying those migrations when the models have already been created in the past outside of Django’s Migrations framework. In theory, this could cause some issues if those migrations also perform other important operations around data population, but this is really up to Django to handle, as this is part of the upgrade method when going from pre-1.7 to 1.7+ anyway.

This can only be called when on Django 1.7 or higher.

Parameters:
  • executor (django.db.migrations.executor.MigrationExecutor) – The migration executor that will handle applying the migrations.

  • targets (list of tuple) – The list of migration targets to apply.

  • plan (list of tuple) – The order in which migrations will be applied.

  • pre_migrate_state (object) – The pre-migration state needed to apply these migrations. This must be generated with create_pre_migrate_state() or a previous call to apply_migrations().

Returns:

The state generated from applying migrations. Any final state must be passed to finalize_migrations().

Return type:

object

django_evolution.utils.migrations.finalize_migrations(post_migrate_state)

Finalize any migrations operations.

This will update any internal state in Django for any migrations that were applied and represented by the provided post-migrate state.

Parameters:

post_migrate_state (object) – The state generated from applying migrations. This must be the result of apply_migrations().

django_evolution.utils.migrations.emit_pre_migrate_or_sync(verbosity, interactive, database_name, create_models, pre_migrate_state, plan)

Emit the pre_migrate and/or pre_sync signals.

This will emit the pre_migrate and/or pre_sync signals, providing the appropriate arguments for the current version of Django.

Parameters:
  • verbosity (int) – The verbosity level for output.

  • interactive (bool) – Whether handlers of the signal can prompt on the terminal for input.

  • database_name (unicode) – The name of the database being migrated.

  • create_models (list of django.db.models.Model) – The list of models being created outside of any migrations.

  • pre_migrate_state (django.db.migrations.state.ProjectState) – The project state prior to any migrations.

  • plan (list) – The full migration plan being applied.

django_evolution.utils.migrations.emit_post_migrate_or_sync(verbosity, interactive, database_name, created_models, post_migrate_state, plan)

Emit the post_migrate and/or post_sync signals.

This will emit the post_migrate and/or post_sync signals, providing the appropriate arguments for the current version of Django.

Parameters:
  • verbosity (int) – The verbosity level for output.

  • interactive (bool) – Whether handlers of the signal can prompt on the terminal for input.

  • database_name (unicode) – The name of the database that was migrated.

  • created_models (list of django.db.models.Model) – The list of models created outside of any migrations.

  • post_migrate_state (django.db.migrations.state.ProjectState) – The project state after applying migrations.

  • plan (list) – The full migration plan that was applied.