mongoTrek is a Java library inspired by Liquibase for managing collection and document migrations within your application's database.

This library is a "roll-forward" migration tool, meaning to rollback changes, new migrations are required to undertake this task.

Compatibility

Version	MongoDB	Java	Java Mongo Migrations Support
<= 4.x	mongo-java-driver:[3.0,) mongodb-driver-legacy:[4.0,5.0)	1.8	YES
5.0.0	mongodb-driver-sync:[4.0,)	1.8	YES
6.0.0+	mongodb-driver-sync:[4.0,)	11	NO

Java Mongo Migrations Upgrade

mongoTrek is a fork from the Java Mongo Migrations project. As such, projects that have previously managed migrations using this project can upgrade to mongoTrek and it will understand the previous migrations schema version collection documents.

Note: No guarantees provided for this upgrade support from version 6.0.0 or later.

Dependency

Maven

<dependency>
    <groupId>net.ozwolf</groupId>
    <artifactId>mongo-trek</artifactId>
    <version>6.0.0</version>
</dependency>

Gradle

compile 'net.ozwolf:mongo-trek:6.0.0'

Provided Dependencies

As part of your own project, you will need to include the following dependencies:

Mongo Java Driver

This library was tested against the 4.8.2 MongoDB sync driver library version. If you require support for the mongodb-driver-legacy or mongo-java-driver libraries, refer to the 4.x versions of the library.

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>[4.8.2.4,5)</version>
</dependency>

Slf4j Implementation

This library is tested against the Logback Classic library at version 1.7.30

MongoDB Database Commands

mongoTrek uses the MongoDB database commands framework to execute commands.

Refer to the MongoDB Database Commands documentation.

Usage

Define Your Migrations File

The migrations file for mongoTrek is a YAML or JSON file that is either a resource in your classpath or a file on your file system. The library will first scan the classpath before the file system.

The file can define the schemaVersionCollection here. If the schema version collection is also defined via the MongoTrek.setSchemaVersionCollection(<string>) command, the value in the file will be ignored.

Each migration entry consists of:

• version [ REQUIRED ] - A unique version identifier. Migrations will be played in schemantic version order, regardless of their order in the migrations file (eg. version 2.0.0 will always be played ahead of 2.0.0.1)
• description [ REQUIRED ] - A short description of the migrations purpose
• author [ OPTIONAL ] - The author of the migration. If not supplied, the author will be recorded as trekBot
• command [ REQUIRED ] - The database command to run. Because mongoTrek uses YAML, this can be in the form of a direct JSON or YAML structure, as long as it meets the MongoDB Database Command requirements.

Example Migrations File

schemaVersionCollection: my_schema_version
migrations:
    - version: 1.0.0
      description: populate people base data
      author: John Trek
      command: {
        insert: "people",
        documents: [
            { name: "Homer Simpson", age: 37 },
            { name: "Marge Simpson", age: 36 }
        ]
      }
    - version: 1.0.1
      description: populate town base data
      command: {
        insert: "town",
        documents: [
            { name: "Springfield", country: "USA" },
            { name: "Shelbyville", country: "USA" }
        ]
      }

Map-Reduce Forced Collection Creation

If mongoTrek encouters a mapReduce command, it will ensure the collection being reduced exists. If it doesn't, it will run a simple createCollection call. It will use the default collection settings defined here in the MongoDB documentation.

Embedded Functions

For commands such as the MapReduce Command, functions should be enclosed as strings. For example:

migrations:
    - version: 1.0.0
      description: run a map-reduce
      command: {
        mapReduce: "towns",
        map: "function() { emit(this.country, 1); }",
        reduce: "function(country, towns) { return Array.sum(towns); }",
        out: "town_counts"
       }

Dates & Times

This library is designed to handle the $date strict JSON operator. Internally, it will convert the value into a valid Java Date object for the Java driver to interpret correctly.

The library currently supports date, time and date-time strings in the formats compatible with following DateTimeFormatter predefined formatters.

Running Your Migrations

To run your migrations, provide either a MongoDB Connection String URI or a MongoDatabase instance on initialization.

You can then either migrate your database (MongoTrek.migrate(<file>)) or request a status update (MongoTrek.status(<file>)). Both methods will return a MongoTrekState, allowing you to query applied, pending and current migration versions.

Example Usage

public class MyApplication {
    private final static Logger LOGGER = LoggerFactory.getLogger(MyApplication.class);
    
    public void start() {
        try {
            MongoTrek trek = new MongoTrek("mongodb/trek.yml", "mongodb://localhost:27017/my_app_schema");
                    
            trek.setSchemaVersionCollection("_my_custom_schema_version");
            
            MongoTrekState state = trek.migrate();
            
            LOGGER.info("Successfully migrated schema to version: " + state.getCurrentVersion());
        } catch (MongoTrekFailureException e) {
            LOGGER.error("Failed to migrate database", e);
            
            System.exit(-1);
        }
    }
}

Migration Results

As of version 3.0.0 of this library, the Migration class now contains the migration result as a Map<String, Object>.

With a MongoTrekState you can get the list of applied transactions and review the migration command result.

Logging Configuration

mongoTrek uses the LOGBack project log outputs.

The logger in question is the MongoTrek class logger (ie. Logger migrationsLogger = LoggerFactory.getLogger(MongoTrek.class);)

You can configure the output of migrations logger using this class.

Messages are logged via the following levels:

• INFO - All migration information (ie. configuration, versions, migration information)
• ERROR - If an error occurs (ie. invalid migration command definition or general connection/execution errors)