Mongock Runner
Table of Contents
# 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:
- Decide the right runner for your project from the available options.
- Import the maven dependencies(which can be found in each runner page).
- Build the runner.
- Execute it.
# Runner options
There are specific runners for certain environments, like frameworks, etc.
Currently Mongock provides:
# Build
Mongock offers two build approaches:
-
Builder approach: The user manually configures and executes the runner by using the runner builder. Normally by setter methods. Regardless the type of runner, all of them provides an static method
builder()which returns the builder. -
Autoconfiguration: Mongock automatically configures and executes the runner by taking the configuration from properties file and taking advantage of the underlying framework. However, It still uses the builder behind the scenes, but it's transparent to the user.
Once the runner is built, it can only run once
# 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 |
| transactional | 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.