providers.mongodb.migrations.MigrationDefinition
Contains all logic to migrate the database from one version to the next.
Usage
providers.mongodb.migrations.MigrationDefinition()Methods
| Name | Description |
|---|---|
| __init__() | Instantiate the MigrationDefinition. |
| apply() |
Make the changes required to move the DB version to self.version.
|
| auto_copy_indexes() | Copy the indexes from old collections to new, and remember that the indexes |
| auto_finalize() | Use within apply() or unapply() as a context manager to automatically |
| copy_indexes() |
Copy the indexes from source_coll_name to dest_coll_name.
|
| drop_old_collections() | Drop the old, pre-migration version of all staged collections. |
| get_new_temp_names() |
Add self._new_prefix to a list of plain collection names.
|
| get_old_temp_names() |
Add self._old_prefix to a list of plain collection names.
|
| migrate_docs_in_collection() |
Migrate a collection by calling change_function on each document within.
|
| new_temp_name() |
Add self._new_prefix to a plain collection name.
|
| old_temp_name() |
Add self._old_prefix to plain collection name.
|
| stage_collection() | Stage a single collection. |
| stage_new_collections() | Rename old collections to temporarily move them aside without dropping them, |
| unapply() | Placeholder for a method to reverse the migration changes. |
| unstage_collection() | Reverse steps from stage_collection() |
__init__()
Instantiate the MigrationDefinition.
Usage
__init__(*, db, unapplying, is_final_migration)Subclass overrides need to call super().__init__ or include its code.
apply()
Make the changes required to move the DB version to self.version.
Usage
apply()
auto_copy_indexes()
Copy the indexes from old collections to new, and remember that the indexes
Usage
auto_copy_indexes(*, coll_names)have been copied for these collections.
auto_finalize()
Usage
auto_finalize(coll_names, copy_indexes=False)stage the temporary migrated collections for the specified collection names and then drop the old collections. Set copy_indexes to True if the indexes are expected to be identical between the old and new collection versions.
Should be used for most migrations, but complex migrations might need to take a more manual approach. For that reason, this context manager is optional.
If an error occurs during the migration process, staged changes will be unstaged and dropped. If a subsequent error occurs during cleanup, it is logged with a recommendation to restore the database.
copy_indexes()
Copy the indexes from source_coll_name to dest_coll_name.
Usage
copy_indexes(*, source_coll_name, dest_coll_name)This function can be used for manual index copying when auto_copy_indexes doesn’t suffice. Normally, prefer to use auto_copy_indexes.
drop_old_collections()
Drop the old, pre-migration version of all staged collections.
Usage
drop_old_collections(*, enforce_indexes)Args - enforce_indexes: Raise an error if indexes haven’t been copied over to the replacement collections. This is not always useful, since the collections might undergo changes that make old indexes obsolete. This should be set to True for migrations that don’t involve changes to the collections’ indexes.
get_new_temp_names()
Add self._new_prefix to a list of plain collection names.
Usage
get_new_temp_names(coll_name)
get_old_temp_names()
Add self._old_prefix to a list of plain collection names.
Usage
get_old_temp_names(coll_name)
migrate_docs_in_collection()
Migrate a collection by calling change_function on each document within.
Usage
migrate_docs_in_collection(
*,
coll_name,
change_function,
validation_model=None,
id_field="",
force_validate=False,
batch_size=1000
)If validation_model is supplied, model will be used to cross-check the resulting doc data when this is the last migration to be applied/unapplied OR always_validate is True.
batch_size controls the size of bulk inserts as well as the max number of documents retrieved at a time by the cursor.
new_temp_name()
Add self._new_prefix to a plain collection name.
Usage
new_temp_name(coll_name)
old_temp_name()
Add self._old_prefix to plain collection name.
Usage
old_temp_name(coll_name)
stage_collection()
Stage a single collection.
Usage
stage_collection(original_coll_name)Do not call until finished with all changes to the collection.
stage_new_collections()
Rename old collections to temporarily move them aside without dropping them,
Usage
stage_new_collections(original_coll_names)then remove the temporary prefix from the migrated collections.
Do not call until finished making changes to (migrating) the collections.
unapply()
Placeholder for a method to reverse the migration changes.
Usage
unapply()To implement, additionally subclass Reversible:
class MyMigration(MigrationDefinition, Reversible):
...
unstage_collection()
Reverse steps from stage_collection()
Usage
unstage_collection(original_coll_name)