# Introduction

This page explains the process of using the runner, configuration properties, etc. You can find a more practical guide in each runner page.

As mentioned in the technical overview, the runner is the orchestator that handles the environment and it's responsible of the process.

The natural steps you should follow are:

# Runner options

There are specific runners for certain environments, like frameworks, etc.

Currently Mongock provides:

# Build

Mongock offers two build approaches:

# Configuration

When using properties file, you need to add the prefix `mongock.`.

You can find more additional properties in each runner page.

Property type Description Type Default value
driver component The Mongock driver. This parameter can only be passed programatically. When opting for autoconfiguration, Mongock builds the driver and injects it to the runner. ConnectionDriver Mandatory
migrationScanPackage property The list of migration(changeUnits and changeLogs) classes and/or packages where they are stored. List< String > Mandatory
metadata property Custom data attached to the migration. It will be added to change entry in the mongock table/collection. Map<String, Object> null
startSystemVersion property System version to start with. String 0
endSystemVersions property System version to end with. String MAX_VALUE
trackIgnored property Specifies if an ignored changeUnit(already executed for example) should be track in the Mongock table/collection with status IGNORED. boolean false
enabled property If false, will disable Mongock execution. boolean NO
serviceIdentifier property Application/service instance's indentifier. String null
defaultMigrationAuthor property Author field is not mandatory in ChangeUnit. The field author in this annotation is optional. However for backward compatibility it's still required. If it's provided in the ChangeUnit annotation, this value is taken. If not, Mongock will look at this property. If not provided, the default value is provided. String default_author
throwExceptionIfCannotObtainLock property Mongock will throw MongockException if lock can not be obtained. Builder method dontFailIfCannotAcquireLock to turn it to false. boolean long
transactionEnabled property Indicates the whether transaction is enabled. For backward compatibility, this property is not mandatory but it will in coming versions. It works together with the driver under the following agreement: Transactions are enabled only if the driver is transactionable and this field is true or not provided. If it's false, transactions are disabled and will throw an exception if this field is true and the driver is not transactionable. To understand what transactionable means in the context of the driver and how to make a driver transactionable, visit the section driver. boolean null
transactionStrategy property Dictates the transaction strategy. CHANGE_UNIT means each changeUnit(applied to deprecated changeLog as well) is wrapped in an independent transaction.EXECUTION strategy means that Mongock will wrap all the changeUnits in a single transaction. Note that Mongock highly recommend the default value, CHANGE_UNIT, as the EXECUTION strategy is unnatural and, unless it's really designed for it, it can cause some troubles along the way. String CHANGE_UNIT

# Execution

Although each builder may provide additional options to build the runner, all of them share the basic method buildRunner(), which returns a MongockRunner instance. This interface provides multiple methods, one of them is execute(), which starts the migration process. This is the natural way to run Mongock when using the standalone runner.

On the other hand, when opting for autoconfiguration, the user doesn't need to worry about the execution, Mongock, with the help of the framework, takes care of it.