Multi-environment MongoDB migrations for Node.js
npm install drift-mongoDrift
=====
Drift is a simple multi-environment MongoDB migrations CLI tool for Node.js.
#### Globally
``
npm install -g drift-mongo
When installed globally, you can use the drift command as needed.
#### Individual project
`
npm install drift-mongo --save-dev
When installed in a project, you can use npx drift within the project folder structure.
You can run drift or drift --help to see the CLI commands.
`
Usage: drift [options] [command]
A CLI for multi-environment MongoDB migrations with Node.js
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
init initializes drift config
create
env
status [options] checks the status of migrations
up [options] runs all pending migrations
down [options] rolls back the last migration
help [command] display help for command
`
Drift requries Node 22 (or higher) installed.
In the root of the project you'd like to setup migrations for, initialize a new drift configuration.
`
$ drift init
Initializing drift config...
Drift configuration generated.
Use your favorite editor to edit the config file at drift/drift.json
`
Running this command did two things:
1. created these folders: drift/migrations
2. created a file in the drift folder
The configuration file, drift.json, was created with a default environment: dev. Edit this file with your development environment details.
The drift.json file maintains your drift configuration for this project, with this initial object structure:
`json`
{
"migration_folder": "migrations",
"envs": {
"dev": {
"mongo_host": "mongodb+srv://user:pass@localhost:27017",
"mongo_db": "platform",
"mongo_collection": "migrations"
}
}
}
- migration_folder: Lets you change the name/path of the migrations folder.envs
- : Holds a environment config object for each configured environment.
Individual environment configurations have three config properties:
- mongo_host: The URI to the MongoDB cluster for the given environment.mongo_db
- : The name of the database you want to run migrations on for the given environment.mongo_collection
- : The name of a collection you want to create/use to track migrations for the given environment.
Important: Add the drift.json file to your .gitignore.
You can add an environment using the CLI, or by editing the drift.json file.
`
Usage: drift env [options]
Adds a new environment to use
Options:
-h, --help display help for command
`
To add a production environment, you can use the following command:
`
$ drift env prod
Environment added: prod
Edit the environment at drift/drift.json
`
Running this command added a new object to the envs object in the drift.json configuration file.
`json`
"envs": {
"prod": {
"mongo_host": "mongodb+srv://user:pass@localhost:27017",
"mongo_db": "platform",
"mogno_collection": "migrations"
}
}
Edit drift.json to add your connection and DB details.
Use the CLI to add a new migration to drift.
`
Usage: drift create [options]
Creates a new migration
Options:
-h, --help display help for command
`
To add a (test) migration, you can use the following command:
`
$ drift create test
Creating migration: test
Migration created!
Edit the migration at drift/migrations/1664591812475-test.js
`
Running this command added a new migration to the configured migrations folder (migrations by default).
Use migration files to perform changes to your database. New migration files are created in the configured migrations folder (migrations by default):
`javascript`
export const up = async (db, client) => {
// Migration code goes here
}
export const down = async (db, client) => {
// Rollback code goes here
}
Edit this file with your migration code. The db object is the official MongoDB object, the client object is a MongoClient instance.
Migrations use async-await and your migration code must use async-await and return a promise.
#### Example
`javascript`
export const up = async (db, client) => {
await db.collection('test').insertOne({test: 'test'})
}
export const down = async (db, client) => {
await db.collection('test').deleteOne({test: 'test'})
}
Run all pending migrations on a given environment. If no environment is specified, dev is configured as default.
`
Usage: drift up [options]
runs all pending migrations
Options:
-e --env
-h, --help display help for command
`
To run all pending migrations for the dev (default) environment use the following command:
`
$ drift up
Migrated: 1664591812475-test.js
Migrations complete!
`
To run all pending migrations for the prod environment, use the following command:
`
$ drift up --env prod
Migrated: 1664591812475-test.js
Migrations complete!
`
Any error caught will stop the process.
When you need to revert migrations for a given environment, migrating down will revert back through the completed migrations one at a time.
`
Usage: drift down [options]
rolls back the last migration
Options:
-e --env
-h, --help display help for command
`
To revert the last completed migration for the dev (default) environment use the following command:
`
$ drift down
Downgraded: 1664591812475-test.js
Rollback complete!
`
To rever the last completed migration for the prod environment, use the following command:
`
$ drift down --env prod
Downgraded: 1664591812475-test.js
Migrations complete!
`
Easily check the status of the migrations for a given environment.
`
Usage: drift status [options]
checks the status of migrations
Options:
-e --env
-h, --help display help for command
`
To check the status of migrations for the dev (default) environment, use the following command:
`bash
$ drift status
Migration Status
Environment: dev
┌─────────────────────────┬──────────┬───────────────────────┐
│ Filename │ Status │ Ran On │
├─────────────────────────┼──────────┼───────────────────────┤
│ 1664591812475-test.js │ migrated │ 9/30/2022, 2:07:06 PM │
└─────────────────────────┴──────────┴───────────────────────┘
``