Mongock: Getting Started

This section documents schema/database evolution using version-controlled migration tools — Liquibase (relational/SQL), Mongock (MongoDB, Java-native) and Flamingock (Mongock’s successor, generalized to any external system) — as described by each tool’s own official documentation: liquibase.org and docs.liquibase.com for Liquibase, docs.mongock.io for Mongock, and docs.flamingock.io for Flamingock — which are the references these pages are written and verified against.

This content was generated with the assistance of AI and should be verified against those official docs before being relied on in production.

Mongock is now maintained under the Flamingock GitHub organization (github.com/flamingock/mongock), and Flamingock is positioned as its successor — see Coming from Mongock. Readers starting a new project should default to Flamingock unless they have a specific reason to stay on Mongock.

This section’s bibliography lists the reference material consulted while preparing these pages.

Mongock migrates MongoDB from Java, using code-first classes instead of a declarative changelog file. This page covers the drivers and runners available and walks through a first @ChangeUnit.

Drivers

The driver is which MongoDB Java client Mongock uses under the hood to execute a change unit’s operations:

Driver Notes

MongoDB Sync

The official synchronous MongoDB Java driver directly — the most common choice, no additional framework required.

Spring Data

Uses a project’s existing MongoTemplate/MongoRepository configuration, so change units can reuse Spring Data mappings and converters already defined for the application.

Reactive

The reactive MongoDB driver, for a project already built on Project Reactor/RxJava.

Pick the driver that matches how the rest of the application already talks to MongoDB, so change units can share connection configuration and, for Spring Data, object mapping.

Runners

The runner is how Mongock is invoked:

  • Standalone — Mongock runs as a plain Java library call, independent of any framework, useful for a migration-only job (a CLI tool, an init container) that isn’t itself a Spring Boot application.

  • Spring Boot — Mongock hooks into the Spring Boot application lifecycle and runs automatically at startup, the same auto-run-on-startup model as Liquibase’s Spring Boot integration, configured via application.yml:

mongock:
  migration-scan-package:
    - com.example.app.migrations

See Mongock Documentation for the exact starter dependency per driver/runner combination.

A First @ChangeUnit

@ChangeUnit(id = "create-person-index", order = "001", author = "alberto")
public class CreatePersonIndexChangeUnit {

    @Execution
    public void execution(MongoDatabase db) {
        db.getCollection("person")
          .createIndex(Indexes.ascending("email"), new IndexOptions().unique(true));
    }

    @RollbackExecution
    public void rollback(MongoDatabase db) {
        db.getCollection("person").dropIndex(Indexes.ascending("email"));
    }
}

Mongock discovers this class via classpath scanning (the migration-scan-package configured above), runs its @Execution method if create-person-index hasn’t already been recorded as applied, and records it afterward. See Mongock: ChangeUnits for the full annotation reference, and the Migration / ChangeUnit reference for the official source.