django_evolution.utils.migrations
Utility functions for working with Django Migrations.
Functions
|
Apply migrations to the database. |
Clear the list of custom migrations. |
|
|
Create state needed before migrations are applied. |
|
Emit the post_migrate and/or post_sync signals. |
|
Emit the pre_migrate and/or pre_sync signals. |
|
Filter migration execution targets based on the given criteria. |
|
Finalize any migrations operations. |
Return whether an app has a migrations module. |
|
|
Return whether a migration is an initial migration. |
|
Record a list of applied migrations to the database. |
Register a global list of custom migrations. |
|
|
Remove the recordings of applied migrations from the database. |
Classes
|
Load and execute migrations. |
A list of applied or pending 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:
- classmethod from_names(app_label, migration_names)
Create a MigrationList based on a list of migration names.
New in version 2.1.
- Parameters:
- Returns:
The new migration list.
- Return type:
- 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:
- __init__()
Initialize the list.
- has_migration_info(app_label, name)
Return whether the list contains an entry for a migration.
- add_migration_targets(targets)
Add a list of migration targets to the list.
- 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:
- get_app_labels()
Iterate through the app labels.
Results are sorted alphabetically.
- clone()
Clone the list.
- Returns:
The cloned migration list.
- Return type:
- __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:
- __len__()
Return the number of items in the list.
- Returns:
The number of items in the list.
- Return type:
- __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, orother
is not aMigrationList
.- Return type:
- __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:
- __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:
- __repr__()
Return a string representation of this list.
- Returns:
The string representation.
- Return type:
- __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:
- __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. IfFalse
, 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 inregister_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.errors.MigrationConflictsError – There are conflicts between migrations loaded from disk.
django_evolution.errors.MigrationHistoryError – There are unapplied dependencies to applied migrations.
- 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 amigrations
module.False
if it does not.- Return type:
- 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
ofunicode
, 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.
- 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:
- 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
oftuple
) – The list of migration targets to apply.plan (
list
oftuple
) – 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 withcreate_pre_migrate_state()
or a previous call toapply_migrations()
.
- Returns:
The state generated from applying migrations. Any final state must be passed to
finalize_migrations()
.- Return type:
- 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 ofapply_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/orpre_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
ofdjango.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/orpost_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
ofdjango.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.