## providers.mongodb.migrations.MigrationDefinition

<span id="hexkit.providers.mongodb.migrations.MigrationDefinition"></span>


Contains all logic to migrate the database from one version to the next.


Usage

``` python
providers.mongodb.migrations.MigrationDefinition(
    *, db, unapplying, is_final_migration
)
```


## Methods

| Name | Description |
|----|----|
| [__init__()](#__init__) | Instantiate the MigrationDefinition. |
| [apply()](#apply) | Make the changes required to move the DB version to `self.version`. |
| [auto_copy_indexes()](#auto_copy_indexes) | Copy the indexes from old collections to new, and remember that the indexes |
| [auto_finalize()](#auto_finalize) | Use within [apply()](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.apply) or [unapply()](providers.mongodb.migrations.Reversible.md#hexkit.providers.mongodb.migrations.Reversible.unapply) as a context manager to automatically |
| [copy_indexes()](#copy_indexes) | Copy the indexes from `source_coll_name` to `dest_coll_name`. |
| [drop_old_collections()](#drop_old_collections) | Drop the old, pre-migration version of all staged collections. |
| [get_new_temp_names()](#get_new_temp_names) | Add `self._new_prefix` to a list of plain collection names. |
| [get_old_temp_names()](#get_old_temp_names) | Add `self._old_prefix` to a list of plain collection names. |
| [migrate_docs_in_collection()](#migrate_docs_in_collection) | Migrate a collection by calling `change_function` on each document within. |
| [new_temp_name()](#new_temp_name) | Add `self._new_prefix` to a plain collection name. |
| [old_temp_name()](#old_temp_name) | Add `self._old_prefix` to plain collection name. |
| [stage_collection()](#stage_collection) | Stage a single collection. |
| [stage_new_collections()](#stage_new_collections) | Rename old collections to temporarily move them aside without dropping them, |
| [unapply()](#unapply) | Placeholder for a method to reverse the migration changes. |
| [unstage_collection()](#unstage_collection) | Reverse steps from [stage_collection()](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.stage_collection) |

<span id="__init__"></span>

<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.__init__"></span>


#### \_\_init\_\_()


Instantiate the MigrationDefinition.


Usage

``` python
__init__(*, db, unapplying, is_final_migration)
```


Subclass overrides need to call `super().__init__` or include its code.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.apply"></span>

------------------------------------------------------------------------


#### apply()


Make the changes required to move the DB version to `self.version`.


Usage

``` python
apply()
```


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.auto_copy_indexes"></span>

------------------------------------------------------------------------


#### auto_copy_indexes()


Copy the indexes from old collections to new, and remember that the indexes


Usage

``` python
auto_copy_indexes(*, coll_names)
```


have been copied for these collections.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.auto_finalize"></span>

------------------------------------------------------------------------


#### auto_finalize()


Use within [apply()](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.apply) or [unapply()](providers.mongodb.migrations.Reversible.md#hexkit.providers.mongodb.migrations.Reversible.unapply) as a context manager to automatically


Usage

``` python
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](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.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.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.copy_indexes"></span>

------------------------------------------------------------------------


#### copy_indexes()


Copy the indexes from `source_coll_name` to `dest_coll_name`.


Usage

``` python
copy_indexes(*, source_coll_name, dest_coll_name)
```


This function can be used for manual index copying when [auto_copy_indexes](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.auto_copy_indexes) doesn't suffice. Normally, prefer to use [auto_copy_indexes](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.auto_copy_indexes).


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.drop_old_collections"></span>

------------------------------------------------------------------------


#### drop_old_collections()


Drop the old, pre-migration version of all staged collections.


Usage

``` python
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.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.get_new_temp_names"></span>

------------------------------------------------------------------------


#### get_new_temp_names()


Add `self._new_prefix` to a list of plain collection names.


Usage

``` python
get_new_temp_names(coll_name)
```


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.get_old_temp_names"></span>

------------------------------------------------------------------------


#### get_old_temp_names()


Add `self._old_prefix` to a list of plain collection names.


Usage

``` python
get_old_temp_names(coll_name)
```


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.migrate_docs_in_collection"></span>

------------------------------------------------------------------------


#### migrate_docs_in_collection()


Migrate a collection by calling `change_function` on each document within.


Usage

``` python
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.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.new_temp_name"></span>

------------------------------------------------------------------------


#### new_temp_name()


Add `self._new_prefix` to a plain collection name.


Usage

``` python
new_temp_name(coll_name)
```


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.old_temp_name"></span>

------------------------------------------------------------------------


#### old_temp_name()


Add `self._old_prefix` to plain collection name.


Usage

``` python
old_temp_name(coll_name)
```


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.stage_collection"></span>

------------------------------------------------------------------------


#### stage_collection()


Stage a single collection.


Usage

``` python
stage_collection(original_coll_name)
```


Do not call until finished with all changes to the collection.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.stage_new_collections"></span>

------------------------------------------------------------------------


#### stage_new_collections()


Rename old collections to temporarily move them aside without dropping them,


Usage

``` python
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.


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.unapply"></span>

------------------------------------------------------------------------


#### unapply()


Placeholder for a method to reverse the migration changes.


Usage

``` python
unapply()
```


To implement, additionally subclass Reversible:

    class MyMigration(MigrationDefinition, Reversible):
        ...


<span id="hexkit.providers.mongodb.migrations.MigrationDefinition.unstage_collection"></span>

------------------------------------------------------------------------


#### unstage_collection()


Reverse steps from [stage_collection()](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition.stage_collection)


Usage

``` python
unstage_collection(original_coll_name)
```