{"id":48761,"library":"node-mongodb-migrations","title":"node-mongodb-migrations","description":"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.","status":"maintenance","version":"0.8.2","language":"javascript","source_language":"en","source_url":"git://github.com/neverbot/node-mongodb-migrations","tags":["javascript","migrate","migrations"],"install":[{"cmd":"npm install node-mongodb-migrations","lang":"bash","label":"npm"},{"cmd":"yarn add node-mongodb-migrations","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-mongodb-migrations","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MongoDB state storage and database migrations","package":"mongodb","optional":false}],"imports":[{"note":"This package does not support ESM; only CommonJS require is supported.","wrong":"import migrate from 'node-mongodb-migrations';","symbol":"default","correct":"const migrate = require('node-mongodb-migrations');"}],"quickstart":{"code":"// First, install the package: npm install node-mongodb-migrations\n\n// Create a migration file: ./migrations/1614556800000-my-migration.js\nexports.up = function(next) {\n  console.log('Migration up');\n  next();\n};\nexports.down = function(next) {\n  console.log('Migration down');\n  next();\n};\n\n// Programmatically run migrations:\nconst migrate = require('node-mongodb-migrations');\nconst set = migrate.load('migrations/.migrate', './migrations');\nset.up(function(err) {\n  if (err) throw err;\n  console.log('Migration completed');\n});\n\n// Or via CLI:\n// migrate --state-mongo MONGODB_URI up","lang":"javascript","description":"Shows installation, creating a simple migration file, and programmatic usage with require() and migrate.load()."},"warnings":[{"fix":"Use callbacks or wrap in a Promise manually. For example: const up = () => new Promise((resolve, reject) => { exports.up = function(next) { resolve(next()); }; });","message":"The package uses callback-based API (next function). Promises and async/await are not supported.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Consider migrating to actively maintained alternatives like migrate-mongo or db-migrate.","message":"The package has not been updated since 2018. It may have unpatched vulnerabilities and does not support modern MongoDB driver versions.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Ensure either state file or MongoDB is used exclusively, or verify the migration state manually.","message":"When 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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Update code to use native MongoDB driver API if you were using then-mongo features.","message":"Version 0.8.0 switched from then-mongo to native mongodb promises, which may break custom code that depended on the then-mongo API.","severity":"breaking","affected_versions":">=0.8.0 <0.9.0"}],"env_vars":null,"search_vec":"'0.8.2':32 'abstract':6 'altern':88 'base':70 'cli':77 'collect':24 'command':78 'compar':86 'creat':84 'db':95 'db-migrat':94 'differenti':57 'e.g':72 'either':15 'environ':30 'file':19,69 'file-bas':68 'focus':102 'fork':42,48 'framework':8 'ikatun/node-migrate':44 'includ':58 'instanc':29 'javascript':108 'key':56 'latest':35 'lightweight':100 'like':89 'local':18 'migrat':4,7,13,85,91,96,109,110 'migrate-mongo':90 'mongo':92 'mongodb':3,23,54,64,75,105 'multi':28 'multi-inst':27 'nativ':53 'node':2 'node-mongodb-migr':1 'node.js':10 'packag':39,98 'persist':62 'promis':55 'releas':37 'rollback':82 'seamless':65 'sole':103 'stabl':36 'state':14,61,71,106 'storag':107 'store':12 'support':59 'switch':66 'tj/node-migrate':50,73 'use':25,52 'version':31","created_at":"2026-06-07T16:58:19.752232+00:00","updated_at":"2026-06-07T16:58:19.752232+00:00","problems":[{"fix":"Run `npm install node-mongodb-migrations` in your project directory.","cause":"Package not installed or not in node_modules","error":"Error: Cannot find module 'node-mongodb-migrations'"},{"fix":"Use `const migrate = require('node-mongodb-migrations');` instead of `import migrate from ...`","cause":"Incorrect import: using ESM import instead of CommonJS require","error":"TypeError: migrate.load is not a function"},{"fix":"Set the environment variable to a valid MongoDB URI with proper authentication, e.g., mongodb://user:pass@host:port/db","cause":"MongoDB connection string in --state-mongo env variable is incorrect or lacks credentials","error":"MongoError: auth fails"},{"fix":"Ensure exports.up and exports.down have a `next` parameter and call it when done: exports.up = function(next) { ... next(); }","cause":"In migration file, next is not passed as a parameter or is undefined","error":"Migration failed: next is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/neverbot/node-mongodb-migrations#readme","github":"git://github.com/neverbot/node-mongodb-migrations","docs":null,"changelog":null,"pypi":null,"npm":"node-mongodb-migrations","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}