Mongock Integration

Integrating Mongock with Spring Boot Applications

1. Install required dependencies

<dependency>
    <groupId>io.mongock</groupId>
    <artifactId>mongock-springboot-v3</artifactId>
    <version>5.4.2</version>
</dependency>

<dependency>
    <groupId>io.mongock</groupId>
    <artifactId>mongodb-springdata-v4-driver</artifactId>
    <version>5.4.2</version>
</dependency>

2. Add MongoTransactionManager configuration

@Configuration
public class MongoConfiguration {

    @Bean
    public MongoTransactionManager transactionManager(MongoTemplate mongoTemplate) {
        TransactionOptions transactionalOptions = TransactionOptions.builder()
                .readConcern(ReadConcern.MAJORITY)
                .readPreference(ReadPreference.primary())
                .writeConcern(WriteConcern.MAJORITY.withJournal(true))
                .build();
        return new MongoTransactionManager(mongoTemplate.getMongoDatabaseFactory(), transactionalOptions);
    }
}

3. Add annotation for the Spring Boot application class to enable Mongock: @EnableMongock

4. Add application properties to configure Mongock

mongock.migration-scan-package=dev.veronb.mongock_demo.mongo.patches
mongock.enabled=true
mongock.start-system-version=1
mongock.end-system-version=1
mongock.transaction-strategy=execution
mongock.transaction-enabled=true

5. Add ChangeUnit classes(db patches) inside the defined package of mongock.migration-scan-package

Working with Local MongoDB Instance

• For transactions to work properly with the transaction manger config, the connected MongoDB should be running as a replica set
• Change application property mongock.transaction-enabled to false to avoid exceptions in local environment

Guidelines/Best Practices

• Long running patches should be run separately using node mongodb scripts to eliminate the server load
• Patches/ChangeUnits should be managed by the system/release version by changeing the @ChangeUnit's system version as well as the mongock.start-system-version and mongock.end-system-version in application.properties
• ChangeUnit order should be managed when merging each PR. Order must be unique across all ChangeLog classes.
• ChangeLog file naming convention: OperationSummaryChangeLogDateTime (ex: UpdateUserStatus202405071630)

Additional Resources

• ChangeUnit Templates: src/main/java/dev/veronb/mongock_demo/templates
• Mongock Integration Demo Presentation
• Mongock Docs - Spring Boot Runner
• Mongock 101
• 5 steps to Use Mongock for MongoDB Changelogs