east-mongo

[!NOTE] This is a fork of okv/east-mongo, rewritten in TypeScript and kept up to date with current MongoDB driver versions.

A MongoDB adapter for east, the Node.js database migration tool. It uses the MongoDB Node.js driver under the hood and passes a pre-connected MongoClient instance directly into each migration.

Executed migration names are tracked in a _migrations collection in the target database, with each document's _id set to the migration name.

A default migration template is included at migrationTemplates/async.ts and will be used automatically unless you override it. To use a custom template, set template in your .eastrc:

module.exports = {
  template: require.resolve('@feedbackfruits/east-mongo/migrationTemplates/async.ts')
}

or in TypeScript:

export default {
  template: require.resolve('@feedbackfruits/east-mongo/migrationTemplates/async.ts')
}

Compatibility

east-mongo targets the current, active, and maintenance releases of Node.js — currently tested against versions 22 and 24.

For MongoDB, we follow the official driver support matrix:

• MongoDB lifecycle policy
• Node.js driver compatibility matrix

The minimum supported MongoDB server version is 7.0 and the minimum supported driver version is 5.7.

Installation

mongodb is a peer dependency, so install it alongside east and this adapter:

npm install east @feedbackfruits/east-mongo mongodb

yarn add east @feedbackfruits/east-mongo mongodb

pnpm add east @feedbackfruits/east-mongo mongodb

Usage

Create an .eastrc file at the root of your project:

{
	"adapter": "@feedbackfruits/east-mongo",
	"url": "mongodb://localhost:27017/test"
}

You can also pass the adapter and URL directly via the CLI:

east migrate --adapter @feedbackfruits/east-mongo --url $MONGODB_URI

To run TypeScript migrations, use tsx:

npm install -DE tsx
tsx node_modules/east/bin/east.js migrate --adapter @feedbackfruits/east-mongo --url $MONGODB_URI --migration-extension ts

url should be a valid MongoDB connection string. For all available options, see the MongoClientOptions reference.

Migrations created with the default template look like:

import type { MongoClient } from 'mongodb';

exports.tags = [];

exports.migrate = async (client: MongoClient) => {
  // Migration definition
};

exports.rollback = async (client: MongoClient) => {
  // Rollback definitions
};

For more on running and managing migrations, see the east CLI usage and library usage docs.