migrate-mongo-alt

library12.0.3jsnpmunverified

A database migration tool for MongoDB in Node.js (fork of migrate-mongo). Version 12.0.3 supports Node >=18 and MongoDB drivers 4.4.x through 7.x. It provides a CLI for creating, up/down migrations, and status checks. Differentiators include merged PRs from the original project, optional context function per migration, and support for ESM or CJS configs. Release cadence is irregular; actively maintained as of 2025.

database

npm install migrate-mongo-alt

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MIGRATE-MONGO-ALT

migrate-mongo-alt

databasejavascriptv12.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

migrate-mongo-alt (CLI)

✓ npx migrate-mongo up

✗ npm install -g migrate-mongo && migrate-mongo up

Use npx to avoid global install. The CLI is the primary interface; there is no programmatic API.

migrate-mongo-alt (programmatic use)

✓ import { up, down, status } from 'migrate-mongo-alt';

✗ const migrateMongo = require('migrate-mongo-alt');

Supports ESM imports. CommonJS require works but default import may be needed.

config export

✓ module.exports = { mongodb: { url: '...', databaseName: '...' } };

✗ export default { ... };

Config file uses CommonJS by default. An async function returning an object is also supported.

Initialize a migration project, create a migration file, and apply it.

mkdir albums-migrations && cd albums-migrations npx migrate-mongo init # Edit the generated migrate-mongo-config.js with your MongoDB URI and database name # Example config: # module.exports = { # mongodb: { # url: 'mongodb://localhost:27017', # databaseName: 'my_database', # options: { directConnection: true } # }, # migrationsDir: 'migrations', # changelogCollectionName: 'changelog' # }; npx migrate-mongo create add_field # Edit migrations/XXXXXXXXXXXXXX-add_field.js: module.exports = { async up(db, client) { await db.collection('items').updateMany({}, { $set: { newField: '' } }); }, async down(db, client) { await db.collection('items').updateMany({}, { $unset: { newField: '' } }); } }; npx migrate-mongo up

Debug

Known issues

gotchaThe config file must export an object or a promise returning an object. Using ES module syntax (export default) will cause an error.

fix

Use module.exports = { ... } or an async function returning the config.

affects: >=12.0.0

gotchaThe migrations directory is relative to the current working directory, not the config file location.

fix

Use an absolute path in migrationsDir or run the CLI from the correct directory.

affects: >=9.0.0

gotchaConnecting to a replica set without directConnection: true may fail with 'MongoServerError: not master'.

fix

Set directConnection: false and provide a valid replica set URI or seed list.

affects: >=10.0.0

deprecatedThe 'context' function receives an object with 'migrationFile' and 'operation' but the signature changed in v11 (previously was (migrationFile, operation) separately).

fix

Update context to accept a single object parameter: { migrationFile, operation }.

affects: >=11.0.0

breakingIn v12, Node.js 16 is no longer supported. The minimum required Node.js version is 18.

fix

Upgrade Node.js to >=18.

affects: >=12.0.0

breakingThe mongodb driver v3 is no longer supported; only v4.4+ is accepted.

fix

Install mongodb driver version 4.4.1 or later.

affects: >=9.0.0

gotchaThe 'up' and 'down' functions in migration files receive 'db' (Db instance) and 'client' (MongoClient). Using 'client.db()' inside the migration will create a new connection.

fix

Use the provided 'db' parameter. Avoid calling client.db() unless necessary.

affects: >=9.0.0

Errors

Common errors & fixes

Error: migrate-mongo is not recognized as an internal or external command

Attempting to use the CLI without global install or npx.

fix

Run with npx: npx migrate-mongo up

MongoParseError: option directConnection is not permitted without a replica set

Setting directConnection: true when connecting to a replica set.

fix

Set directConnection: false or remove the option.

Error: Cannot find module 'migrate-mongo-alt'

Module not installed in node_modules.

fix

Run npm install migrate-mongo-alt (or add it to package.json).

TypeError: (0 , _migrateMongo.up) is not a function

Improper import/require of the module's programmatic API.

fix

Use correct import: import { up } from 'migrate-mongo-alt';

Upgrade

Version history

12.0.3latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency for MongoDB driver connection and operations.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/theogravity/migrate-mongo-alt ↗

packagemigrate-mongo-alt ↗

homepagehttps://github.com/theogravity/migrate-mongo-alt#readme ↗