East MongoDB Adapter

Common errors

• Error: Cannot find module 'mongodb'

  cause The 'mongodb' package, a peer dependency, was not installed alongside 'east-mongo'.
  fix Install the peer dependency: `npm install mongodb@^3` (or `mongodb@^2` if preferred) in your project.

• Error: Adapter 'east-mongo' not found. Check your .eastrc configuration.

  cause The 'east-mongo' package itself is not installed, or the 'adapter' path in your `.eastrc` file is incorrect.
  fix Ensure 'east-mongo' is installed (`npm install east-mongo`) and that your `.eastrc` has `"adapter": "east-mongo"`.

• MongoError: Topology was destroyed

  cause This often occurs with older MongoDB drivers when connection options or lifecycle management are not handled robustly, or when the MongoDB server is unavailable/restarts during operations.
  fix Verify your MongoDB connection URL and options in `.eastrc`. Ensure the MongoDB server is running and accessible. Consider adding more robust error handling and connection retry logic in your migration scripts, though the underlying driver version may be a limiting factor.

Warnings

• breaking This package is specifically designed for `east` version 1.x and `mongodb` native driver versions 2.x or 3.x. Using it with `east` versions prior to 1.x, or `mongodb` versions 4.x or newer, will likely lead to compatibility issues or errors.
  Fix: Ensure that `east` is installed at version >=1.0.0 and `mongodb` is installed at 2.x.x or 3.x.x (`npm install east@^1 east-mongo mongodb@^3`). For newer `mongodb` or `east` versions, consider using an alternative, more modern migration solution.
• breaking The `east-mongo` package is abandoned, with no updates or activity since 2017. This means it will not receive bug fixes, security patches, or compatibility updates for newer Node.js versions, MongoDB server versions, or `mongodb` driver updates.
  Fix: It is strongly recommended to find an alternative, actively maintained MongoDB migration tool. Continuing to use an abandoned package introduces significant security and stability risks to your application.
• gotcha Node.js compatibility is limited to versions 4.0.0 and above. Running `east-mongo` on modern Node.js versions (e.g., Node.js 14, 16, 18, 20+) has not been tested and may encounter unexpected behavior or errors due to breaking changes in Node.js core.
  Fix: If you must use `east-mongo`, run it in a Node.js 4.x, 6.x, or 8.x environment. For modern applications, migrate to an actively maintained migration tool compatible with current Node.js LTS releases.
• gotcha The package's Snyk badge indicates 'Known Vulnerabilities'. Given its abandonment, these vulnerabilities are likely unpatched, posing a security risk to applications using this package.
  Fix: Conduct a thorough security audit of your dependencies and codebase if using `east-mongo`. Prioritize migrating to a secure, actively maintained alternative to mitigate potential exploits.

Install

• npm install east-mongo npm
• yarn add east-mongo yarn
• pnpm add east-mongo pnpm

Imports

• Adapter Configuration

  { "adapter": "east-mongo" }

  The adapter is loaded by `east` through its configuration file (`.eastrc`), not via direct JavaScript import statements. The value 'east-mongo' is a string reference to the installed package.
• Async Migration Template
  wrong:

  import { async } from 'east-mongo/lib/migrationTemplates/async.js'

  correct:

  require.resolve('east-mongo/lib/migrationTemplates/async.js')

  To use the async/await migration template, you reference its file path within the `.eastrc` configuration. This is a CommonJS `require.resolve` pattern, not an ES module import.
• Promises Migration Template (Default)

  // No explicit import needed if 'template' is not set in .eastrc

  The promises-based migration template is used by default if no 'template' path is specified in the `.eastrc` configuration.

Quickstart

This quickstart demonstrates how to configure `east-mongo` in an `.eastrc` file and provides a basic migration example using async/await functions for creating a collection, adding an index, inserting data, and a corresponding rollback function.

/* .eastrc file */
module.exports = {
	"adapter": "east-mongo",
	"url": "mongodb://localhost:27017/my_database",
	"options": {
		"server": {
			"socketOptions": {
				"socketTimeoutMS": 3600000
			}
		}
	}
};

/* Example migration file (e.g., 20230101000000-initial-setup.js) */
exports.tags = [];

exports.migrate = async function(params) {
	const { db, dropIndexIfExists } = params;

	// Example: Create a collection and an index
	await db.collection('users').createIndex({ email: 1 }, { unique: true });
	console.log('Created unique index on users.email');

	// Example: Insert some initial data
	await db.collection('settings').insertOne({ key: 'appVersion', value: '1.0.0' });
	console.log('Inserted initial app version setting');

	return Promise.resolve();
};

exports.rollback = async function(params) {
	const { db, dropIndexIfExists } = params;

	// Example: Rollback by dropping the collection and index
	await dropIndexIfExists('users', 'email_1'); // 'email_1' is the default index name
	await db.collection('users').drop();
	console.log('Dropped users collection and index');

	await db.collection('settings').deleteOne({ key: 'appVersion' });
	console.log('Removed app version setting');

	return Promise.resolve();
};