Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
migrateMongo
✓ const migrateMongo = require('migrate-mongodb-og');
✗ import { up, down } from '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)
✓ import migrateMongo from 'migrate-mongodb-og';
✗ import { up, down } 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
✓ const config = require('./migrate-mongo-config');
✗ import { config } from 'migrate-mongodb-og';
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.
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.");
migrate-mongo --version
Errors
Common errors & fixes
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017
The MongoDB server is not running or the connection URL in `migrate-mongo-config.js` is incorrect.
fixEnsure 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'
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.
fixRun 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.
The `migrate-mongo-config.js` file is missing the required MongoDB connection details.
fixEdit `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
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.
fixFor 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.
The `useFileHash` option is enabled in `migrate-mongo-config.js`, and a migration file was modified after it was already applied to the database.
fixEither 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.
Audit
Dependencies
mongodbrequiredCore driver for interacting with MongoDB. Required as a peer dependency for database operations.