DEV Community: Santosh Gupta

7 Things I Wish migrate-mongo Had After a Few Production Incidents

Santosh Gupta — Mon, 10 Aug 2026 06:11:28 +0000

I've used migrate-mongo for years.

It's simple, reliable, and honestly a good choice for many projects.

But as our application grew, I started running into the same problems repeatedly: rollbacks, concurrent deployments, migration drift, and debugging what actually happened months ago.

Eventually, I stopped working around those problems and built mongo-migrate-kit.

Here are the seven things I wanted.

1. Roll back a specific migration

This was the one that frustrated me the most.

Imagine three migrations went out:

migration A  ✓
migration B  ✗
migration C  ✓

I only want to undo B.

With migrate-mongo, rollback is based on the latest migration. There's no simple way to say "undo this particular migration."

So you either roll back more than you want or start doing things manually.

I've done the latter in production. Not fun.

With mongo-migrate-kit:

mmk down 20260101-the-broken-one.js

Or if you actually want to roll back a batch:

mmk down --batch 3

2. Dry run before touching production

Before running migrations in production, I want to know:

Which migrations are pending?
What order will they run in?
What is about to happen?

That's why mmk has dry-run support:

mmk dry-run up
mmk dry-run down

It shows the plan without changing the database.

I run this before production migrations now. It's a small thing, but it removes a lot of uncertainty.

3. Two deployments shouldn't run migrations simultaneously

We once had two deployments trigger migrations almost at the same time.

Both processes thought they were in charge.

That's not a situation you want with database migrations.

mongo-migrate-kit uses a database-backed atomic lock:

Deploy A → acquire lock → run migrations → release

Deploy B → lock exists → stop

The lock has a TTL, so a crashed process doesn't leave the database permanently locked.

And if you don't need locking locally:

mmk up --no-lock

4. Know when an old migration was modified

This one is easy to overlook.

A migration runs in production.

Someone later edits the file.

The filename is still the same, so the migration history says everything is fine.

But the code that exists in Git is no longer the code that ran in production.

mongo-migrate-kit stores a SHA-256 checksum for every migration.

If the file changes, you can see the drift.

And with:

mmk up --strict

the migration can fail instead of silently continuing.

If the change was intentional:

mmk up 20260101-add-index.js --force

Migration files are history. I think they should be treated that way.

5. Redo shouldn't require two commands

During development, my migration loop was basically:

migrate down
migrate up

Over and over.

So I added:

mmk redo

Or:

mmk redo 20260101-add-index.js

Small feature.

Probably the command I use most while writing migrations.

6. Rollbacks shouldn't erase history

A rollback is still an event.

If a migration ran on Monday and was reverted on Tuesday, I want that information to remain in the database.

Instead of deleting the migration record, mmk marks it as:

applied → reverted

The history keeps information such as:

batch
status
appliedAt
revertedAt
duration
checksum
environment
executedBy

Months later, you can still answer:

"Did this migration actually run in production?"

That's important when debugging old incidents.

7. TypeScript shouldn't need a separate setup

If your application is TypeScript, migration files should be TypeScript too.

With mongo-migrate-kit:

import type { MigrationContext } from 'mongo-migrate-kit';

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

export async function down({ db }: MigrationContext): Promise<void> {
  await db.collection('users').dropIndex('email_1');
}

No extra ts-node setup or build step.

JavaScript works too, including ESM and CommonJS.

Should you switch from `migrate-mongo`?

Maybe not.

If you have a small project and a handful of migrations, migrate-mongo is probably perfectly fine.

I used it for years.

These problems only started becoming painful when we had more migrations, more developers, more environments, and CI/CD deployments running against production.

That's when migration tooling stops being just:

"Run these files in order."

It becomes infrastructure.

And infrastructure needs things like locking, audit history, drift detection, and safe rollbacks.

Already using `migrate-mongo`?

You don't need to rewrite your existing migrations.

mongo-migrate-kit can import your existing history:

npm install mongo-migrate-kit mongodb

mmk import --dry-run
mmk import
mmk up

The old changelog isn't modified.

That's the reason I built this tool.

Not because migrate-mongo is bad.

Because after enough production incidents, I knew exactly which features I wanted in my migration workflow.

mongo-migrate-kit is open source.

If you've had a migration go wrong in production, I'd genuinely like to hear what happened. Those stories are usually where the best tooling ideas come from.

Moving from Migrate Mongo to Mongo Migrate Kit (mmk) Without Re Running Old Migrations

Santosh Gupta — Thu, 25 Jun 2026 11:34:10 +0000

