Main concepts

This page explains all the essential concepts you will need to know to understand what Mongock is and how it works.

Mongock structure

Mongock consists in 3 main type of objects: ChangeLogs, driver and runner. Builders are simply used to configure and build these 3 components.


A Mongock executable process a set of changeLogs, which are the classes that will contain the actual migration. A changeLog consists in a bunch of methods called changeSet, which is a single task (set of instructions made on a database). In other words a changeLog is a class annotated with @ChangeLog and containing methods annotated with @ChangeSet.ChangeLogs will be explained further in Creating changeLogs

We recommend to read our best practices for creating and designing changeLogs.

@ChangeLog(order = "1")
public class ClientInitializerChangeLog {
@ChangeSet(id = "data-initializer", author = "mongock", order = "001")
public void ClientInitializer(ClientRepository clientRepository) {
List<Client> clients = IntStream.range(0, INITIAL_CLIENTS)
.mapToObj(i -> new Client(i))


The driver is responsible of dealing with the specific database driver or library wrapping the database access such as Spring data. Currently Mongock provides the following drivers:

  • mongodb-v3-driver

  • mongodb-sync-v4-driver

  • mongodb-springdata-v2-driver

  • mongodb-springdata-v3-driver

MongockConnectionDriver driver = new SpringDataMongo3Driver(mongoTemplate);

Although one of the main goals of this is to keep providing support for legacy drivers, while continue adding new drivers, once a new version(for example sync-4-driver) is added, the legacy one(v3-driver) will be still supported, but not evolved, meaning this that we won't provide any new feature for it, just bug fixes. However the level of support will depend on the type of Mongock edition you are using. Please take a look to support policy.


Runners are the ones dealing with the process logic and framework. For example, there is a runner for Java standalone applications(with no framework at all) or for specific frameworks(and versions), if it's needed or useful. Currently Mongock provides the following runners:

  • mongock-standalone

  • mongock-spring-v5

As drivers, legacy versions of the same driver will be supported(subscribed to the support policy applied), but won't be enhanced. Please take a look to support policy.

When using MongockStandalone, once you have built the runner instance, you need to run it manually with runner.execute()


The mechanism to build a Mongock instance(with the specific driver) to process your migrations.

In version 4 we have added a new approach in Spring based on annotation that makes all the work for you. However, if you need to have more control over the bean creation or you are not using Spring or any other reason, you still have the manual builder approach available.

Spring 5 ApplicationRunner
Spring 5 InitializingBean
Spring 5 ApplicationRunner
Spring 5 InitializingBean
MongockStandalone.Runner runner = MongockStandalone.builder()
// when using standalone runner, you need to run it manually

Annotation approach is the recommended way when using Spring, however you still have the builder approach if you need more control, you are not using Spring or simply you are more comfortable with it.