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:
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
When using properties file, you need to add the prefix `mongock.`.
You can find more additional properties in each runner page.
|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||
|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||
|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
|throwExceptionIfCannotObtainLock||property||Mongock will throw MongockException if lock can not be obtained. Builder method
|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
|transactionStrategy||property||Dictates the transaction strategy.
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.