Registry / database / codemao-migrate-mongo

codemao-migrate-mongo

library2.2.7jsnpmunverified

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.

database

npm install codemao-migrate-mongo

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CODEMAO-MIGRATE-MO

codemao-migrate-mongo

databasejavascriptv2.2.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ module.exports.up = async (db) => { /* migration */ }

✗ module.exports.up = (db, next) => { next(); } (callback-style deprecated in newer versions)

Migrations can use async/await or return a Promise. Callback-style (next) still works but is legacy.

down

✓ module.exports.down = async (db) => { /* rollback */ }

✗ module.exports.down = (db, next) => { next(); } (same as up)

Use async functions to avoid callback nesting. Both 'up' and 'down' are required exports.

config

✓ module.exports = { mongodb: { url: '...', options: {} }, migrationsDir: 'migrations', changelogCollectionName: 'changelog' }

✗ Using require() to load config (it's a CommonJS module, but must export the object directly)

The config file is a CommonJS module exporting an object. It is read automatically by the CLI.

Shows how to initialize a project, create a migration file, write up/down functions, and run migrations using async/await.

// Initialize project const { execSync } = require('child_process'); execSync('mkdir albums-migrations && cd albums-migrations && migrate-mongo init', { stdio: 'inherit' }); // Edit config.js manually (mongodb.url) // Create migration execSync('migrate-mongo create add_albums', { stdio: 'inherit' }); // Then write migration file content: module.exports = { up: async (db) => { await db.collection('albums').insertMany([{ artist: 'Beatles', blacklisted: true }]); }, down: async (db) => { await db.collection('albums').deleteMany({ artist: 'Beatles' }); } }; // Run migrations execSync('migrate-mongo up', { stdio: 'inherit' });

Debug

Known issues

gotchaThe migration file must export both 'up' and 'down' functions. If 'down' is missing, migration down command will not work.

fix

Ensure each migration module exports both up and down functions, even if down is a no-op.

affects: >=1.0.0

gotchaThe 'db' object provided in migrations is the native MongoDB Db object, not a session or transaction context. Do not close the connection.

fix

Use db.collection() directly. Do not call db.close() or use MongoClient inside migrations.

affects: >=1.0.0

deprecatedCallback-style (db, next) is deprecated in favor of async/await or Promise-returning functions.

fix

Use async functions: module.exports.up = async (db) => { ... }

affects: >=2.0.0

gotchaThe changelog collection name is case-sensitive and defaults to 'changelog'. If you change it, migrations will not see previously applied ones.

fix

Keep the changelogCollectionName consistent across all environments.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'migrate-mongo'

The package is not installed globally or locally.

fix

Run 'npm install -g migrate-mongo' or 'npm install --save-dev migrate-mongo' and use npx.

Error: connect ECONNREFUSED 127.0.0.1:27017

MongoDB is not running on the default port.

fix

Start MongoDB service or update config.js with correct connection URL.

ReferenceError: module is not defined

Using ES modules (import/export) instead of CommonJS.

fix

Either use CommonJS (module.exports) or set 'type':'module' in package.json and use import/export syntax accordingly.

Cannot read property 'collection' of undefined

The db argument is not passed correctly or migration function signature is wrong.

fix

Ensure migration function accepts exactly one argument (db) for async style or two (db, next) for callback style.

Upgrade

Version history

2.2.7latest on npm

Audit

Dependencies

mongodbrequiredRequired for connecting to MongoDB and performing database operations within migrations.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/seppevs/migrate-mongo ↗

packagecodemao-migrate-mongo ↗

homepagehttps://github.com/seppevs/migrate-mongo#readme ↗