mongration

library1.0.1jsnpmunverified

A Node.js migration framework for MongoDB that persists migration state in the database, supports checksums to detect changes in already-applied migrations, rollback on error, replica sets, and synchronous/asynchronous migrations. The current version is 1.0.1 (no recent updates). It features a programmatic API and a CLI, differentiating from other MongoDB migration tools by its built-in checksum verification and automatic rollback.

database

npm install mongration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGRATION

mongration

databasejavascriptv1.0.1

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.

Migration

✓ import { Migration } from 'mongration'

✗ const Migration = require('mongration').Migration;

Package supports both ESM and CommonJS. The default export is an object with Migration class.

migration step interface

✓ const step = { id: 'step-name', up: function(db, next) { /* ... */ }, down: function(db, next) { /* ... */ } }

✗ const step = { id: 'step-name', id: 'duplicate', up: 'string' }

Step objects must have unique 'id', 'up' (required), and 'down' (optional) functions receiving (db, next).

Migration constructor config

✓ new Migration({ hosts: 'localhost:27017', db: 'mydb', migrationCollection: 'migrations' })

✗ new Migration({ host: 'localhost', db: 'mydb' })

Config must include 'hosts' (string) or 'mongoUri', and 'migrationCollection' is required. 'user' and 'password' optional.

Initializes mongration with MongoDB config, defines a migration step, adds it, and runs up to 3 pending migrations.

import { Migration } from 'mongration'; const config = { hosts: process.env.MONGO_HOST ?? 'localhost:27017', db: process.env.MONGO_DB ?? 'test', migrationCollection: 'migrationversion' }; const migration = new Migration(config); const step = { id: 'my-first-migration', up: function(db, next) { db.collection('users').insertOne({ name: 'test' }, next); }, down: function(db, next) { db.collection('users').deleteOne({ name: 'test' }, next); } }; migration.add([step]); migration.migrate(3, (err, results) => { if (err) { console.error('Migration failed:', err); } else { console.log('Migration results:', results); } });

Debug

Known issues

gotchaThe 'migrationCollection' config property is required; missing it will cause a runtime error.

fix

Always include 'migrationCollection' in the configuration object.

affects: >=0.0.0

gotchaStep 'id' must be unique across all steps; duplicates cause unpredictable behavior.

fix

Ensure each step has a unique 'id' (string).

affects: >=0.0.0

gotchaThe 'up' function must call the 'next' callback to mark completion; not doing so hangs the migration.

fix

Always invoke 'next' (or 'next(err)') inside 'up' and 'down' functions.

affects: >=0.0.0

gotchaThe package uses the MongoDB native driver version 2.x internally; incompatible with driver 3.x or later.

fix

Pin mongodb driver to version 2.x or use an alternative like migrate-mongo.

affects: <=1.0.1

Errors

Common errors & fixes

Error: Cannot find module 'mongration'

Package not installed or path incorrect.

fix

Run 'npm install mongration' and ensure node_modules is in the require path.

TypeError: migration.add is not a function

Using wrong import or initialization; 'Migration' object not created correctly.

fix

Use 'const migration = new Migration(config)' then 'migration.add(step)'.

TypeError: step.up is not a function

Step object missing 'up' property or it's not a function.

fix

Ensure each step has 'up: function(db, next) { ... }'.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/awapps/mongration ↗

packagemongration ↗

homepagehttps://github.com/awapps/mongration#readme ↗