{"id":47279,"library":"codemao-migrate-mongo","title":"migrate-mongo","description":"A database migration tool for MongoDB in Node.js. Current stable version is 2.2.7. It provides a simple CLI to initialize, create, run up/down migrations, and check status. Key differentiators: lightweight, uses the official MongoDB Node.js driver, supports both callback and Promise API, and stores changelog in a MongoDB collection. Releases are infrequent but stable. Ideal for projects needing a straightforward migration solution without complex setup.","status":"active","version":"2.2.7","language":"javascript","source_language":"en","source_url":"https://github.com/seppevs/migrate-mongo","tags":["javascript","migrate mongo mongodb migrations database"],"install":[{"cmd":"npm install codemao-migrate-mongo","lang":"bash","label":"npm"},{"cmd":"yarn add codemao-migrate-mongo","lang":"bash","label":"yarn"},{"cmd":"pnpm add codemao-migrate-mongo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for connecting to MongoDB and performing database operations within migrations.","package":"mongodb","optional":false}],"imports":[{"note":"Migrations can use async/await or return a Promise. Callback-style (next) still works but is legacy.","wrong":"module.exports.up = (db, next) => { next(); } (callback-style deprecated in newer versions)","symbol":"up","correct":"module.exports.up = async (db) => { /* migration */ }"},{"note":"Use async functions to avoid callback nesting. Both 'up' and 'down' are required exports.","wrong":"module.exports.down = (db, next) => { next(); } (same as up)","symbol":"down","correct":"module.exports.down = async (db) => { /* rollback */ }"},{"note":"The config file is a CommonJS module exporting an object. It is read automatically by the CLI.","wrong":"Using require() to load config (it's a CommonJS module, but must export the object directly)","symbol":"config","correct":"module.exports = { mongodb: { url: '...', options: {} }, migrationsDir: 'migrations', changelogCollectionName: 'changelog' }"}],"quickstart":{"code":"// Initialize project\nconst { execSync } = require('child_process');\nexecSync('mkdir albums-migrations && cd albums-migrations && migrate-mongo init', { stdio: 'inherit' });\n// Edit config.js manually (mongodb.url)\n// Create migration\nexecSync('migrate-mongo create add_albums', { stdio: 'inherit' });\n// Then write migration file content:\nmodule.exports = {\n  up: async (db) => {\n    await db.collection('albums').insertMany([{ artist: 'Beatles', blacklisted: true }]);\n  },\n  down: async (db) => {\n    await db.collection('albums').deleteMany({ artist: 'Beatles' });\n  }\n};\n// Run migrations\nexecSync('migrate-mongo up', { stdio: 'inherit' });","lang":"javascript","description":"Shows how to initialize a project, create a migration file, write up/down functions, and run migrations using async/await."},"warnings":[{"fix":"Ensure each migration module exports both up and down functions, even if down is a no-op.","message":"The migration file must export both 'up' and 'down' functions. If 'down' is missing, migration down command will not work.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use db.collection() directly. Do not call db.close() or use MongoClient inside migrations.","message":"The 'db' object provided in migrations is the native MongoDB Db object, not a session or transaction context. Do not close the connection.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use async functions: module.exports.up = async (db) => { ... }","message":"Callback-style (db, next) is deprecated in favor of async/await or Promise-returning functions.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Keep the changelogCollectionName consistent across all environments.","message":"The changelog collection name is case-sensitive and defaults to 'changelog'. If you change it, migrations will not see previously applied ones.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.2.7':16 'api':45 'callback':42 'changelog':48 'check':29 'cli':21 'collect':52 'complex':67 'creat':24 'current':12 'databas':5,74 'differenti':32 'driver':39 'ideal':58 'infrequ':55 'initi':23 'javascript':69 'key':31 'lightweight':33 'migrat':2,6,27,64,70,73 'migrate-mongo':1 'mongo':3,71 'mongodb':9,37,51,72 'need':61 'node.js':11,38 'offici':36 'project':60 'promis':44 'provid':18 'releas':53 'run':25 'setup':68 'simpl':20 'solut':65 'stabl':13,57 'status':30 'store':47 'straightforward':63 'support':40 'tool':7 'up/down':26 'use':34 'version':14 'without':66","created_at":"2026-06-07T16:50:42.596410+00:00","updated_at":"2026-06-07T16:50:42.596410+00:00","problems":[{"fix":"Run 'npm install -g migrate-mongo' or 'npm install --save-dev migrate-mongo' and use npx.","cause":"The package is not installed globally or locally.","error":"Error: Cannot find module 'migrate-mongo'"},{"fix":"Start MongoDB service or update config.js with correct connection URL.","cause":"MongoDB is not running on the default port.","error":"Error: connect ECONNREFUSED 127.0.0.1:27017"},{"fix":"Either use CommonJS (module.exports) or set 'type':'module' in package.json and use import/export syntax accordingly.","cause":"Using ES modules (import/export) instead of CommonJS.","error":"ReferenceError: module is not defined"},{"fix":"Ensure migration function accepts exactly one argument (db) for async style or two (db, next) for callback style.","cause":"The db argument is not passed correctly or migration function signature is wrong.","error":"Cannot read property 'collection' of undefined"}],"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/seppevs/migrate-mongo#readme","github":"https://github.com/seppevs/migrate-mongo","docs":null,"changelog":null,"pypi":null,"npm":"codemao-migrate-mongo","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}}