{"id":18560,"library":"migrate-mongo","title":"migrate-mongo","description":"A database migration tool for MongoDB in Node.js, currently at version 14.0.7. Supports MongoDB drivers 4.x through 7.x and requires Node.js >=20.0.0. It provides CLI commands (init, create, up, down, status) and programmatic API. Key differentiators: lightweight, lock-based concurrency, checksum validation, and support for both CommonJS and ESM module systems. Common pitfalls include incorrect configuration file exports, missing peer dependency mongodb, and improper use of up/down functions in migration files.","status":"active","version":"14.0.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 migrate-mongo","lang":"bash","label":"npm"},{"cmd":"yarn add migrate-mongo","lang":"bash","label":"yarn"},{"cmd":"pnpm add migrate-mongo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for database connection. Must be installed separately.","package":"mongodb","optional":false}],"imports":[{"note":"Default export; named exports also available for individual functions.","wrong":"import { migrateMongo } from 'migrate-mongo'","symbol":"default","correct":"import migrateMongo from 'migrate-mongo'"},{"note":"Named export for programmatic use, not default.","wrong":"import up from 'migrate-mongo'","symbol":"up","correct":"import { up } from 'migrate-mongo'"},{"note":"Named export for programmatic use, not default.","wrong":"import down from 'migrate-mongo'","symbol":"down","correct":"import { down } from 'migrate-mongo'"},{"note":"Both CJS and ESM supported; ESM recommended for modern projects.","wrong":"const config = require('migrate-mongo').config","symbol":"config","correct":"import { config } from 'migrate-mongo'"}],"quickstart":{"code":"// 1. Install: npm install migrate-mongo mongodb\n// 2. Initialize project: npx migrate-mongo init\n// 3. Configure 'migrate-mongo-config.js' with your MongoDB URL and database name.\n// 4. Create a migration: npx migrate-mongo create add-users\n// 5. Edit the generated file in migrations/:\n\nexport async function up(db, client) {\n  await db.collection('users').insertOne({ name: 'John', email: 'john@example.com' });\n}\nexport async function down(db, client) {\n  await db.collection('users').deleteOne({ name: 'John' });\n}\n\n// 6. Run migrations: npx migrate-mongo up\n// Programmatic usage:\nimport { up, down, config } from 'migrate-mongo';\nconst migrationConfig = await config.read();\nawait up(migrationConfig);\n// or await down(migrationConfig);","lang":"javascript","description":"Shows full workflow: install, init, create migration file with up/down functions, run via CLI or programmatic API."},"warnings":[{"fix":"Upgrade Node.js to 20 or later.","message":"Node.js >=20.0.0 required as of v14. Older versions will fail.","severity":"breaking","affected_versions":">=14.0.0"},{"fix":"Install mongodb driver ^4.4.1 || ^5.0.0 || ^6.0.0 || ^7.0.0.","message":"MongoDB driver versions below 4.4 are not supported; driver 7.x requires specific connection options.","severity":"breaking","affected_versions":">=14.0.0"},{"fix":"Remove these options from config; they are now default.","message":"useNewUrlParser and useUnifiedTopology options are deprecated in MongoDB driver 4.x+.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Use .mjs extension or configure package.json appropriately.","message":"If using ESM (moduleSystem: 'esm'), migration files must use .mjs extension or set \"type\": \"module\" in package.json.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Install locally with 'npm install migrate-mongo --save-dev' or globally with 'npm install -g migrate-mongo'.","cause":"migrate-mongo not installed or not in PATH (global install missing).","error":"Error: Cannot find module 'migrate-mongo'"},{"fix":"Run 'migrate-mongo up' to apply pending migrations and create changelog collection.","cause":"Migration database not initialized; need to run 'migrate-mongo up' first.","error":"Error: Collection not found: changelog"},{"fix":"Remove 'useCreateIndex' and 'useFindAndModify' from config; they are no longer needed.","cause":"Deprecated options passed to MongoDB driver.","error":"MongoParseError: options usecreateindex, usefindandmodify are not supported"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}