MongoDB Version Control Using Mongock For Java
What is Mongock?
Mongock is a coding-based approach to manage and apply database schema changes to MongoDB databases using Java language.
Why do we need a database version control?
Usually, software applications will be developed with different team members in different environments like DEV, QA, PROD. As a version control for the code of this application, git will be used, but how version controlling of the database related to this application happens. As an example, the codebase of this application can be cloned from git and begin development with a fresh database. Next,
- Some schema changes will be added to the database.
- New indexes will be added to the database.
- Collection names will be changed
- The database may needed to be rollbacked later
This change will work with on local database. but that database changes are not included in the database which was deployed in the PROD environment or some other developer’s environment. When they run the application with new changes or when they deployed the software with new changes in prod, some exceptions may arise. So this problem can be resolved by using a database version control system. That is the reason to use database schema migration tools like liquibase or Mongock.
Why Mongock
There are many database schema migration tools like Liquibase, so what Mogock differentiates from them?
the reason is, liquibase mostly supports relational databases. However there is a plugin for liquibase-mongodb, but that doesn’t fully support NoSQL databases like MongoDB. Also some MongoDB commands in liquibase-mongodb plugin are not supported by the some cloud providers. collmod is a command that is going to be executed by liquibase-mongodb plugin will arise some exceptions when using that for AWS documentDB.
Mongock is a tool that was designed especially for MongoDB. Also Mongock has a coding-based approach, so it is easy to use than liquibase
Mongock Concepts
There are four main concepts that needed to be discussed under Mongock Concepts. they are
ChangeLogs
ChangeSets
Driver
Runner
ChangeLogs
Basically, ChangeLog is a java class that is annotated by @ChangeLog annotation. These are migration classes. They contain ChangeSets which are the set of transactions that should perform on our database. more than one ChangeLogs can be used as per application needs. Mongock will execute them by the order number that we provide to the ChangeLog with @ChangeLog annotation.
ChangeSets
ChangeSet is a java method inside the ChangeLog class which is annotated by @ChangeSet annotation. this contains a set of transactions that will be performed on the database. more than one ChangeSets can exist and each one will be executed by Mongock according to the order that is provided with @ChangeSet annotation.
Mongock will create a collection named mongockChangeLog to store the executed ChangeSets so next time Mongock will skip those ChangeSets.
changes can be applied to the database using MongockTemplate provided by Mongock, or MongoDatabase provided by MongoDB driver, or CustomBean, a custom-created bean in spring-boot. These options will provide as method parameters. (The recommended way is to use MongockTemplate).
One important fact is, if developers have a plan to use more than one changelog class, then they have to use a unique name for the id of change set in every changelog class
Driver
The driver is responsible for 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
Runner
This is the starting point of Mongock. this runner will create the process for execution of Mongock. This will happen via ApplicationRunner class inside the runner
these runners will deal 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). Currently, Mongock provides the following runners.
mongock-standalone
mongock-spring-v5
Mongock Configuration
Required Dependencies
In order to configure Mongock, four dependencies should be added to the classpath. Gradle is used as the building tool so Gradle dependencies should be added. Mongock schema migration happens in compile time so all the dependencies should be added as compile dependencies.
Also, an important fact to remember is that the versions of these dependencies and Spring-boot parent dependencies (In Gradle, that is a spring-boot plugin) should be always compatible with each other, to look compatibility please refer to this compatibilty_tabe
- Mongock BOM(Bills of Materials) dependency
- Mongock runner dependency for Spring
- Mongock driver dependency for MongoDB spring
- MongoDB and spring data dependency
Add ChangeLog file
A changelog file should be created. For example Java classes according to the versions can be created inside migrations the package. These are the class that was annotated using @ChangeLog annotation and contains the annotated methods with @ChangeSet annotation. more classes can be added as the database schemas or indexes grows.
Configure application.properties file
The application should be configured to find ChangeLog classes, for the location of migration package should be added to the configuration file
Also, it is needed to specify which ChangeSets should be executed for a particular migration. when the time that Mongock was added to this application, the database already existed. so creating collections from scratch is not necessary. but in DatabaseChangeLog file contains methods for creating collections and creating indexes that exist up to that point in the database. So the versions should be configured to resolve this issue.
A specific version can be given in @ChangeSetannotation. Then Mongock will execute the changesets whose versions are inside the range of the versions specified in application.properties file. That can be specified by adding starting version and end version in the configuration file as follows
