MongoDB Memory Server Global

Common errors

• Error: MongoDB binary for version X.Y.Z not found.

  cause The `mongodb-memory-server-global` package failed to download the required MongoDB binary during installation, or the specified version is unsupported/unavailable.
  fix Check your network connection and proxy settings. Ensure the requested MongoDB version is supported by `mongodb-memory-server` (e.g., >=4.2.0 for v11+). Try deleting the `~/.cache/mongodb-binaries` directory and reinstalling, or manually specify a supported version with the `MONGOMS_VERSION` environment variable.

• TypeError: MongoMemoryServer.create is not a function

  cause Attempting to use `MongoMemoryServer` directly from `mongodb-memory-server-global` instead of `mongodb-memory-server`.
  fix Change your import statement from `import { MongoMemoryServer } from 'mongodb-memory-server-global'` to `import { MongoMemoryServer } from 'mongodb-memory-server'`.

• Node.js vX.Y.Z is not supported. Please use Node.js >= 20.19.0

  cause Running `mongodb-memory-server` with an unsupported Node.js version.
  fix Upgrade your Node.js environment to version 20.19.0 or newer. Consider using a Node Version Manager (NVM) to manage different Node.js versions for various projects.

Warnings

• breaking The default MongoDB binary version used by `mongodb-memory-server` has been updated to 8.2.x. This might affect tests expecting older MongoDB behavior or specific features.
  Fix: If specific MongoDB versions are required, set the `mongodb-version` configuration option (e.g., in `package.json` or via environment variables) to pin to an older version, for example `MONGOMS_VERSION=7.0.0`.
• breaking Support for MongoDB versions below 4.2.0 has been removed. Trying to specify older versions will result in download or startup failures.
  Fix: Ensure your project's MongoDB version requirements are 4.2.0 or higher. Update your `mongodb-version` configuration if you were using an unsupported version.
• breaking The minimum supported Node.js version is now 20.19.0. Running on older Node.js environments will lead to errors.
  Fix: Upgrade your Node.js environment to version 20.19.0 or higher. Use a Node.js version manager like `nvm` to manage multiple Node.js versions.
• breaking The TypeScript target in the project's `tsconfig` has been upgraded to `es2023`. This could potentially cause issues in projects with older TypeScript configurations or environments expecting a different target.
  Fix: Update your project's `tsconfig.json` to be compatible with `es2023` or ensure your build process correctly transpiles newer ECMAScript features.
• deprecated The specific package `mongodb-memory-server-global-4.0` has been removed as MongoDB 4.0 is no longer supported by the latest MongoDB driver.
  Fix: Migrate your tests and applications to use a newer MongoDB version (4.2.0 or higher) and the main `mongodb-memory-server-global` package.
• gotcha Binary download failures can occur due to network issues or incorrect proxy configurations. Recent versions include fixes for `USE_HTTP` requests.
  Fix: Ensure stable internet connectivity. If behind a proxy, configure `HTTP_PROXY` or `HTTPS_PROXY` environment variables. For specific issues, setting `MONGOMS_USE_HTTP=1` might resolve download problems caused by `http` module limitations in some environments.

Install

• npm install mongodb-memory-server-global npm
• yarn add mongodb-memory-server-global yarn
• pnpm add mongodb-memory-server-global pnpm

Imports

• MongoMemoryServer
  wrong:

  import { MongoMemoryServer } from 'mongodb-memory-server-global'

  correct:

  import { MongoMemoryServer } from 'mongodb-memory-server'

  The 'mongodb-memory-server-global' package primarily manages binary downloads. For programmatic control (starting/stopping the server), import `MongoMemoryServer` from the core `mongodb-memory-server` package.
• MongoMemoryReplSet
  wrong:

  const { MongoMemoryReplSet } = require('mongodb-memory-server-global')

  correct:

  import { MongoMemoryReplSet } from 'mongodb-memory-server'

  Similar to `MongoMemoryServer`, replication set functionality is exported by `mongodb-memory-server`. Use named imports for ESM environments, and `require` for CommonJS.
• start
  wrong:

  import * as MMS from 'mongodb-memory-server'

  correct:

  import { start } from 'mongodb-memory-server'

  For a simpler API to just start the server without explicit class instantiation, `start` is available as a named export from `mongodb-memory-server`. Avoid star imports unless necessary for specific legacy patterns.

Quickstart

Demonstrates starting an in-memory MongoDB instance, connecting with Mongoose, performing basic CRUD operations, and then cleaning up the connection and server. This setup implicitly relies on `mongodb-memory-server-global` having pre-downloaded the necessary binaries.

import { MongoMemoryServer } from 'mongodb-memory-server';
import mongoose from 'mongoose';

async function runInMemoryDbTest() {
  // mongodb-memory-server-global ensures binaries are available.
  // MongoMemoryServer handles the in-memory instance.
  const mongod = await MongoMemoryServer.create();
  const uri = mongod.getUri();

  console.log(`MongoDB Memory Server started at: ${uri}`);

  try {
    await mongoose.connect(uri);
    console.log('Mongoose connected to in-memory MongoDB');

    const UserSchema = new mongoose.Schema({ name: String, email: String });
    const User = mongoose.model('User', UserSchema);

    const newUser = await User.create({ name: 'Test User', email: 'test@example.com' });
    console.log('User created:', newUser);

    const foundUser = await User.findOne({ name: 'Test User' });
    console.log('User found:', foundUser);

  } catch (error) {
    console.error('Error during test:', error);
  } finally {
    await mongoose.disconnect();
    console.log('Mongoose disconnected.');
    await mongod.stop();
    console.log('MongoDB Memory Server stopped.');
  }
}

runInMemoryDbTest();