Migration

The @ChangeLog annotation has been deprecated in favour of the @ChangeUnit. For more information check this section

# Introduction

A migration is composed by multiple smaller pieces called ChangeUnits, which are processed in order by the Mongock runner.

ChangeUnits are the unit of migration. These refer to the annotated classes where developers write migration logic/scripts.

All classes with the @ChangeUnit annotation will be scanned by Mongock to execute the migration.

A migration is constituted by an ordered list of ChangeUnits. Each of the ChangeUnits represent a unit of migration, which has the following implications:

  1. Each ChangeUnit is wrapped in a transaction:.
    • When transactions are possible(transactional environment), Mongock uses the mechanism provided by the database.
    • On the other hand, in non-transactional environments, Mongock will try to provide an artificial transactional atmosphere by rolling back the failed change manually.
  2. In targeted operations, such as undo, upgrade, etc., the ChangeUnit is the unit of the operation. For example, when performing an undo operation, it needs to specify the ChangeUnitId until which all the ChangeUnits are reverted(inclusive).
  3. A ChangeUnit has only one migration method, which is marked with the @Execution annotation, and a rollback method, annotated with @RollbackExecution.

# ChangeUnit methods

Every class marked as @ChangeUnit will be marked as a migration class and can contain methods annotated as follow:

This method is treated and tracked in the database history like the @Execution method, meaning this that in case of failure, it will force the migration to be aborted, tracked in the database as failed and Mongock will run it again in the next execution.


# ChangeUnit attributes

Multiple attributes can be passed to ChangeUnits to configure these. The following table represents the list of attributes that you can set for preparing your migration:

Method Description Mandatory? Default value
id Returns the ChangeUnit's id that will be stored in the ChangeUnit history table/collection and will the way to identify a ChangeUnit. The combination of this field and the author must be unique among the changeunits. YES n/a
order Returns the ChangeUnit's execution order. The order will be applied treating the value as alphanumeric. YES n/a
author Returns the ChangeUnit's author. The combination of this and the author must be unique among the changeunits. NO default-author
runAlways Returns whether the ChangeUnit is runAlways or not. For more information, visit the runner configuration section. NO false
systemVersion Returns the ChangeUnit's system version. For more information, visit the runner configuration section. NO 0

# ChangeUnit example

ChangeUnits accept dependency injections directly in the method and at constructor level

The value of @ChangeUnit's order annotation field will be treated as alphanumeric.

@ChangeUnit(id="myMigrationChangeUnitId", order = "001", author = "mongock_test", systemVersion = "1")
public class MyMigrationChangeUnit {
private final MongoTemplate template;
public MyMigrationChangeUnit(MongoTemplate template) {
this.template = template;
}
//Note this method / annotation is Optional
@BeforeExecution
public void before() {
mongoTemplate.createCollection("clients");
}
//Note this method / annotation is Optional
@RollbackBeforeExecution
public void rollbackBefore() {
mongoTemplate.dropCollection("clients");
}
@Execution
public void migrationMethod() {
getClientDocuments()
.stream()
.forEach(clientDocument -> mongoTemplate.save(clientDocument, CLIENTS_COLLECTION_NAME));
}
@RollbackExecution
public void rollback() {
mongoTemplate.deleteMany(new Document());
}
}

# Best practices


ChangeLog

From Mongock version 5, @ChangeLog and @ChangeSet annotations are deprecated and shouldn't be used. However, these won't be removed for backwards compatibility.

Please follow one of the recommended approaches depending on your use case:

- For existing changeLogs created prior version 5: Leave it untouched, keeping the deprecated annotation.

- For new migrations from version 5: Use the new @ChangeUnit annotation instead.


Please visit the ChangeLog - version 4 section to access the ChangeLog documentation for Version 4.

For more information about the reason we have adopted this change, please visit our FAQ section.