Registry / database / node-mongodb-migrations

node-mongodb-migrations

library0.8.2jsnpmunverified

An abstract migration framework for Node.js that stores migration state either in a local file or in a MongoDB collection (useful for multi-instance environments). Version 0.8.2 is the latest stable release. The package is a fork of ikatun/node-migrate, which itself was forked from tj/node-migrate. It uses native MongoDB promises. Key differentiators include support for state persistence in MongoDB, seamless switching from file-based state (e.g., tj/node-migrate) to MongoDB, and CLI commands for up, down, rollback, and create migrations. Compared to alternatives like `migrate-mongo` or `db-migrate`, this package is lightweight and focused solely on MongoDB state storage.

database

npm install node-mongodb-migrations

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-MONGODB-MIGRA

node-mongodb-migrations

databasejavascriptv0.8.2

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.

default

✓ const migrate = require('node-mongodb-migrations');

✗ import migrate from 'node-mongodb-migrations';

This package does not support ESM; only CommonJS require is supported.

Shows installation, creating a simple migration file, and programmatic usage with require() and migrate.load().

// First, install the package: npm install node-mongodb-migrations // Create a migration file: ./migrations/1614556800000-my-migration.js exports.up = function(next) { console.log('Migration up'); next(); }; exports.down = function(next) { console.log('Migration down'); next(); }; // Programmatically run migrations: const migrate = require('node-mongodb-migrations'); const set = migrate.load('migrations/.migrate', './migrations'); set.up(function(err) { if (err) throw err; console.log('Migration completed'); }); // Or via CLI: // migrate --state-mongo MONGODB_URI up

Debug

Known issues

gotchaThe package uses callback-based API (next function). Promises and async/await are not supported.

fix

Use callbacks or wrap in a Promise manually. For example: const up = () => new Promise((resolve, reject) => { exports.up = function(next) { resolve(next()); }; });

affects: >=0.0.0

deprecatedThe package has not been updated since 2018. It may have unpatched vulnerabilities and does not support modern MongoDB driver versions.

fix

Consider migrating to actively maintained alternatives like migrate-mongo or db-migrate.

affects: >=0.0.0

gotchaWhen using --state-mongo and --state-file simultaneously, if the migrations collection is empty, the state file is migrated to MongoDB. This can cause unexpected behavior if the state file is not up-to-date.

fix

Ensure either state file or MongoDB is used exclusively, or verify the migration state manually.

affects: >=0.0.0

breakingVersion 0.8.0 switched from then-mongo to native mongodb promises, which may break custom code that depended on the then-mongo API.

fix

Update code to use native MongoDB driver API if you were using then-mongo features.

affects: >=0.8.0 <0.9.0

Errors

Common errors & fixes

Error: Cannot find module 'node-mongodb-migrations'

Package not installed or not in node_modules

fix

Run `npm install node-mongodb-migrations` in your project directory.

TypeError: migrate.load is not a function

Incorrect import: using ESM import instead of CommonJS require

fix

Use `const migrate = require('node-mongodb-migrations');` instead of `import migrate from ...`

MongoError: auth fails

MongoDB connection string in --state-mongo env variable is incorrect or lacks credentials

fix

Set the environment variable to a valid MongoDB URI with proper authentication, e.g., mongodb://user:pass@host:port/db

Migration failed: next is not a function

In migration file, next is not passed as a parameter or is undefined

fix

Ensure exports.up and exports.down have a `next` parameter and call it when done: exports.up = function(next) { ... next(); }

Upgrade

Version history

0.8.2latest on npm

Audit

Dependencies

mongodbrequiredRequired for MongoDB state storage and database migrations

Agent activity

10 hits · last 30 days

node

Resources

githubgit://github.com/neverbot/node-mongodb-migrations ↗

packagenode-mongodb-migrations ↗

homepagehttps://github.com/neverbot/node-mongodb-migrations#readme ↗