Runner

In Main concepts we already mentioned the concept of runners. Runners are the ones dealing with the process logic and framework.

Motivation

While Mongock standalone could be run with any framework, it would be nice that the user has some kind of adaption to take advantage of the underlying frameworks, for any relevant framework in the market. For example, in Spring, been able to use the Spring context, profiles or property files, etc. And once having that, it would be ideal for the user to be able to use version of Mongock adapted to the specific framework's version he is using and once a new version come up and he decide to not upgrade, still having support for the legacy version.

This is the goal of Mongock runners. Currently Mongock only provides support for standalone(which can be run in any framework) and Spring 5, but the objective is to provide support for any relevant framework in the market.

How it works

Technically, as drivers, runners are simple implementations of the same interface which, providing a bridge between the drivers and the process executor.

The idea is to provide a specific runner for every relevant framework in the market. Open source users will be able to add runners, following the runner specification.

Runners available

Currently Mongock provides two runners: Mongock standalone and Spring 5.

Mongock standalone runner

It does not used any framework support for its execution. Ideally when running standalone Java applications, you want to have all the control of the Mongock instance and when it's executed or when you are using a framework for which there is no specific Mongock runner, you can use Mongock standalone while we develop it.

Mongock Spring v5 runner

Based on Spring 5 and Spring Boot 2, its objetive to provide the easiest way to run Mongock with it. It provide support for Spring profiles, context, properties, annotation approach based on Spring configuration, etc.

Unlike Mongock standalone, it provides two building approach: the traditional builder approach and annotation approach(@EnabbleMongock)

Building time: Runner

When use it the annotation approach, you just need to import the required Mongock runner dependency, annotate your SpringBootApplication with @EnableMongock and everything is done for you. All the configuration should be provided via properties file.

However, if you opt for the manual builder approach, you need to build the runner yourself by using Mongock builder

Configuration

Configuration parameter

Default value

Type

Description

Link

changeLogScanPackage

mandatory. At least one.

List<String>

Instructs Mongock where to find the changeLog classes.

link

springContext

mandatory for Spring

ApplicationContext

Sets the spring Application context for bean injections into ChangeSet methods. It's where the custom beans, MongoTemplate, profiles, etc. is take from.

link

eventPublisher

null

ApplicationEvent Publisher

Sets the spring application event publisher to be able to handle the life cycle events

link

migrationStartedListener

null

Runnable

Handler for standalone start event

link

migrationSuccessListener

null

Consumer for Standalone Migration SuccessEvent

Handler for standalone success event

link

migrationFailureListener

null

Consumer for Standalone Migration FailureEvent

Handler for standalone failure events

link

metadata

null

Map<String, Object>

Custom data attached to the migration. It will added to all changes in changeLog collection

link

startSystemVersion

"0"

String

System version to start with

link

endSystemVersions

MAX_VALUE

String

System version to end with.

link

throwExceptionIfCannot....

true

boolean

Mongock will throw MongockException if lock can not be obtained. Builder method setLockConfig

link

legacyMigration

null

Object

Configuration related to migrate from legacy systems.

link

trackIgnored

false

boolean

Specifies if ignored changeSets(already executed, etc.) should be track in the changeLog collection with IGNORED status

link

enabled

true

boolean

If false, will disable Mongock execution

link

When using the builder method setLockConfig, which takes lockAcquiredForMinutes, maxWaitingForLockMinutes and maxTries as parameters, will implicitly set throwExceptionIfCannotObtainLock to true.

properties
mongock-spring-v5
standalone
properties
mongock:
change-logs-scan-package:
- com.github.cloudyrock.mongock...changelogs.client.initializer
- com.github.cloudyrock.mongock...changelogs.client.updater
metadata:
change-motivation: Missing field in collection
decided-by: Tom Waugh
start-system-version: 1.3
end-system-version: 6.4
lock-acquired-for-minutes: 10
max-waiting-for-lock-minutes: 4
max-tries: 5
throw-exception-if-cannot-obtain-lock: true
legacy-migration:
origin: mongobeeChangeLogCollection
mapping-fields:
change-id: legacyChangeIdField
author: legacyAuthorField
timestamp: legacyTimestampField
change-log-class: legacyChangeLogClassField
change-set-method: legacyChangeSetMethodField
track-ignored: true
enabled: true
mongock-spring-v5
builder
.addChangeLogsScanPackage("com.your.changelog.package")
.addChangeLogsScanPackage("com.your.changelog.package")
.setSpringContext(springContext)
.setEventPublisher(applicationEventPusblisher)
.withMetadata(
new HashMap(){{
put("change-motivation", "Missing field in collection");
put("decided-by", "Tom Waugh");
}})
.setStartSystemVersion("1.3")
.setEndSystemVersion("6.4")
.setLockConfig(10,4,5)
.setLegacyMigration(new MongockLegacyMigration(
"mongobeeChangeLogCollection",
true,
"legacyChangeIdField",
"legacyAuthorField",
"legacyTimestampField",
"legacyChangeLogClassField",
"legacyChangeSetMethodField"))
.setTrackIgnored(true)
.setEnabled(true)
standalone
builder
.addChangeLogsScanPackage("com.your.changelog.package")
.addChangeLogsScanPackage("com.your.changelog.package")
.withMetadata(
new HashMap(){{
put("change-motivation", "Missing field in collection");
put("decided-by", "Tom Waugh");
}})
.setStartSystemVersion("1.3")
.setEndSystemVersion("6.4")
.setLockConfig(10,4,5)
.setLegacyMigration(new MongockLegacyMigration(
"mongobeeChangeLogCollection",
true,
"legacyChangeIdField",
"legacyAuthorField",
"legacyTimestampField",
"legacyChangeLogClassField",
"legacyChangeSetMethodField"))
.setTrackIgnored(true)
.setTrackIgnored(true)
.setEnabled(true)
.setMigrationStartedListener(()-> {/**TODO your business logic**/ })
.setMigrationSuccessListener(successEvent-> {/**TODO your business logic**/ })
.setMigrationFailureListener(failureEvent-> {/**TODO your business logic**/ })
.execute();