This tutorial shows you how to connect to MongoDB using Flyway with Native Connectors. Native Connectors is a new engine designed to handle migrations without relying on the JDBC framework.

Prerequisites

Before we can get started, please make sure you have the following in place:

• Flyway v11.0.x or later
• A MongoDB instance running on localhost:27017 (Using docker is a great way to get started)
• A user with the root role on the admin database
• Port 27017 is publicly exposed from within the docker container
• If you are using javascript migrations then you'll need mongosh to be installed

You can verify that this is working using the MongoDB Compass tool to connect to your database.

Connecting to MongoDB

In this tutorial we'll be setting things up in the TOML configuration file:

[environments.mongodb]
url = "mongodb://localhost:27017/"
user = "your username"
password = "your password"

[flyway]
environment = "mongodb"

Note: MongoDB defaults to the test database if you don't specify one in the url.

You should now be able to run flyway info -environment=mongodb to verify that Flyway can connect to your MongoDB instance.

Migration files

Native Connectors enables two different types of migration file: JSON and JavaScript. The JSON files are executed using a native MongoDB API, while the JavaScript files are executed using the MongoDB shell on your computer.

Note: You can check if your MongoDB shell is installed by running mongosh --version in your terminal. If it isn't, the install guide is here.

Here is an insert statement in each format:

JSON

{
  "insert": "user",
  "documents": [ {"name":  "Ada Lovelace", "age":  205} ]
}

Javascript

db.user.insert({name: "Ada Lovelace", age: 205});

You will need to decide which format is best for you in your environment. In order to configure Flyway to look for MongoDB migration files, you will need to set the following configuration:

JSON

[flyway]
sqlMigrationSuffixes = [".json"]

Javascript

[flyway]
sqlMigrationSuffixes = [".js"]

Once you have your migration file and have configured Flyway for the appropriate file type, you can proceed

In this tutorial we are creating a versioned migration called V1__my_mongodb_migration.js or V1__my_mongodb_migration.json in the sql\ folder of your flyway installation.

Migrating

Now run the following command:

./flyway migrate info -environment=mongodb

You should see output similar to the following:

Flyway OSS Edition 11.1.0 by Redgate

See release notes here: https://rd.gt/416ObMi
Database: <<details removed>> (MongoDB)
Schema history table "test"."flyway_schema_history" does not exist yet
Successfully validated 1 migration (execution time 00:00.934s)
Creating Schema History table "test"."flyway_schema_history" ...
Current version of schema "test": << Empty Schema >>
Migrating schema "test" to version "1 - my mongodb migration" [non-transactional]
Successfully applied 1 migration to schema "test", now at version v1 (execution time 00:01.231s)
Schema version: 1

+-----------+---------+------------------------------+--------+---------------------+---------+----------+
| Category  | Version | Description                  | Type   | Installed On        | State   | Undoable |
+-----------+---------+------------------------------+--------+---------------------+---------+----------+
|           |         | << Flyway Schema Creation >> | SCHEMA | 2024-12-12 10:33:15 | Success |          |
| Versioned | 1       | my mongodb migration         | SQL    | 2024-12-12 10:33:16 | Success | No       |
+-----------+---------+------------------------------+--------+---------------------+---------+----------+

You should also notice a new record (Ada Lovelace) within a new collection (user) within your Mongo tooling. As Mongo is a document database, there is no requirement to create a schema before inserting data as it will create collections ad-hoc.