Runner - Springboot

# Introduction

As its name suggests, this runner is the one to use with Springboot. It leverages the Springboot features, like the ApplicationContext, profiles and EventPublisher, to provides a smooth user experience.

It supports both building approaches, builder and autoconfiguration.

# Get started

Following the get started section, this covers steps 2 and 7.

# Add the maven dependency for the runner (step 2)


# Build the runner (step 7)

Like the rest of the runners, the springboot runner is built from a builder. Each runner provides a class with an static method builder().

Springboot adds an extra mandatory field to the driver and scan class/package(mandatory in all the runners), the Spring ApplicationContext, from which all the dependencies injected to your migration classes are taken.

When using the builder approach, you need to provide the driver and ApplicationContext manually to the builder. On the other hand, when using the autoconfiguration approach, Mongock will take the ApplicationContext from Springboot directly and will build the driver, which probably requires you to inject to the context the required parameters. For example the database, MongoTemplate, etc. This depends on the type of Driver you are using. Find more information in the driver section.


# Springboot compatibility

Mongock Runner Framework Version compatibility
MongockSpringboot Springboot 2.X.X

# Configuration

Visit the configuration section in the runner page to see the list of the basic runner's properties.

# Features

# Runner type: ApplicationRunner vs InitializingBean

Springboot provides two options to delegate an execution, in this case the migration:

Mongock takes advantage of this aspects and, on top of the method buildRunner(), provides two other options to support the ApplicationRunner and InitializingBean.

When using autoconfiguration, you can set the runner type by configuration with:

runner-type: [applicationrunner | initializingbean]

Or with builder, with the methods:

Bear in mind that the runner, represented by a MongockApplicationRunner or a MongockInitializingBeanRunner, needs to be register as a bean, as follow:

public MongockInitializingBeanRunner mongockRunner(ConnectionDriver driver, ApplicationContext applicationContext) {
return MongockSpringboot.builder()

# Dependency injection

As mentioned in the get started section, the springboot runner takes the dependency injected to the migration classes(@ChangeUnit and the deprecated @ChangeLog), from the Springboot ApplicationContext:


# Profiles

Mongock supports the Spring @Profile annoation.

When a changeUnit is annotated with @Profile, it will only executed if any of the profiles present in the annotation is contained in the Spring activeProfiles array.

# Events

As explained in the events page, Mongock provides three Events: StartedEvent, SuccessEvent and FailureEvent. In the Springboot world, these are represented by:

To listen to these events you need to:

import org.springframework.context.ApplicationListener;
import org.springframework.stereotype.Component;
public class MongockSuccessEventListener implements ApplicationListener<SpringMigrationSuccessEvent> {
public void onApplicationEvent(SpringMigrationSuccessEvent event) {
System.out.println("[EVENT LISTENER] - Mongock finished successfully");

The example section shows how to use it in the builder.

# Examples

# Example with properties

- com.your.migration.package1
- com.your.migration.package2
change-motivation: Missing field in collection
decided-by: Tom Waugh
start-system-version: 1.3
end-system-version: 6.4
throw-exception-if-cannot-obtain-lock: true #Default true
origin: mongobeeChangeLogCollection
change-id: legacyChangeIdField
author: legacyAuthorField
timestamp: legacyTimestampField
change-log-class: legacyMigrationClassField
change-set-method: legacyChangeSetMethodField
track-ignored: false #Default true
transaction-enabled: true
runner-type: applicationrunner
enabled: true #Default true

# Example with builder

new HashMap() { {
put("change-motivation", "Missing field in collection");
put("decided-by", "Tom Waugh");
} })
.setLegacyMigration(new MongockLegacyMigration(