{"id":16649,"library":"migrate-mongodb-og","title":"migrate-mongodb-og: MongoDB Migration Tool (Fork for MongoDB 7+)","description":"This package, `migrate-mongodb-og`, is a critical fork of the popular `migrate-mongo` database migration tool designed for Node.js environments. It provides a robust CLI and programmatic API for managing schema changes in MongoDB databases. The current stable version, 11.0.1, specifically addresses compatibility challenges by supporting a broad range of MongoDB driver versions, including `^4.4.1`, `^5.0.0`, `^6.0.0`, and notably `^7.0.0`. Its key differentiator is its explicit support for MongoDB 7 and beyond, filling a gap left by the original project. While there isn't a strict release cadence mentioned, as a fork, it typically updates to maintain compatibility with new MongoDB versions and to integrate relevant bug fixes or features from the upstream project. It enables developers to define migration scripts in JavaScript, offering functions to bring the database schema `up` or `down`, create new migration files, and check `status`.","status":"active","version":"11.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/sylvia-ivy/migrate-mongodb-og","tags":["javascript","migrate mongo mongodb migrations database mongodb7"],"install":[{"cmd":"npm install migrate-mongodb-og","lang":"bash","label":"npm"},{"cmd":"yarn add migrate-mongodb-og","lang":"bash","label":"yarn"},{"cmd":"pnpm add migrate-mongodb-og","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core driver for interacting with MongoDB. Required as a peer dependency for database operations.","package":"mongodb","optional":false}],"imports":[{"note":"The library's primary programmatic interface is a CommonJS module exporting a single object containing `up`, `down`, `create`, `status`, `init`, and `database` methods. Named imports are generally not supported at the top-level.","wrong":"import { up, down } from 'migrate-mongodb-og';","symbol":"migrateMongo","correct":"const migrateMongo = require('migrate-mongodb-og');"},{"note":"For ESM projects, use a default import. Ensure `type: 'module'` is set in `package.json` or use a `.mjs` file extension. Named imports for individual functions are generally not supported at the top-level.","wrong":"import { up, down } from 'migrate-mongodb-og';","symbol":"migrateMongo (ESM)","correct":"import migrateMongo from 'migrate-mongodb-og';"},{"note":"The configuration object is typically loaded from a local `migrate-mongo-config.js` file created by `migrate-mongo init`. This object is then passed to `migrateMongo.config.set()` before running migrations programmatically.","wrong":"import { config } from 'migrate-mongodb-og';","symbol":"config","correct":"const config = require('./migrate-mongo-config');"},{"note":"The `database` utility, available via `migrateMongo.database`, provides a `connect()` method that returns the native `mongodb.Db` and `mongodb.MongoClient` instances for use in migration scripts. These are typically passed to `up` and `down` functions.","symbol":"db, client","correct":"const { db, client } = await migrateMongo.database.connect();"}],"quickstart":{"code":"const fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst projectDir = 'albums-migrations-quickstart';\nconst configFilePath = path.join(projectDir, 'migrate-mongo-config.js');\nconst migrationsDir = path.join(projectDir, 'migrations');\n\n// Clean up previous runs if any\nif (fs.existsSync(projectDir)) {\n  fs.rmSync(projectDir, { recursive: true, force: true });\n}\n\nconsole.log(`Creating project directory: ${projectDir}`);\nexecSync(`mkdir ${projectDir} && cd ${projectDir} && npx migrate-mongodb-og init`, { stdio: 'inherit' });\n\n// Read the generated config file\nlet configContent = fs.readFileSync(configFilePath, 'utf8');\n\n// Update the MongoDB URL and database name with environment variables\nconfigContent = configContent.replace(\n  'url: \"mongodb://localhost:27017\"',\n  `url: process.env.MONGODB_URL ?? \"mongodb://localhost:27017\"`\n);\nconfigContent = configContent.replace(\n  'databaseName: \"YOURDATABASENAME\"',\n  `databaseName: process.env.MONGODB_DB_NAME ?? \"quickstartdb\"`\n);\n// Remove useNewUrlParser if it causes issues with newer drivers, as it's deprecated\nconfigContent = configContent.replace('useNewUrlParser: true', '// useNewUrlParser: true');\n// Also remove useUnifiedTopology which is also deprecated\nconfigContent = configContent.replace('useUnifiedTopology: true', '// useUnifiedTopology: true');\n\nfs.writeFileSync(configFilePath, configContent);\n\nconsole.log(`Updated configuration in ${configFilePath}`);\nconsole.log(`Creating a sample migration...`);\nexecSync(`cd ${projectDir} && npx migrate-mongodb-og create first-migration`, { stdio: 'inherit' });\n\n// Add content to the created migration file\nconst migrationFileName = fs.readdirSync(migrationsDir).find(f => f.includes('first-migration'));\nif (migrationFileName) {\n  const migrationFilePath = path.join(migrationsDir, migrationFileName);\n  const migrationContent = `\nmodule.exports = {\n  async up(db, client) {\n    // TODO write your migration here.\n    // Example: Insert a document into a collection\n    console.log('Running up migration: first-migration');\n    await db.collection('users').insertOne({ name: 'Test User', createdAt: new Date() });\n  },\n\n  async down(db, client) {\n    // TODO write the way to undo your migration (if necessary).\n    // Example: Remove the document inserted in 'up'\n    console.log('Running down migration: first-migration');\n    await db.collection('users').deleteOne({ name: 'Test User' });\n  }\n};\n`;\n  fs.writeFileSync(migrationFilePath, migrationContent);\n  console.log(`Added content to migration file: ${migrationFileName}`);\n}\n\nconsole.log(\"Quickstart complete. To run migrations: cd \" + projectDir + \" && npx migrate-mongodb-og up\");\nconsole.log(\"Set MONGODB_URL and MONGODB_DB_NAME environment variables for your database connection.\");","lang":"javascript","description":"This quickstart demonstrates how to initialize a migration project, configure the connection to MongoDB using environment variables, and create a basic migration file with `up` and `down` functions."},"warnings":[{"fix":"Run `npm uninstall migrate-mongo` then `npm install migrate-mongodb-og`. Update all `require()` or `import` statements from `'migrate-mongo'` to `'migrate-mongodb-og'`.","message":"This package (`migrate-mongodb-og`) is a fork of the original `migrate-mongo`. Existing projects using `migrate-mongo` must update their `package.json` and import paths to switch to this fork.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Check your `package.json` for the `mongodb` dependency and update it to a compatible version, e.g., `npm install mongodb@^7`.","message":"The package has peer dependencies on `mongodb` driver versions `^4.4.1 || ^5.0.0 || ^6.0.0 || ^7.0.0`. Ensure your project's `mongodb` dependency matches one of these versions to avoid compatibility issues.","severity":"gotcha","affected_versions":">=11.0.0"},{"fix":"Remove `useNewUrlParser: true` and `useUnifiedTopology: true` from the `options` object within your `migrate-mongo-config.js` file.","message":"MongoDB connection options like `useNewUrlParser: true` and `useUnifiedTopology: true` are deprecated and no longer needed (and may cause warnings) with `mongodb` driver versions 4.x and higher. They should be removed from `migrate-mongo-config.js`.","severity":"deprecated","affected_versions":">=11.0.0"},{"fix":"Carefully review the `mongodb` section in `migrate-mongo-config.js`. Ensure `url` points to your MongoDB instance and either includes the database name (e.g., `mongodb://localhost:27017/MYDB`) or `databaseName` is explicitly set.","message":"The `migrate-mongo-config.js` file requires either a `url` property with the database name encoded, or both `url` and `databaseName` properties. Misconfiguration here is a common source of connection errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your MongoDB server is running. Verify the `url` in `migrate-mongo-config.js` matches your MongoDB instance's address and port.","cause":"The MongoDB server is not running or the connection URL in `migrate-mongo-config.js` is incorrect.","error":"MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017"},{"fix":"Run the command from a directory where your user has write permissions, or use `sudo` (not recommended for general use) or fix directory permissions.","cause":"The command `migrate-mongo init` or `migrate-mongo create` was run in a directory where the user lacks write permissions to create the `migrations` folder.","error":"Error: EACCES: permission denied, mkdir 'migrations'"},{"fix":"Edit `migrate-mongo-config.js` and provide a valid `url` and `databaseName` within the `mongodb` object. Remember `databaseName` can also be part of the `url` string.","cause":"The `migrate-mongo-config.js` file is missing the required MongoDB connection details.","error":"The 'url' or 'databaseName' property is missing or empty in the config."},{"fix":"For CommonJS, use `const migrateMongo = require('migrate-mongodb-og');` then `migrateMongo.up()`. For ESM, use `import migrateMongo from 'migrate-mongodb-og';` then `migrateMongo.up()`.","cause":"Attempting to use named imports for functions (`import { up } from 'migrate-mongodb-og';`) when the module primarily exports a single object with methods, or using an incorrect CommonJS destructuring.","error":"TypeError: migrateMongo.up is not a function"},{"fix":"Either revert the changes to the migration file to its original state, or, if the changes are intentional and idempotent, set `useFileHash: false` in `migrate-mongo-config.js` (use with caution), or create a new migration for the additional changes.","cause":"The `useFileHash` option is enabled in `migrate-mongo-config.js`, and a migration file was modified after it was already applied to the database.","error":"Error: Migration \"20230101000000-my-migration.js\" already applied, but its content has changed."}],"ecosystem":"npm"}