If you're using migrate-mongo and considering a switch, the biggest concern usually isn't features.

It's this:

"Will I have to re-run old migrations or risk production data?"

The short answer is no.

I built mongo-migrate-kit with migration adoption as a first class feature because switching migration tools shouldn't feel risky.

The Problem

Most teams already have months or years of migration history.

Re-running old migrations is dangerous.

Editing migration records manually is even worse.

What you really want is a way to tell the new tool:

"These migrations already ran. Start tracking them and leave everything else alone."

That's exactly what mongo-migrate-kit does.

Import Existing migrate-mongo History

First, install the package:

npm install mongo-migrate-kit mongodb

Preview the import:

npx mmk import --dry-run

This reads your existing migrate-mongo changelog and shows what will be imported.

Nothing is written to the database.

Once you're happy with the output:

npx mmk import

The migration history is copied into mongo-migrate-kit's tracking collection.

Your original migrate-mongo changelog remains untouched.

What Happens Next?

After importing:

npx mmk status

Previously applied migrations appear as applied.

Any migration files that haven't run yet remain pending.

When you run:

npx mmk up

Only pending migrations execute.

Old migrations are never re-run.

Why I Built This

I originally created mongo-migrate-kit after running into rollback issues during a deployment.

While using migrate-mongo, I found myself wanting more control over migration safety and deployment workflows.

That led to features such as:

Rollback specific migrations or batches
Dry-run support
SHA-256 checksum validation
Distributed migration locking
Redo support
TypeScript support
Safe migration adoption from migrate-mongo

Documentation

Getting started takes only a few minutes:

Deep dive on migration guide from migrate mongo:
https://mongo-migrate-kit.vercel.app/guide/migrate-mongo

npm:
https://www.npmjs.com/package/mongo-migrate-kit

GitHub:
https://github.com/guptasantosh327/mongo-migrate-kit

Final Thoughts

Migration tools should make deployments safer, not add anxiety.

If you're looking for a migrate-mongo alternative or need a MongoDB migration tool for Node.js that can adopt existing migration history safely, give mongo-migrate-kit a try.

I Built a MongoDB Migration Tool After One Bad Deploy

Santosh Gupta — Sat, 06 Jun 2026 07:15:09 +0000

A few months ago I shipped a bad MongoDB migration.

Classic mistake.

I had run 3 migrations.

The third one had a bug.

I only wanted to rollback that migration.

Turns out with migrate-mongo, rollback is mostly:

undo the last applied migration

Which sounds fine until you have:

multiple deployments
multiple environments
teammates deploying too

“Last applied” stops feeling obvious.

I ended up manually undoing DB changes and fixing migration history myself.

Not fun.

That was the moment I realized our migration setup had started breaking down as the project grew.

The stuff I kept wishing existed

After that incident I wrote down all the things I wanted from a migration tool:

run one migration file
rollback a specific migration
preview migrations before running (dry-run)
avoid concurrent deploys stepping on each other (locking)
detect edited migrations (checksums)
a redo command for local development
TypeScript support without setup pain
migration history that doesn’t disappear after rollback

None of these felt unusual.

They felt like things you eventually want once your project stops being small.

So I ended up building one.

Meet `mongo-migrate-kit`

CLI name: mmk

A few examples:

Run pending migrations:

mmk up

Rollback a specific migration:

mmk down migration-name

Preview before touching production:

mmk up --dry-run

Redo during development:

mmk redo

The hard problem: switching tools safely

This was the part I cared about most.

Migration tools are easy to adopt on day 1.

They’re painful to switch after 50+ migrations already exist.

I didn’t want people to:

rerun old migrations
recreate indexes
duplicate seed data
accidentally touch production data

So I added:

mmk import

It reads your existing migrate-mongo changelog and adopts the migration history.

Then:

mmk up

only runs new migrations.

No replaying old history.

No scary production moments.

One thing I intentionally don't support

Imported migrate-mongo migrations are forward-only.

You can’t rollback imported migrations using mmk.

I could have tried to force compatibility, but I didn’t trust it enough to be safe.

Different execution models + database tooling = not something I wanted to gamble with.

So the tool fails loudly instead of pretending everything is reversible.

Curious what other teams are doing

If you're running MongoDB migrations in production:

What’s your current setup?
Have you hit similar pain points?
Are you still happy with migrate-mongo?

Would genuinely love feedback.

Project:

mongo-migrate-kit

Docs/demo:
mongo-migrate-kit.vercel.app

npm:
mongo-migrate-kit