Blog
Notes from running MongoDB migrations in real projects: rolling back the right thing, keeping two deploys from colliding, running migrations in CI and on app start, and the habits I picked up the hard way. There's also a series on several repos sharing one database, and posts on specific setups: Kubernetes, a database per tenant, TypeScript, Mongoose, secret managers, big backfills and testing. New here? The guide is the better place to start.
- Many repos, one MongoDB database: migrations that don't step on each other
October 16, 2026 · 5 min read
When several repos run migrations against one MongoDB database, they share one history and start stepping on each other. What breaks, how other tools handle it, and the one setting that fixes it in mongo-migrate-kit.
- One repo, one database? You can ignore namespaces
October 16, 2026 · 3 min read
mongo-migrate-kit 1.5 adds namespaces for repos that share a MongoDB database. If your repo has its database to itself, here's exactly what changes for you: nothing.
- Several repos, one MongoDB database, one team
October 16, 2026 · 5 min read
Three repos, one MongoDB database, and a migration history that stays separate per repo. A walkthrough of mongo-migrate-kit namespaces: configs, records, batches, status and locking.
- Several products in one MongoDB database
October 16, 2026 · 4 min read
When several products or teams share one MongoDB database, give each product its own history collection and each repo its own namespace. The rule of thumb, the setup, and how to lock down permissions.
- Rolling out mongo-migrate-kit to 50 repos
October 16, 2026 · 4 min read
A practical plan for rolling out one MongoDB migration tool across fifty repos and three shared databases: the inventory, naming rules, configs, CI, and the order that saves you cleanup work.
- Adding a namespace to a repo that already ran migrations
October 16, 2026 · 5 min read
Your repo ran migrations before it had a namespace, and now its database is shared. Here's how mongo-migrate-kit protects you from re-running them, and how to move the old records over with one command.
- How locking works when 20 repos share one database
October 16, 2026 · 5 min read
When twenty repos share one MongoDB database, whose migration runs first? How mongo-migrate-kit's single database-wide lock works: busy messages, long migrations, crashed holders, and why finer-grained locks were left out.
- The namespace mistakes mongo-migrate-kit catches for you
October 16, 2026 · 5 min read
A changed namespace, a filename two repos both used, records nobody moved, a copied config, an older tool against newer data. Five mistakes that would silently re-run or skip migrations, and the exact messages mongo-migrate-kit stops you with instead.
- MongoDB migrations in a monorepo: one namespace per service
October 16, 2026 · 4 min read
Running MongoDB migrations in a monorepo where several services each have their own migrations folder: one config and one namespace per service, where to run mmk from, and the path mistake that makes it quietly find nothing.
- Leaving migrate-mongo when several repos shared its changelog
October 16, 2026 · 4 min read
Several repos shared one migrate-mongo changelog collection. Here's how to move each of them to mongo-migrate-kit with its own namespace: only its own history, no mix-ups between repos, and nothing in the old changelog touched.
- service is deprecated, use namespace (they're not the same)
October 16, 2026 · 4 min read
mongo-migrate-kit 1.5 deprecates the service setting in favour of namespace. They sound alike but do different things. Here's the difference, why service couldn't be fixed, and how to switch safely.
- MongoDB migrations with a database per tenant
October 16, 2026 · 4 min read
Running the same MongoDB migrations across hundreds of tenant databases: a loop with runMigrations(), limited parallelism, readable logs, one tenant's failure not blocking the rest, and new tenants migrated on creation.
- MongoDB migrations on Kubernetes: Job, Helm hook or init container?
October 16, 2026 · 5 min read
Where should MongoDB migrations run on Kubernetes: a Job, a Helm hook, an init container, or the app itself? The trade-offs, working manifests, and the production-image problem that breaks most first attempts.
- JS, TS, ESM or CommonJS: MongoDB migrations that actually run in production
October 16, 2026 · 6 min read
JavaScript or TypeScript, ES modules or CommonJS: which migration files actually run in production, on which Node versions, and the errors you'll see when the combination is wrong.
- Using Mongoose in migrations (and why you mostly shouldn't)
October 16, 2026 · 4 min read
Your app uses Mongoose. Should your migrations? Why importing app models into migrations goes wrong, what to use instead, and how to pass Mongoose in safely when you really need it.
- Loading your migration connection string from a secret manager
October 16, 2026 · 4 min read
Keep the MongoDB connection string for your migrations in AWS Secrets Manager, GCP Secret Manager, Vault or Azure Key Vault, fetched at runtime by the config file and never written to disk or CI variables.
- Backfilling millions of documents in a MongoDB migration
October 16, 2026 · 5 min read
How to write a MongoDB migration that backfills millions of documents without timing out, locking up production or leaving a mess when it crashes halfway: batches, bulkWrite, filters that let it resume, no transactions, and a lock that renews itself.
- Testing MongoDB migrations with Vitest and mongodb-memory-server
October 16, 2026 · 4 min read
Most teams never test their MongoDB migrations, until a down() that never worked is needed in production. A tiny round-trip test with Vitest (or Jest) and mongodb-memory-server that catches it in CI.
- Zero-downtime MongoDB schema changes: expand, migrate, contract
October 16, 2026 · 5 min read
Migrations run before the new code is live, so for a few minutes old code runs against the new data. The expand-and-contract pattern for MongoDB (renaming a field, adding a required field, adding a unique index) without downtime or broken rollbacks.
- Habits that make MongoDB migrations safe
July 29, 2026 · 6 min read
MongoDB migration best practices learned the hard way: reversible migrations, rolling back one file, dry runs, locking, checksums, transactions, batches, expand and contract, and keeping history.
- MongoDB migrations in GitHub Actions
July 22, 2026 · 4 min read
A practical GitHub Actions setup for MongoDB migrations: test every migration on pull requests, block deploys while migrations are pending, log the plan, and stay safe when two jobs overlap.
- Running MongoDB migrations on app start and in serverless
July 15, 2026 · 4 min read
How to run MongoDB migrations from your Node.js app's start-up code or a serverless function without leaking connections, racing other instances, or serving traffic too early.
- Locking MongoDB migrations so two deploys can't collide
July 8, 2026 · 5 min read
Two deploys running migrations at once can leave MongoDB in a mess. How a lock stored in MongoDB prevents it, and the three cases a simple lock gets wrong: crashes, races and long migrations.
- How to roll back a single MongoDB migration
July 1, 2026 · 4 min read
Most MongoDB migration tools only undo the last migration. Here's how to roll back one specific migration, one old batch, or the last few, and how to preview it first.
- 7 things I kept missing in migrate-mongo
June 24, 2026 · 4 min read
Seven gaps in migrate-mongo that cost me time in production: single-file rollback, dry runs, locking that's off by default, edited files, redo, lost history and older batches.
- Switching from migrate-mongo to mongo-migrate-kit, step by step
June 17, 2026 · 4 min read
Move an existing project from migrate-mongo to mongo-migrate-kit without re-running old migrations, losing history, or touching your old changelog.
- Why I built a new MongoDB migration tool
June 10, 2026 · 4 min read
The story behind mongo-migrate-kit: one bad migration on a Friday, a tool that could only undo the last one, and how I switched an existing project over in one command.