migrate-mongoose

library4.0.0jsnpmunverified

migrate-mongoose is a robust migration framework designed for Node.js projects that utilize Mongoose for MongoDB interaction. It's currently in version 4.0.0, having recently released a major update. A key differentiator is its approach to storing migration state directly within MongoDB, rather than relying on a local file system, making it well-suited for Platform as a Service (PaaS) deployments like Heroku where ephemeral file systems are common. The framework provides features such as access to Mongoose models directly within migration files, support for promises or standard callbacks, flexible configuration via files or environment variables (including `.env` support), and tools for managing (pruning) migration files. It tracks migration status globally in the database, simplifying deployment and ensuring consistency across environments. Release cadence appears to be driven by feature additions, Mongoose updates, or necessary dependency changes rather than a fixed schedule.

database

npm install migrate-mongoose

github ↗package ↗

INSTALL

IMPORT

SIG · MIGRATE-MONGOOSE

migrate-mongoose

databasejavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mongoose

✓ import mongoose from 'mongoose';

✗ const mongoose = require('mongoose');

migrate-mongoose is primarily a CLI tool. This import is for Mongoose itself, typically used within *user-defined migration files* (e.g., `migrations/add_users.js`) that are executed by migrate-mongoose, rather than for the migrate-mongoose package directly.

run

✓ require('migrate-mongoose'); // This primarily executes the CLI entry point

✗ import { run } from 'migrate-mongoose';

migrate-mongoose is not typically imported for programmatic use within application code, as its main interface is the command-line interface. Directly requiring the package from `node_modules` would generally invoke its CLI behavior or expose internal utilities not meant for public API. Use `npx migrate` instead.

MigrationFunction

✓ /** @typedef {import('mongoose').Connection} MongooseConnection */ /** @typedef {(db: any, client: MongooseConnection) => Promise<void>} MigrationFunction */

For TypeScript or JSDoc users, type definitions are typically used to define the expected signature of `up` and `down` functions within migration files. The package itself is JavaScript, so direct type exports are not present, but external `@types/migrate-mongoose` might be used for better autocompletion.

Demonstrates installation, configuration using a .env file, creating a new migration, editing the migration file with example Mongoose code, and then running and listing migrations.

npm install migrate-mongoose # Configure database URI via .env file echo "MIGRATE_dbConnectionUri=mongodb://localhost:27017/my_app_db" > .env # Or, set as environment variable directly (e.g., in a CI/CD pipeline) # export MIGRATE_dbConnectionUri=mongodb://localhost:27017/my_app_db # Create a new migration file npx migrate create add_users_collection # This will generate a file like './migrations/123456789-add_users_collection.js' # Edit the migration file (example content for add_users_collection.js): /* module.exports = { async up(db, client) { const users = client.connection.db.collection('users'); await users.createIndex({ email: 1 }, { unique: true }); console.log('Users collection index created.'); }, async down(db, client) { const users = client.connection.db.collection('users'); await users.dropIndex('email_1'); // Use the actual index name from MongoDB console.log('Users collection index dropped.'); } }; */ # Run pending migrations (applies 'up' function) npx migrate up # List all migrations and their status npx migrate list

Debug

Known issues

breakingVersion 4.0.0 removed Babel support. Projects relying on older Babel configurations for migration files may need to update their Node.js environment or transpile migrations separately if using very old ES features not natively supported by your Node.js version.

fix

Ensure your Node.js version (e.g., Node.js 14+) natively supports the ES features used in your migration files (async/await, etc.). No extra build step for migrations is typically needed now.

affects: >=4.0.0

gotchaMigration state is stored directly in MongoDB, which is a core feature but can be a surprise for users accustomed to file-based migration trackers. This is critical for PaaS environments, but means your database needs to be accessible.

fix

Be aware that the 'migrations' collection in your MongoDB tracks run migrations. Do not manually alter this collection unless you understand the implications. Ensure proper database connection string configuration.

affects: >=1.0.0

gotchaThe `down` command requires a specific migration name to roll back to, unlike `up` which can run all pending migrations by default. Omitting the migration name for `down` will result in an error.

fix

When performing a rollback, always specify the target migration name: `npx migrate down <migration_name>`.

affects: >=1.0.0

gotchaConfiguration options like `--dbConnectionUri` can be set via environment variables prefixed with `MIGRATE_` (e.g., `MIGRATE_dbConnectionUri`) or through a `.env` file. These take precedence over default options.

fix

Leverage `.env` files or environment variables for managing sensitive database credentials or simplifying CLI commands in development and production environments. Ensure `.env` files are not committed to source control.

affects: >=3.x

Errors

Common errors & fixes

Error: Missing required argument: dbConnectionUri

The `--dbConnectionUri` option was not provided, nor was `MIGRATE_dbConnectionUri` set as an environment variable or in a `.env` file.

fix

Provide the database connection URI using `npx migrate <command> --dbConnectionUri <uri>` or by setting `export MIGRATE_dbConnectionUri='<uri>'` (or in a `.env` file).

Error: There are no migrations to run.

You tried to run `migrate up`, but all local migration files already have a corresponding 'up' entry in the database, meaning they've all been applied.

fix

This is often not an error but an informational message. If you expect migrations to run, check if new migration files exist in your `migrations` directory or if they've already been applied.

Error: migration 'your_migration_name' not found

The migration name provided to `migrate down` does not correspond to an existing local migration file or a recorded migration in the database.

fix

Ensure the migration name is correct and the corresponding migration file exists. Use `npx migrate list` to see available migrations.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

mongooserequiredCore dependency for database interaction and schema management.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/balmasi/migrate-mongoose ↗

packagehttps://www.npmjs.com/package/migrate-mongoose ↗