Skip to content
Go to file

MonJam Build Status codecov

MongoDB migration


  • Gradle plugin
  • Java and script migration
  • Multi-document transaction (MongoDB 4.0+)

Road Map

  • Integration with Spring MongoTemplate
  • Maven plugin
  • Validate, info, clean command


Add gradle plugin, dependency and configuration in your build.gradle.

plugins {
    id 'io.github.oun.monjam' version '0.5.0'

repositories {

dependencies {
    compile 'io.github.oun:monjam-core:0.5.0'

monjam {
    url = 'mongodb://localhost:27017/?replicaSet=rs0'
    database = 'monjam'
    collection = 'schema_migrations'
    location = 'db/migration'

See the code example for Spring-based application.


Create Migration

Annotated class with @MongoMigration annotation and each methods with @Migrate annotation. Method with annotation parameter type MIGRATE and ROLLBACK will be executed on running migrate and rollback command respectively.

Annotation based Java Migration

package db.migration;

import com.monjam.core.annotation.Migrate;
import com.monjam.core.annotation.MongoMigration;
import com.monjam.core.api.Context;
import com.monjam.core.api.MigrationType;

public class UserMigration {
    @Migrate(type = MigrationType.MIGRATE, version = "1.0.0", description = "Change user prefix type")
    public void changeUserPrefixType(Context context) {
        // Execute on migrate version 1.0.0

    @Migrate(type = MigrationType.ROLLBACK, version = "1.0.0", description = "Revert user prefix type")
    public void revertChangeUserPrefixType(Context context) {
        // Execute on rollback version 1.0.0

Java Migration

Create java based migration class implementing Migration interface. The up and down method will be executed upon running migrate and rollback command respectively.

package db.migration;

import com.monjam.core.api.Context;
import com.monjam.core.api.Migration;

public class V1_0_0__Change_user_prefix_type implements Migration {
    public void up(Context context) {
        // Execute on migrate

    public void down(Context context) {
        // Execute on rollback

Script Migration

Create migrate script V1_0_0__Change_user_prefix_type.js

db.users.update({prefix: 'Mr.'}, {$set: {prefix: 1}}, {multi: true});
db.users.update({prefix: 'Mrs.'}, {$set: {prefix: 2}}, {multi: true});

File Name Pattern

Java class and script file must follow naming pattern {Prefix}{Version}__{Description}

  • Prefix: V for migrate, U for rollback (applicable to script migration)
  • Version: Sem-ver format separated each part with underscored
  • Separator: Two underscores
  • Description: Underscores separated words

Execute Migrate

./gradlew monjamMigrate

As each migration get applied, the schema migration history collection (default to schema_migrations) is updated with each document corresponding to applied migration

_id version description executedAt
5d3bbedb93b76e755467566d 1.0.0 Change user prefix type 2019-07-27T03:02:51.555Z


Command Gradle Task Description
Migrate monjamMigrate Migrates database to the latest version or target version
Rollback monjamRollback Rollback the most recently applied migration or target version


Configuration can be defined in build.gradle.

monjam {
    url = 'mongodb://localhost:27017/?replicaSet=rs0'
    database = 'monjam'
    collection = 'schema_migrations'
    location = 'db/migration'

or using gradle properties passed directly via command-line. ./gradlew monjamMigrate -Pmonjam.username=admin -Pmonjam.password=secret

Name Description Default
url Connection url -
database Database name -
username Username -
password Password -
authDatabase Authentication database name admin
collection Collection that store applied schema migrations schema_migrations
location Schema migration files locations db/migration
target Target version to migrate or rollback. For migrate, migration with version higher will be ignored. For rollback, migration with version equals or lower will be ignored latest version (migrate), previous version (rollback)
scriptMigrationExtension Script migration file extension js


No packages published


You can’t perform that action at this time.