Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import migrateMongo from 'migrate-mongo'
✗ import { migrateMongo } from 'migrate-mongo'
Default export; named exports also available for individual functions.
up
✓ import { up } from 'migrate-mongo'
✗ import up from 'migrate-mongo'
Named export for programmatic use, not default.
down
✓ import { down } from 'migrate-mongo'
✗ import down from 'migrate-mongo'
Named export for programmatic use, not default.
config
✓ import { config } from 'migrate-mongo'
✗ const config = require('migrate-mongo').config
Both CJS and ESM supported; ESM recommended for modern projects.
Shows full workflow: install, init, create migration file with up/down functions, run via CLI or programmatic API.
// 1. Install: npm install migrate-mongo mongodb
// 2. Initialize project: npx migrate-mongo init
// 3. Configure 'migrate-mongo-config.js' with your MongoDB URL and database name.
// 4. Create a migration: npx migrate-mongo create add-users
// 5. Edit the generated file in migrations/:
export async function up(db, client) {
await db.collection('users').insertOne({ name: 'John', email: 'john@example.com' });
}
export async function down(db, client) {
await db.collection('users').deleteOne({ name: 'John' });
}
// 6. Run migrations: npx migrate-mongo up
// Programmatic usage:
import { up, down, config } from 'migrate-mongo';
const migrationConfig = await config.read();
await up(migrationConfig);
// or await down(migrationConfig);
migrate-mongo --version
Errors
Common errors & fixes
Error: Cannot find module 'migrate-mongo'
migrate-mongo not installed or not in PATH (global install missing).
fixInstall locally with 'npm install migrate-mongo --save-dev' or globally with 'npm install -g migrate-mongo'.
Error: Collection not found: changelog
Migration database not initialized; need to run 'migrate-mongo up' first.
fixRun 'migrate-mongo up' to apply pending migrations and create changelog collection.
MongoParseError: options usecreateindex, usefindandmodify are not supported
Deprecated options passed to MongoDB driver.
fixRemove 'useCreateIndex' and 'useFindAndModify' from config; they are no longer needed.
Audit
Dependencies
mongodbrequiredPeer dependency for database connection. Must be installed separately.