Registry / database / mongo-migration-tool

mongo-migration-tool

library1.3.0jsnpmunverified

A database migration tool for MongoDB, version 1.3.0, with TypeScript type definitions. It allows you to manage schema and data migrations using change logs, with a focus on simplicity and MongoDB-native operations. Unlike other migration tools, it integrates directly with MongoDB change streams and supports rollback. The package is actively maintained with regular releases, providing a lightweight alternative to heavier frameworks.

database

npm install mongo-migration-tool

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-MIGRATION-TO

mongo-migration-tool

databasejavascriptv1.3.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.

MigrationTool

✓ import { MigrationTool } from 'mongo-migration-tool'

✗ const MigrationTool = require('mongo-migration-tool')

ESM-only since v1; CommonJS require is not supported.

MigrationEngine

✓ import { MigrationEngine } from 'mongo-migration-tool'

✗ import { Engine } from 'mongo-migration-tool'

The correct export name is `MigrationEngine`, not `Engine`.

MigrationConfig

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

✗ import { Config } from 'mongo-migration-tool'

TypeScript users should import the `MigrationConfig` type for configuration objects.

Migration

✓ import type { Migration } from 'mongo-migration-tool'

✗ import { Migration } from 'mongo-migration-tool'

`Migration` is a type-only export; use `import type` to avoid runtime errors.

Initializes the MigrationTool, connects to MongoDB, runs pending migrations, and closes the connection.

import { MigrationTool } from 'mongo-migration-tool'; import { MongoClient } from 'mongodb'; const client = new MongoClient(process.env.MONGO_URI ?? 'mongodb://localhost:27017'); const tool = new MigrationTool(client, { database: 'myapp', migrationsCollection: 'migrations', migrationsDir: './migrations' }); async function run() { await client.connect(); await tool.run(); console.log('Migrations completed'); await client.close(); } run().catch(console.error);

Debug

Known issues

breakingThe `run` method no longer accepts a callback argument as of v2.

fix

Use the promise-based API: `await tool.run()` instead of `tool.run(callback)`.

affects: >=2.0

deprecatedThe `createMigration` CLI command is deprecated; use `generate` instead.

fix

Run `npx mongo-migration-tool generate <name>` instead.

affects: >=1.2.0

gotchaAlways ensure the migration directory has a trailing slash when setting `migrationsDir`.

fix

Provide a string that ends with '/' (e.g., './migrations/') or use `path.join()` to normalize.

affects: >=1.0.0

gotchaRunning multiple instances concurrently can cause duplicate migration runs due to race conditions.

fix

Use a distributed lock mechanism (e.g., based on MongoDB atomic findAndModify) before running migrations.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: MigrationTool is not a constructor

Using CommonJS `require` with ESM-only package.

fix

Switch to ESM import: `import { MigrationTool } from 'mongo-migration-tool'`

TypeError: tool.run is not a function

Attempting to use callback syntax with v2+.

fix

Use `await tool.run()` (promise-based) as callbacks were removed in v2.

MongoServerError: collection already exists

Migration script creates a collection that already exists.

fix

Use `db.createCollection('name', { strict: false })` or check existence first.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

mongodbrequiredRequired for MongoDB driver connection and operations

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ArchAngel776/mongo-migration-tool ↗

packagemongo-migration-tool ↗

homepagehttps://github.com/ArchAngel776/mongo-migration-tool#readme ↗