migrate-mongodb-og: MongoDB Migration Tool (Fork for MongoDB 7+)

Common errors

• MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

  cause The MongoDB server is not running or the connection URL in `migrate-mongo-config.js` is incorrect.
  fix Ensure your MongoDB server is running. Verify the `url` in `migrate-mongo-config.js` matches your MongoDB instance's address and port.

• Error: EACCES: permission denied, mkdir 'migrations'

  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.
  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.

• The 'url' or 'databaseName' property is missing or empty in the config.

  cause The `migrate-mongo-config.js` file is missing the required MongoDB connection details.
  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.

• TypeError: migrateMongo.up is not a function

  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.
  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()`.

• Error: Migration "20230101000000-my-migration.js" already applied, but its content has changed.

  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.
  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.

Warnings

• breaking 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.
  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'`.
• gotcha 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.
  Fix: Check your `package.json` for the `mongodb` dependency and update it to a compatible version, e.g., `npm install mongodb@^7`.
• deprecated 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`.
  Fix: Remove `useNewUrlParser: true` and `useUnifiedTopology: true` from the `options` object within your `migrate-mongo-config.js` file.
• gotcha 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.
  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.

Install

• npm install migrate-mongodb-og npm
• yarn add migrate-mongodb-og yarn
• pnpm add migrate-mongodb-og pnpm

Imports

• migrateMongo
  wrong:

  import { up, down } from 'migrate-mongodb-og';

  correct:

  const migrateMongo = require('migrate-mongodb-og');

  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.
• migrateMongo (ESM)
  wrong:

  import { up, down } from 'migrate-mongodb-og';

  correct:

  import migrateMongo from 'migrate-mongodb-og';

  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.
• config
  wrong:

  import { config } from 'migrate-mongodb-og';

  correct:

  const config = require('./migrate-mongo-config');

  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.
• db, client

  const { db, client } = await migrateMongo.database.connect();

  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.

Quickstart

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.

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

const projectDir = 'albums-migrations-quickstart';
const configFilePath = path.join(projectDir, 'migrate-mongo-config.js');
const migrationsDir = path.join(projectDir, 'migrations');

// Clean up previous runs if any
if (fs.existsSync(projectDir)) {
  fs.rmSync(projectDir, { recursive: true, force: true });
}

console.log(`Creating project directory: ${projectDir}`);
execSync(`mkdir ${projectDir} && cd ${projectDir} && npx migrate-mongodb-og init`, { stdio: 'inherit' });

// Read the generated config file
let configContent = fs.readFileSync(configFilePath, 'utf8');

// Update the MongoDB URL and database name with environment variables
configContent = configContent.replace(
  'url: "mongodb://localhost:27017"',
  `url: process.env.MONGODB_URL ?? "mongodb://localhost:27017"`
);
configContent = configContent.replace(
  'databaseName: "YOURDATABASENAME"',
  `databaseName: process.env.MONGODB_DB_NAME ?? "quickstartdb"`
);
// Remove useNewUrlParser if it causes issues with newer drivers, as it's deprecated
configContent = configContent.replace('useNewUrlParser: true', '// useNewUrlParser: true');
// Also remove useUnifiedTopology which is also deprecated
configContent = configContent.replace('useUnifiedTopology: true', '// useUnifiedTopology: true');

fs.writeFileSync(configFilePath, configContent);

console.log(`Updated configuration in ${configFilePath}`);
console.log(`Creating a sample migration...`);
execSync(`cd ${projectDir} && npx migrate-mongodb-og create first-migration`, { stdio: 'inherit' });

// Add content to the created migration file
const migrationFileName = fs.readdirSync(migrationsDir).find(f => f.includes('first-migration'));
if (migrationFileName) {
  const migrationFilePath = path.join(migrationsDir, migrationFileName);
  const migrationContent = `
module.exports = {
  async up(db, client) {
    // TODO write your migration here.
    // Example: Insert a document into a collection
    console.log('Running up migration: first-migration');
    await db.collection('users').insertOne({ name: 'Test User', createdAt: new Date() });
  },

  async down(db, client) {
    // TODO write the way to undo your migration (if necessary).
    // Example: Remove the document inserted in 'up'
    console.log('Running down migration: first-migration');
    await db.collection('users').deleteOne({ name: 'Test User' });
  }
};
`;
  fs.writeFileSync(migrationFilePath, migrationContent);
  console.log(`Added content to migration file: ${migrationFileName}`);
}

console.log("Quickstart complete. To run migrations: cd " + projectDir + " && npx migrate-mongodb-og up");
console.log("Set MONGODB_URL and MONGODB_DB_NAME environment variables for your database connection.");