Mongogrator - a MongoDB migration tool for TS & JS

Repository here

Mongogrator is a very fast database migration CLI for MongoDB. Its purpose is to easily create and run migrations for development and production stages

Installing

Using the following command, it will automatically download, install and add Mongogrator to PATH

MacOS/Linux

curl -fsSL git.new/mongogrator-installer.sh | bash

Windows

powershell -c "irm git.new/mongogrator-installer.ps1 | iex"

List of commands

Mongogrator CLI
Usage: mongogrator <command> [options]

Commands:
   init [--js]               Initialize a new configuration file
   add                       Creates a new migration file with the provided name
   list                      List all migrations and their status
   migrate [config_path]     Run all migrations that have not been applied yet
   version, -v, --version    Prints the current version of Mongogrator

Flags:
   --help, -h                Prints the detailed description of the command

Usage guide

A basic guide on how to use the CLI

Adding new migrations

Start by initializing the config file

mongogrator init

This initializes a mongogrator.config.ts file in the location of the command. You can optionally pass a --js flag at the end of the command to initialize in a js file

Setup the url to the desired mongo cluster, and make sure it's running

mongogrator add insert_user

This will create the migration file under the directory key assigned in the config migrationsPath

The following is an example of a newly created ts migration file

import type { Db } from 'mongodb'

/**
 * This function is called when the migration is run.
 * @param _db The mongodb database object that's passed to the migration
 */
export const migrate = async (_db: Db): Promise<void> => {
  // Migration code here
}

The migrations are executed through the native MongoDB Node.js driver

Migration query example

import type { Db } from 'mongodb'

/**
 * This function is called when the migration is run.
 * @param _db The mongodb database object that's passed to the migration
 */
export const migrate = async (_db: Db): Promise<void> => {
  // Migration code here
  _db.collection('users').insertOne({ name: 'Alex' })
}

Migrations list

You can add as many migrations as you want and then call the list command to display the status of each

mongogrator list

This will print out a list of all the migrations, each has a status of either NOT MIGRATED or MIGRATED

┌───┬───────────────────────────────┬──────────────┐
│   │ migration                     │ status       │
├───┼───────────────────────────────┼──────────────┤
│ 0 │ 20240923150201806_insert_user │ NOT MIGRATED │
└───┴───────────────────────────────┴──────────────┘

Naturally, the status will be NOT MIGRATED as we haven't run the migration yet

Running the migrations

Run the migrations simply by calling

mongogrator migrate

This will run all the migrations and log them to the database under the specified collection name in the config logsCollectionName

For production purposes, you can pass the config path to the migrate command directly if it's not accessible under the same path

mongogrator migrate /dist

Now if you run the list command again, it will reveal that the migration file has been successfully executed

┌───┬───────────────────────────────┬──────────────┐
│   │ migration                     │ status       │
├───┼───────────────────────────────┼──────────────┤
│ 0 │ 20240923150201806_insert_user │ MIGRATED     │
└───┴───────────────────────────────┴──────────────┘

Logs collection schema

{
  _id: objectId(),
  name: string,
  createdAt: Date(),
}

Configuration

{
  url: 'mongodb://localhost:27017', // Cluster url
  database: 'test', // Database name for which the migrations will be executed
  migrationsPath: './migrations', // Migrations directory relative to the location of the commands
  logsCollectionName: 'migrations', // Name of the logs collection that will be stored in the database
  format: 'ts', // Format type of the migration files ['ts', 'js']
}

all the config keys with path values are relative to the location of the config file itself