{"id":15139,"library":"migrate-mongoose","title":"Mongoose Migration Framework","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/balmasi/migrate-mongoose","tags":["javascript","migrate","migration","mongoose","schema","mongodb","db","nosql"],"install":[{"cmd":"npm install migrate-mongoose","lang":"bash","label":"npm"},{"cmd":"yarn add migrate-mongoose","lang":"bash","label":"yarn"},{"cmd":"pnpm add migrate-mongoose","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for database interaction and schema management.","package":"mongoose","optional":false}],"imports":[{"note":"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.","wrong":"const mongoose = require('mongoose');","symbol":"mongoose","correct":"import mongoose from 'mongoose';"},{"note":"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.","wrong":"import { run } from 'migrate-mongoose';","symbol":"run","correct":"require('migrate-mongoose'); // This primarily executes the CLI entry point"},{"note":"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.","symbol":"MigrationFunction","correct":"/** @typedef {import('mongoose').Connection} MongooseConnection */\n/** @typedef {(db: any, client: MongooseConnection) => Promise<void>} MigrationFunction */"}],"quickstart":{"code":"npm install migrate-mongoose\n\n# Configure database URI via .env file\necho \"MIGRATE_dbConnectionUri=mongodb://localhost:27017/my_app_db\" > .env\n\n# Or, set as environment variable directly (e.g., in a CI/CD pipeline)\n# export MIGRATE_dbConnectionUri=mongodb://localhost:27017/my_app_db\n\n# Create a new migration file\nnpx migrate create add_users_collection\n\n# This will generate a file like './migrations/123456789-add_users_collection.js'\n# Edit the migration file (example content for add_users_collection.js):\n/*\nmodule.exports = {\n  async up(db, client) {\n    const users = client.connection.db.collection('users');\n    await users.createIndex({ email: 1 }, { unique: true });\n    console.log('Users collection index created.');\n  },\n\n  async down(db, client) {\n    const users = client.connection.db.collection('users');\n    await users.dropIndex('email_1'); // Use the actual index name from MongoDB\n    console.log('Users collection index dropped.');\n  }\n};\n*/\n\n# Run pending migrations (applies 'up' function)\nnpx migrate up\n\n# List all migrations and their status\nnpx migrate list","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Migration 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When performing a rollback, always specify the target migration name: `npx migrate down <migration_name>`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Configuration 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.","severity":"gotcha","affected_versions":">=3.x"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Provide the database connection URI using `npx migrate <command> --dbConnectionUri <uri>` or by setting `export MIGRATE_dbConnectionUri='<uri>'` (or in a `.env` file).","cause":"The `--dbConnectionUri` option was not provided, nor was `MIGRATE_dbConnectionUri` set as an environment variable or in a `.env` file.","error":"Error: Missing required argument: dbConnectionUri"},{"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.","cause":"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.","error":"Error: There are no migrations to run."},{"fix":"Ensure the migration name is correct and the corresponding migration file exists. Use `npx migrate list` to see available migrations.","cause":"The migration name provided to `migrate down` does not correspond to an existing local migration file or a recorded migration in the database.","error":"Error: migration 'your_migration_name' not found"}],"ecosystem":"npm"}