Start here

mongo-migrate-kit (the command is mmk) runs database migrations for MongoDB from Node.js. A migration is a small file with two functions: up makes a change, and down undoes it. You keep these files in your repo next to your code. mmk remembers which ones have run on each database, so every environment ends up with the same changes in the same order.

If you have used Rails, Laravel or Knex migrations, this will feel familiar. If you haven't, that's fine too. The pages below are written so you can read them in order.

What you need

• Node.js 18 or newer
• A MongoDB server, version 4.2 or newer. A local one is fine. If you don't have one, docker run -d -p 27017:27017 mongo starts one.
• About ten minutes for the first step

The path

1. Get it runningabout 10 minutes

   Install the package, create a migration, run it, look at the status, and roll it back. The tutorial does the same thing more slowly and explains each step.

   Quick start →
   Tutorial →
2. Understand itabout 15 minutes

   Where mmk keeps its history, what a batch is, how the lock and checksums work, and what a good migration file looks like.

   How it works →
   Writing migrations →
   TypeScript →
   A normal day with mmk →
   In VS Code →
3. Use it in productionabout 30 minutes

   Configuration, running migrations in CI or on app start, transactions, hooks, and reading the errors when something fails.

   Configuration →
   Deploying and CI →
   Running from your code →
   When something goes wrong →
4. Bigger setupsread when you need it

   Several repos writing to one database, moving an existing project off migrate-mongo, and longer reads on the blog.

   Sharing a database →
   Moving from migrate-mongo →
   Blog →

Looking something up?

You don't have to follow the path. If you already know what you need:

• CLI cheatsheet has every command and flag on one page.
• Commands explains each command in detail, with real output.
• Error codes lists every error mmk can show and what to do about it.
• FAQ answers the questions people ask most.

Something unclear?

If a page here confused you, that's a bug in the docs. Please open an issue or use the "Edit this page" link at the bottom of any page.