Mongoose Migration Framework

Common errors

• Error: Missing required argument: dbConnectionUri

  cause 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.

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

  cause 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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: When performing a rollback, always specify the target migration name: `npx migrate down <migration_name>`.
• gotcha 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.
  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.

Install

• npm install migrate-mongoose npm
• yarn add migrate-mongoose yarn
• pnpm add migrate-mongoose pnpm

Imports

• mongoose
  wrong:

  const mongoose = require('mongoose');

  correct:

  import mongoose from '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
  wrong:

  import { run } from 'migrate-mongoose';

  correct:

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

  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.

Quickstart

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