migration-mongodb

library1.0.3jsnpmunverified

A minimalistic migration and seeding package for MongoDB that automates running migration files on app startup. Version 1.0.3 provides a simple synchronous initializer that scans a folder for files containing 'migration' in their name and executes them sequentially. It is designed for small projects or prototypes where a full migration framework is overkill. The package has no runtime dependencies beyond the native MongoDB driver. It does not support rollbacks, configuration files, or CLI commands; migrations are automatically run each time the application starts. The release cadence is unknown; the package has seen no recent updates. Compared to alternatives like migrate-mongo or mongodb-migrate, this package is much simpler but lacks features like down-migrations, version locking, and asynchronous control.

database

npm install migration-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MIGRATION-MONGODB

migration-mongodb

databasejavascriptv1.0.3

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 export (function)

✓ import mongodbMigrations from 'migration-mongodb'

✗ const mongodbMigrations = require('migration-mongodb').default

The package is CommonJS and exports a single function; in ESM environments, default import works if using bundler or Node >= 14 with 'type': 'module'.

require style in CommonJS

✓ const mongodbMigrations = require('migration-mongodb')

✗ const { migrationMongodb } = require('migration-mongodb')

The package exports a function directly, not an object. Destructuring will yield undefined.

TypeScript usage

✓ import mongodbMigrations from 'migration-mongodb'; import { Db } from 'mongodb';

✗ import * as mongodbMigrations from 'migration-mongodb'

No TypeScript definitions are included; use @types/mongodb for Db type. The default import works but yields 'any' type.

Shows how to initialize and run MongoDB migrations automatically using the default exported function.

const mongodbMigrations = require('migration-mongodb'); const mongoClient = require('mongodb').MongoClient; // Connection details const connectionUrl = 'mongodb://localhost:27017'; const dbName = 'myapp'; const migrationFolder = __dirname + '/migrations'; // Run migrations synchronously on startup mongodbMigrations(connectionUrl, dbName, migrationFolder); console.log('Migrations executed'); // Example migration file (e.g., ./migrations/create-users-migration.js): // module.exports = async function(db) { // await db.createCollection('users'); // await db.collection('users').insertOne({ username: 'admin' }); // };

Debug

Known issues

breakingMigrations run automatically on every application startup; there is no concept of 'already ran'. If a migration is not idempotent (e.g., creates a collection that already exists), it will throw an error and crash the app.

fix

Make migration functions idempotent by checking existence before creation, or use a migration tool with state tracking.

affects: all

gotchaMigration file names must contain the string 'migration' (case-sensitive) or they will be ignored. For example, 'create-users.js' will not be executed.

fix

Rename files to include 'migration' in the filename, e.g., 'create-users-migration.js'.

affects: all

gotchaThe package does not support rollback or down migrations. Once a migration file is removed, the changes are not automatically reversed.

fix

Manually handle rollbacks in your application or choose a migration framework that supports down migrations.

affects: all

gotchaThe migration function receives a raw `db` object from the MongoDB driver, not a mongoose or other ODM connection. If you use mongoose, you must convert or use the native driver.

fix

Access the native db via mongoose.connection.db and pass it instead of relying on the package's connection logic, or use a different migration tool.

affects: all

Errors

Common errors & fixes

TypeError: mongodbMigrations is not a function

Using import incorrectly; the package is CommonJS and may not be compatible with ESM import syntax in some environments.

fix

Use require('migration-mongodb') or configure your bundler/Node to handle CommonJS modules.

Error: Cannot read property 'collection' of null

The migration folder does not exist or no files contain 'migration' in the name.

fix

Ensure the migration folder exists and contains at least one file with 'migration' in its filename.

MongoError: Collection already exists

Running a migration that tries to create an existing collection (non-idempotent migration) on subsequent app restarts.

fix

Add a check: if (await db.listCollections({name: 'yourCollection'}).hasNext()) return;

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

mongodbrequiredRequired as a peer dependency; the package directly uses the MongoDB driver's Db object inside migration functions.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/anshulsoni6/migration-mongodb ↗

packagemigration-mongodb ↗

homepagehttps://github.com/anshulsoni6/migration-mongodb#readme ↗