Quick start

Step 1 of the learning path · about 5 minutes

This page gets you from nothing to a migration you have run and rolled back. If you'd like each step explained as you go, the tutorial covers the same ground more slowly.

Here's the whole thing in one recording. The steps below match it.

1. Install

You need the package and the official MongoDB driver:

npm

npm install mongo-migrate-kit mongodb

pnpm

pnpm add mongo-migrate-kit mongodb

yarn

yarn add mongo-migrate-kit mongodb

This gives you the mmk command. Run it with npx mmk, or add scripts to package.json (see the end of this page).

You need Node.js 18 or newer and a MongoDB server, version 4.2 or newer. If you don't have one running, Docker is the quickest way: docker run -d -p 27017:27017 mongo.

ES modules or CommonJS?

Either works, with nothing to set up. mmk init and mmk create read your package.json and write export for "type": "module" projects and module.exports for everything else. See ES modules or CommonJS.

2. Create a config file

npx mmk init

This writes mmk.config.js in the current folder. Every option is in there with a comment. For now, only two lines matter:

// mmk.config.js (trimmed)
const config = {
  uri: 'mongodb://localhost:27017',
  dbName: 'myapp',
  // ...everything else has a sensible default
};

Change dbName to your database. Want TypeScript or JSON instead? Use npx mmk init --ts or npx mmk init --json. (TypeScript needs Node 22.18 or newer, or tsx. See TypeScript.)

You can skip the file

The config file is optional. Setting MMK_URI and MMK_DB in your environment (or a .env file) works just as well.

3. Create a migration

npx mmk create add-users-email-index

Loaded config from mmk.config.js
✔ Created  20261015223650-add-users-email-index.js

The file lands in migrations/ with a timestamp at the front, so files always sort in the order you made them. Open it and fill in both functions. It uses export if your package.json has "type": "module", and module.exports otherwise:

ES module

// migrations/20261015223650-add-users-email-index.js
export const description = 'Unique index on users.email';
export const author = 'Asha Rao';

export async function up({ db }) {
  await db.collection('users').createIndex({ email: 1 }, { unique: true });
}

export async function down({ db }) {
  await db.collection('users').dropIndex('email_1');
}

CommonJS

// migrations/20261015223650-add-users-email-index.js
module.exports = {
  description: 'Unique index on users.email',
  author: 'Asha Rao',

  async up({ db }) {
    await db.collection('users').createIndex({ email: 1 }, { unique: true });
  },

  async down({ db }) {
    await db.collection('users').dropIndex('email_1');
  },
};

up makes the change. down undoes it. The author line is filled in for you from your git name.

4. Run it

npx mmk up

Loaded config from mmk.config.js
✔ Applied  20261015223650-add-users-email-index.js   [117ms]

5. Check where you are

npx mmk status

Loaded config from mmk.config.js
┌─────────────────────────────────────────┬─────────┬───────┬─────────────────────┬──────────┬──────────┐
│ Migration                               │ Status  │ Batch │ Applied At          │ Checksum │ Author   │
├─────────────────────────────────────────┼─────────┼───────┼─────────────────────┼──────────┼──────────┤
│ 20261015223650-add-users-email-index.js │ applied │ 1     │ 2026-10-15 22:36:51 │ ok       │ Asha Rao │
└─────────────────────────────────────────┴─────────┴───────┴─────────────────────┴──────────┴──────────┘

6. Roll it back

npx mmk down

Loaded config from mmk.config.js
↩ Reverted 20261015223650-add-users-email-index.js   [5ms]

The index is gone, and the migration shows as pending again. The record of it running is still in the database, marked reverted. mmk never deletes history.

Add some npm scripts

Typing npx mmk gets old. Most projects add something like this:

{
  "scripts": {
    "migrate": "mmk up",
    "migrate:down": "mmk down",
    "migrate:status": "mmk status",
    "migrate:new": "mmk create"
  }
}

Then npm run migrate:new -- add-orders-index creates a file and npm run migrate runs it.

Where to go next

• Tutorial if you want the same steps with more explanation.
• How it works to understand batches, the history collection and the lock.
• Writing migrations for TypeScript, CommonJS and good habits.