mgdb-migrator

library7.0.0jsnpmunverified

A TypeScript-first MongoDB migration library supporting up/down migrations with configurable logging and database connections. Current stable version 7.0.0 (semver), requires Node >=20, peer dependency on mongodb driver ^5 || ^6 || ^7. Differentiators: built-in logger, esm/cjs support, types included, simple API with both singleton and instance usage. Actively maintained with CI.

database

npm install mgdb-migrator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MGDB-MIGRATOR

mgdb-migrator

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

migrator

✓ import { migrator } from 'mgdb-migrator'

✗ const { migrator } = require('mgdb-migrator')

Default singleton instance, available via named export

Migrator

✓ import { Migrator } from 'mgdb-migrator'

✗ import Migrator from 'mgdb-migrator'

Class for creating custom instances, not default export

MigrationConfig

✓ import type { MigrationConfig } from 'mgdb-migrator'

✗ import { MigrationConfig } from 'mgdb-migrator'

Type export, requires type import syntax in TypeScript

Shows configuration, migration definition (up/down), and execution to latest version

import { migrator } from 'mgdb-migrator'; await migrator.config({ log: true, collectionName: 'migrations', db: { connectionUrl: process.env.MONGO_URL ?? 'mongodb://localhost:27017/mydb', }, }); migrator.add({ version: 1, name: 'create_users_collection', up: async (db, logger) => { await db.createCollection('users', { validator: { $jsonSchema: { bsonType: 'object', required: ['email'] } } }); }, down: async (db) => { await db.collection('users').drop(); }, }); await migrator.migrateTo('latest');

Debug

Known issues

breakingv7.0.0 drops support for Node <20

fix

Upgrade Node to v20+ or pin to v6.x

affects: >=7.0.0

breakingv6.0.0 changed config() to return a Promise; previously synchronous

fix

Await migrator.config() or use .then()

affects: >=6.0.0 <7.0.0

gotchamigrator.add returns void, chaining not supported

fix

Call migrator.add separately for each migration

affects: >=1.0.0

gotchamigrateTo('latest') only goes up; does not rollback overshoot

fix

Use migrateTo(versionNumber) for target version; down migrations run if needed

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'mgdb-migrator'

Package not installed or using old Node.js that doesn't support self-referencing

fix

Install with npm install mgdb-migrator or use relative path if local

TypeError: migrator.config is not a function

Importing default instead of named export (e.g., import migrator from 'mgdb-migrator')

fix

Use import { migrator } from 'mgdb-migrator'

MongoClient is not a constructor

Incompatible mongodb driver version (e.g., v4 vs v5)

fix

Enable peer dependency: npm install mongodb@^6

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency for database operations

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/Airfordable/mgdb-migrator ↗

packagemgdb-migrator ↗

homepagehttps://github.com/Airfordable/mgdb-migrator#readme ↗