Registry / database / db-mongo-migration

db-mongo-migration

library1.13.0jsnpmunverified

A command-line tool for running and managing MongoDB migrations. Version 1.13.0 supports both custom abstraction and native MongoDB operations with transaction handling. It uses YAML config for db connection, migration directory, and changelog collection. Ships TypeScript types. Competing with migrate-mongo, it offers native transaction support via INativeMigration. Release cadence is irregular; recent versions focus on stability and fixes. Works in Node.js (ESM).

database

npm install db-mongo-migration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DB-MONGO-MIGRATION

db-mongo-migration

databasejavascriptv1.13.0

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.

IMigration

✓ import { IMigration } from 'db-mongo-migration'

✗ const IMigration = require('db-mongo-migration').IMigration

Package is ESM-only since v1.10. Use TypeScript or ESM imports.

✓ import { DB } from 'db-mongo-migration'

DB is a wrapper type around MongoDB's Db with transaction support. Type-only import is safe.

INativeMigration

✓ import { INativeMigration } from 'db-mongo-migration'

Use this when you need direct access to MongoDB native Db and MongoClient for custom transaction handling.

MigrationConfig

✓ import { MigrationConfig } from 'db-mongo-migration'

Type for the config object if reading config programmatically. Only available in TypeScript.

Shows how to initialize, create, and run a migration with a sample migration file using the IMigration interface.

// 1. Initialize config (creates migration-config.yaml) // npx mongo-migrate init // 2. Create a migration // npx mongo-migrate create add-users // 3. Run migration (up) // npx mongo-migrate up // Sample migration file (migrations/xxxxxx-add-users.js): import { IMigration, DB } from 'db-mongo-migration' class Migration implements IMigration { async up(db: DB) { await db.collection('users').insertOne({ name: 'admin', role: 'admin' }); } async down(db: DB) { await db.collection('users').deleteOne({ name: 'admin' }); } } export default Migration;

Debug

Known issues

breakingESM-only since version 1.10. CommonJS require() will fail.

fix

Use import syntax or upgrade to ESM project.

affects: >=1.10.0

deprecateduseDefaultTransaction option in config is deprecated; transactions are now automatic.

fix

Remove useDefaultTransaction from config entirely.

affects: >=1.8.0

gotchaMigration files must export a default class implementing IMigration or INativeMigration. Named exports are ignored.

fix

Use `export default Migration;` at end of migration file.

affects: *

gotchaDatabase connection uses environment variables via dotenv, but config file path must resolve correctly. If .env is not loaded, connection fails silently.

fix

Ensure .env file exists in working directory or set variables explicitly.

affects: *

Errors

Common errors & fixes

Error: Cannot find module 'db-mongo-migration'

Package not installed or ESM misconfiguration in Node.js.

fix

Run `npm install db-mongo-migration` and ensure your project is set to ESM (type: module in package.json or use .mjs extension).

MongoError: bad auth Authentication failed.

Invalid database credentials in migration-config.yaml.

fix

Check the URL and databaseName fields; ensure environment variables are set correctly. Use URL format: mongodb://user:pass@host:port/db

TypeError: db.collection is not a function

Using db incorrectly; the 'db' parameter in up/down is a DB wrapper, not a native MongoDB Db object.

fix

Use the provided DB object methods (e.g., db.collection()). If you need native Db, use INativeMigration interface instead.

Upgrade

Version history

1.13.0latest on npm

Audit

Dependencies

mongodboptionalUsed for native MongoDB connections and transactions

commanderrequiredCLI argument parsing

yamlrequiredConfiguration file parsing

dotenvoptionalEnvironment variable loading for config

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/jorasmhj/db-mongo-migration ↗

packagedb-mongo-migration ↗

homepagehttps://github.com/jorasmhj/db-mongo-migration ↗