mongo-migra

library1.8.0jsnpmunverified

Mongo Migra is a simple, dependency-light migration tool for MongoDB databases, version 1.8.0 (stable release cycle ~1 year). It uses the native MongoDB Node.js driver directly, with no ORM or additional abstraction. Key differentiator: supports replica sets and transactions, allowing migration scripts to use sessions. It also offers TypeScript type definitions and a CLI for creating, deleting, applying, rolling back, and tracking migrations. Unlike other tools, it avoids heavy frameworks and keeps the setup minimal.

database

npm install mongo-migra

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-MIGRA

mongo-migra

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

default

✓ import mongoMigra from 'mongo-migra';

✗ const mongoMigra = require('mongo-migra');

Package is ESM-only since v1.8.0; TypeScript types included.

MongoMigraConfig

✓ import { MongoMigraConfig } from 'mongo-migra';

✗ import { Config } from 'mongo-migra';

Named export for configuration type in TypeScript.

MigrationScript

✓ import type { MigrationScript } from 'mongo-migra';

✗ import { MigrationScript } from 'mongo-migra';

Use type-only import to avoid runtime overhead; MigrationScript is a type definition.

Initialize and run all pending migrations using TypeScript with environment variable for URI.

import { MongoClient } from 'mongodb'; import mongoMigra from 'mongo-migra'; const config = { uri: process.env.MONGO_URI ?? '', database: 'myapp', migrationsPath: './migrations', collectionName: 'migrations', }; async function run() { await mongoMigra.up(config); } run().catch(console.error);

Debug

Known issues

breakingmongo-migra v1.8.0 dropped CommonJS support; all imports must be ESM.

fix

Use ES module imports (import) instead of require().

affects: >=1.8.0

deprecatedThe action=compile is no longer necessary if running directly in TypeScript or using ts-node.

fix

Omit compile step; run with ts-node or use node with transpiled JS.

affects: >=1.8.0

gotchaTransactions only work when connecting to a replica set; single node does not support sessions.

fix

Ensure MongoDB is running as a replica set (even a single-node replica set) for transactional migrations.

affects: >=0.1.0

gotchaConfig parameter must be passed as 'config=<path>' in CLI, not as a flag.

fix

Use syntax: mongo-migra action=up config=./custom-config.json

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: mongoMigra is not a function

Importing as default export in CommonJS environment that still uses require.

fix

Switch to ESM (import mongoMigra from 'mongo-migra') or update Node to support ESM.

MongoError: Transaction numbers are only supported on replica set members

Attempting to use transactions on a standalone MongoDB instance.

fix

Configure MongoDB as a replica set (e.g., single-node replica set) before running transactional migrations.

Error: Cannot find module 'mongo-migra'

Package not installed, or installed globally but used locally (or vice versa).

fix

Run 'npm install mongo-migra' in the project directory, or use global install if running CLI globally.

SyntaxError: Unexpected token 'export'

Running ESM code with old Node.js version that does not support ES modules.

fix

Upgrade Node.js to >=12.22.0 or use a transpiler like Babel.

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency for MongoDB connection and operations

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/JONAF2103/mongo-migra ↗

packagemongo-migra ↗

homepagehttps://github.com/JONAF2103/mongo-migra#readme ↗