Choosing a Migration Tool

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.

The three tools in this guide are not interchangeable — each one targets a different combination of "what am I migrating" and "what does my codebase already look like." This page gives a default recommendation per situation and names the specific reasons to deviate from it, in the same style as Choosing the Right Database.

Default: Liquibase for a Relational/SQL Target

If the target is a relational database and there is no existing investment in Mongock, default to Liquibase. It has no JVM requirement to run standalone (only the CLI, Maven/Gradle plugin, or Spring Boot integration if you do run on the JVM), its changelog is declarative (SQL, XML, YAML or JSON) and reviewable by a DBA who doesn’t read the application’s language, and it is the most mature and widely adopted of the three for relational schemas.

Deviate from this only when the target is not relational — see below.

Mongock: An Existing MongoDB + Java/Spring Project, Already Invested

Choose Mongock when a project already has MongoDB, is on Java/Spring, and already has Mongock change units in place, with no specific reason to move off it. Its code-first @ChangeUnit model fits naturally into a JVM codebase, and there is real switching cost — rewriting @ChangeUnit classes as Liquibase changelogs (which doesn’t natively target MongoDB the way it targets SQL) or as Flamingock @Change classes — that has to be worth paying before you pay it.

Do not default to Mongock for a new project. It is still maintained, but its own documentation positions Flamingock as the forward path (Coming from Mongock), and starting new work on the predecessor when the successor is the vendor’s own recommended direction just moves the eventual migration cost later without avoiding it.

Flamingock: New Projects, Multiple Target Systems, or Migrating Off Mongock

Choose Flamingock when:

  • You are starting a new project that will use MongoDB, or any of Flamingock’s other supported target systems.

  • You need one Change-as-Code model across several target systems — SQL, MongoDB, DynamoDB, Couchbase, and non-database systems such as message brokers, external APIs or cloud services — instead of running a separate tool per target (Flamingock: Changes & Target Systems).

  • You have an existing Mongock project and no reason to stay on it — Flamingock provides a documented migration path (Coming from Mongock) rather than a rewrite from scratch.

Flamingock’s safety-by-default philosophy (stopping and requiring manual intervention rather than guessing when a safe outcome can’t be guaranteed) and its explicit target-system model also make it the better fit whenever a change unit has to coordinate a database change with a side effect on a non-database system — something neither Liquibase nor Mongock is designed to express directly.

Decision Flowchart

flowchart TD Start[Need to migrate a schema/model?] --> Q1{Single relational/SQL
database only?} Q1 -->|yes| Liquibase[["Liquibase"]] Q1 -->|no| Q2{Existing Mongock project,
no reason to migrate?} Q2 -->|yes| Mongock[["Mongock"]] Q2 -->|no| Q3{New project, multiple target
systems, or migrating off Mongock?} Q3 -->|yes| Flamingock[["Flamingock"]] Q3 -->|no| Flamingock

Summary Table

Situation Default Why

New relational/SQL project

Liquibase

Declarative changelog, DBA-reviewable, no JVM requirement.

Existing MongoDB + Java/Spring, already on Mongock

Mongock

Switching cost outweighs the benefit without a specific driver.

New MongoDB (or other) project

Flamingock

Vendor-recommended forward path; one model across target systems.

Multiple target systems (SQL + MongoDB + non-database)

Flamingock

The only one of the three built for this from the start.

Migrating an existing Mongock codebase forward

Flamingock

Documented migration path — see Coming from Mongock.