DEV Community: Santosh Gupta

How to Roll Back a Single MongoDB Migration (Without Nuking the Rest)

Santosh Gupta — Fri, 11 Sep 2026 13:25:20 +0000

If you've ever searched Google for something like:

"How do I roll back one specific MongoDB migration?"

…there's a good chance something already went wrong.

You ran a few migrations. One of them had a bug. And now you don't want to undo everything.

You just want to undo that one migration.

That sounds simple, but if you're using tools like migrate-mongo, you'll quickly discover that rollback doesn't always work the way you'd expect.

I've run into this problem myself, and it's one of the reasons I started using mongo-migrate-kit.

The problem with traditional migration rollbacks

Most MongoDB migration tools treat migrations like a stack.

The basic idea is simple:

Run a migration → push it onto the stack
Run down → remove the most recently applied migration
Run down again → remove the one before that

For a simple project, that's perfectly fine.

But real projects rarely stay simple.

Imagine you deployed three migrations:

Migration A
Migration B
Migration C

Then you discover that Migration B has a problem.

With a stack-based rollback system, you can't simply say:

Undo Migration B.

You first have to roll back Migration C, then Migration B.

Now you've rolled back something that wasn't even broken.

The situation gets even more confusing when you have multiple environments and developers. The "last migration" in your local environment might not be the same as the last migration in staging or production.

And if the migration you want to undo isn't the most recent one at all, you're usually left with two options:

Roll back several migrations until you reach it.
Fix the database manually.

I've done the second option before.

I don't recommend it.

What I actually wanted was rollback by migration name

The feature I wanted was very simple:

Roll back this specific migration file.

That's exactly how mongo-migrate-kit works.

The CLI is mmk, and you can roll back a migration directly by its filename:

npx mmk down 20260101120000-the-broken-one.js

That runs the down() function for that migration only.

The other migrations stay exactly where they are.

No rolling back good migrations.

No manually modifying the database.

No trying to remember which migrations need to be reapplied afterward.

Just undo the one you actually meant to undo.

Rolling back an entire release

Sometimes, though, the problem isn't one migration.

Maybe the entire deployment was bad.

For that situation, you can roll back by batch:

npx mmk down --batch 3

A batch represents the migrations that were applied together during one mmk up operation.

So if Batch 3 contained five migrations, this command rolls back that batch as a unit.

This is useful when the problem is the deployment itself rather than one specific migration.

What if I just want to undo the last few migrations?

There's another situation that comes up quite often.

You don't care about a specific batch, and you don't want to specify filenames.

You simply want to undo the last few migrations.

For example:

npx mmk down --steps 2

This rolls back the last two applied migrations, starting with the newest one.

So now there are three different ways to think about rollback:

npx mmk down <file>       # Undo one specific migration

npx mmk down --batch <n>  # Undo an entire deployment batch

npx mmk down --steps <n>  # Undo the last N migrations

They're three different problems, so they should have three different solutions.

Always preview before rolling anything back

Personally, the part I dislike most about production rollbacks is uncertainty.

You don't want to run a command and then discover what it was going to do.

So before rolling back anything important, I preview it first:

npx mmk dry-run down 20260101120000-the-broken-one.js

This doesn't modify the database.

It simply tells you which migrations would be rolled back and in what order.

For production databases, this is something I strongly recommend doing first.

It takes a couple of seconds and can save you from making a much bigger mistake.

What happens if someone edits a migration after it has already run?

This is another problem that's surprisingly easy to create.

Let's say a migration was applied successfully:

20260101120000-add-users-index.js

A few weeks later, someone edits that migration file.

Then someone tries to roll it back.

The problem is that the current down() function might not belong to the same migration code that originally ran against the database.

You're essentially trying to undo something using code that may have changed after the fact.

That can get dangerous very quickly.

mongo-migrate-kit checks for this using SHA-256 checksums.

When a migration is applied, its checksum is recorded.

Before rolling it back, mmk compares the current file with the version that was originally applied.

If they don't match, the rollback stops:

✖ Checksum mismatch: 20260101120000-the-broken-one.js was edited after it was applied

This is intentional.

Rolling back edited migration code can be riskier than applying it.

If you genuinely know what you're doing, you can override the check using --force.

But the important thing is that you have to explicitly choose to do that.

The tool won't silently run potentially different rollback code against your database.

Your migration history also stays intact

Another thing I didn't like about some migration approaches was losing history.

When a migration is rolled back with mongo-migrate-kit, the migration record isn't simply deleted.

Instead, it's marked as reverted and gets a revertedAt timestamp.

That means you can still answer questions like:

What migrations ran on this database?
When were they applied?
Who ran them?
How long did they take?
Which migrations were later reverted?

When something breaks in production, having that history available is extremely useful.

Especially at 2 AM.

The short version

If you just want the commands:

npx mmk down <file>
# Roll back exactly one migration

npx mmk down --batch <n>
# Roll back an entire batch

npx mmk down --steps <n>
# Roll back the last N migrations

npx mmk dry-run down <file>
# Preview what will happen without changing anything

That's really the main idea behind the rollback system.

You should be able to choose what you want to undo.

Not be forced to undo everything that happened after it.

Try it

Install the package:

npm install mongo-migrate-kit mongodb

Then, before doing anything risky, preview the rollback:

npx mmk dry-run down <file>

And when you're ready:

npx mmk down <file>

That's it.

If you've ever had to manually fix a MongoDB database because your migration tool couldn't undo one specific migration, you'll probably understand why I built this feature.

You can find the documentation and examples at:

https://mongo-migrate-kit.vercel.app

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