# 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(@EnableMongock)

# 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
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:
  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.github.cloudyrock.mongock.integrationtests.spring5.springdata3.changelogs.client.initializer")
    .addChangeLogsScanPackage("com.github.cloudyrock.mongock.integrationtests.spring5.springdata3.changelogs.client.updater")
    .setSpringContext(springContext)
    .withMetadata(
        new HashMap())
    .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.github.cloudyrock.mongock.integrationtests.spring5.springdata3.changelogs.client.initializer")
    .addChangeLogsScanPackage("com.github.cloudyrock.mongock.integrationtests.spring5.springdata3.changelogs.client.updater")
    .withMetadata(
        new HashMap())
    .setStartSystemVersion("1.3")
    .setEndSystemVersion("6.4")
    .setLockConfig(10,4,5)
    .setLegacyMigration(new MongockLegacyMigration(
        "mongobeeChangeLogCollection", true, "legacyChangeIdField", "legacyAuthorField", "legacyTimestampField", "legacyChangeLogClassField", "legacyChangeSetMethodField"))
    .setTrackIgnored(true)
    .setEnabled(true)
    .execute();