Mongock 5 released!! Please visit the upgrade page to follow easy process.

# Introduction

Mongock is a Java based migration tool as part of your application code for Distributed environments. It allows developers to execute safer migrations by having ownership and control over data migrations during the Application deployment process as code and data changes are shipped together.

It was originally designed for MongoDB data migrations and the product is evolving to provide a wider suite of database compatibility whilst providing transactional execution features for use cases that require state management in distributed systems.

# Why Mongock?

Our mission is to enable developers to deploy and manage stateful data migrations in distributed systems in a safe and reliable manner. If you are looking for migrating data for your Java Application Services in a safe and reliable manner via code, Mongock is your best bet.

In a nutshell:

Get more information about our support model at​ and we can help you walking you to production.

# How it works

# 1. Scenario

Lets describe a scenario where the use of Mongock plays a big role:

We have a microservice called client-service, which uses the table/collection clients

As part of the development, we have a new User Story which requires your application to get some clients data from a third party system and persist them into database, in the clients table/collection. This is only required once and must be performed as part of the release.

In addition, the client-service is deployed in a distributed environment running with more than one node and with horizontal scaling.

# 2. Your migration changes (link)

We first need to implement the migration to retrieve the data from the third party system and persist it in the database. For this we use the ChangeUnit, which is Mongock's unit of Migration. This will be where we write the code.

Note: From version 5, ChangeLog annotation is deprecated (though remains for backwards compatibility). It's been replaced by @ChangeUnit.

Please, visit the ChangeUnit section for more information.

# 3. The persistent layer (link)

We need to access the database for multiple reasons:

For allowing Mongock to access the database and persist state changes, we will use the Mongock Driver. The driver contains all the information and mechanisms to access to the database. Mongock provides multiple drivers for different databases. The developers can choose the most suitable and configure the driver by providing some information like the the target schema, etc.

Please, visit the Driver section for more information.

# 4. Run the migration

Once we have implemented our migration in our changelog and configured the persistent layer using a Mongock driver, we need to run the migration. For this, we will use the Mongock Runner.

The Mongock Runner orchestrates the configurations, environment/framework settings, the driver and the ChangeUnits and runs all migrations in an orderly manner. The most common use case is that the application won't start until the migration has been succesfully finalized (although this behaviour can be altered). This means that if the list of migrations fail, the application will stop its startup process and exit. This will be retried again in the next startup and Mongock will continue the migration where it left.

Great, we have the migration done, tested, deployed and working nicely. Awesome πŸŽ‰

Mongock provides multiple runners for framework compatibility: for standalone applications, Springboot and many others coming soon. Please, visit the Runner section for more information.

For a more in-depth description of Mongock, please visit the Technical Overview section

# ... Cool, but we got a new user story! 😱

But now a new User Story has arrived where it requires us to add a new field. Well, we already have Mongock setup, all it requires is to create another ChangeUnit to address this change in the same way we did previously. Don't worry, Mongock will take care of running only the ChangeUnits that haven't been executed yet.

Note that a ChangeUnit represents a unit of migration, which means that each ChangeUnit is wrapped in a transaction. As soon as it's finished, it's commited.

# ... other ways of running Mongock

The explained way of running Mongock is the common and traditional use case. However, Mongock can be used in wider use cases and offers more operations to support these.

You can use the Mongock CLI to run the same migration, but also other operations like undo, list and more supported operations. The purpose is to provide a flexible manner of executing migrations.

Please, visit the CLI section for more information.