Mongogrator is a lightweight database migration package for MongoDB.
The original purpose of the package is to utilize a config file based on .ts
format to allow importing values and assign them to the config keys.
Since Mongogrator is mainly a CLI based package, it relies on the following dependencies
- typescript
- ts-node
- mongodb
Mongogrator comes with its own CLI. You can either install it globally
npm install -g mongogrator
mongogrator init
Or use it directly by adding npx prefix before every command
npx mongogrator init #--js
The init
command spawns the mongogrator.config.ts
file. You can also pass a --js
option to generate the config file in js format instead
Commands:
help Display the list of available commands
version Display the current version of Mongogrator
init --js Initialize config file
add[name] Adds a new migration file
list Display the list of all migrations and their status
migrate[path] Run the migrations
Options:
--js, -j Flag the file creation to be in js
--help, -h Add at the end of every command to get detailed help on it
--version, -v Display the current version of Mongogrator
A basic guide on how to use the package
Start by adding a new migration file with the desired name
mongogrator add insert_user
This will create the migration file under the directory assigned in the config migrationsPath
[!NOTE]
- The default migrations directory is
./migrations
, and file format ists
(typescript)
import type { Db } from 'mongodb'
export const migrate = async (_db: Db): Promise<void> => {
// Migration code here
}
The migrations are executed through the native MongoDB Node.js driver
import type { Db } from 'mongodb'
export const migrate = async (_db: Db): Promise<void> => {
_db.collection('users').insertOne({ name: 'Alex' })
}
You can add as many migrations as you want and then the list command to display the status of each
mongogrator list
This will print out a list of all the migrations, each of them has the status of either NOT MIGRATED
or MIGRATED
1726339397_add_user NOT MIGRATED
Naturally, the status will be NOT MIGRATED
as we haven't run the migration yet
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 migrations that are built in a different directory, simply add the directory path at the end of the command
mongogrator migrate /dist
Now if you run the list
command again, it will reveal that the file migration has completed
1726339397_add_user MIGRATED
{
_id: objectId(),
name: string,
createdAt: Date(),
updatedAt: Date()
}
Each migration log is created with the createdAt
date assigned before running the migration, and updatedAt
date is assigned after the migration is completed
{
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']
}
[!IMPORTANT] all path config values are relative to the location from which the command was called