MongoDB Memory Server Global 4.4

Common errors

• Error: MongoDB binary for version X.Y.Z is not supported on this platform.

  cause The specific MongoDB binary version you are trying to use (or the default set by a package) is not compatible with your operating system or CPU architecture, or it's a version that has been explicitly deprecated by `mongodb-memory-server`.
  fix Ensure your system is running a supported architecture (e.g., not an unsupported older macOS/ARM combination for very old MongoDB versions). If you are overriding the version, specify a supported version (e.g., `await MongoMemoryServer.create({ version: '4.4.0' })`). For this package, the version is fixed at 4.4.

• Error: MongoNetworkError: connect ECONNREFUSED 127.0.0.1:xxxxx

  cause The MongoDB Memory Server instance failed to start correctly, crashed, or was stopped before the client attempted to connect. This can be due to port conflicts, insufficient permissions, or issues with the downloaded binary.
  fix Verify that no other process is using the allocated port (the server tries to find a free port automatically, but conflicts can occur). Check the console output for any error messages during `MongoMemoryServer.create()`. Ensure you are awaiting `create()` before attempting to connect a client. Consider adding `await mongoServer.stop()` in a `finally` block or `afterAll` hook to prevent resource leaks.

• TypeError: Cannot read properties of undefined (reading 'connect')

  cause This typically occurs when trying to use a MongoDB client (like `MongoClient` or `mongoose`) before the `mongoUri` is properly obtained from a *successfully started* `MongoMemoryServer` instance.
  fix Ensure that `MongoMemoryServer.create()` successfully resolves and that `mongoServer.getUri()` is called *after* the server is confirmed to be running. Always handle potential errors from `create()` and subsequent operations.

Warnings

• breaking mongodb-memory-server-global-4.4 version 11.0.0 and above requires Node.js version 20.19.0 or higher. Older Node.js environments are no longer supported.
  Fix: Upgrade your Node.js runtime to version 20.19.0 or newer. Check your `package.json` engines field and CI/CD environments.
• breaking When compiling TypeScript, `mongodb-memory-server-global-4.4` version 11.0.0 upgrades its internal `tsconfig` target to `es2023`. This might cause compilation issues if your project's `tsconfig.json` targets an older ES version or has incompatible settings.
  Fix: Ensure your project's `tsconfig.json` is compatible with `es2023` or newer. You might need to update your TypeScript compiler version or adjust your project's `target` setting.
• gotcha While this specific package (`-global-4.4`) is designed for MongoDB 4.4, the underlying `mongodb-memory-server` library (from which this package re-exports) dropped support for MongoDB versions below 4.2.0 in v11.0.0. Attempting to manually configure this package to an unsupported older MongoDB version will fail.
  Fix: If you need an older MongoDB version for testing, you must use an older version of `mongodb-memory-server` or one of its global packages that supports it. For version 4.4, this package is suitable, but do not try to configure it to <4.2.
• deprecated The separate package `mongodb-memory-server-global-4.0` was removed in the v11.0.0 release of the `mongodb-memory-server` ecosystem, as it is no longer supported by the latest MongoDB drivers. Users of that package should upgrade.
  Fix: Migrate your tests to use `mongodb-memory-server-global-4.4` or a newer `mongodb-memory-server-global-` package to maintain compatibility with modern MongoDB drivers and Node.js versions.

Install

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

Imports

• MongoMemoryServer
  wrong:

  import MongoMemoryServer from 'mongodb-memory-server-global-4.4';

  correct:

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

  MongoMemoryServer is a named export, not a default export. This package re-exports the main class pre-configured for MongoDB 4.4.
• MongoMemoryServer
  wrong:

  import { MongoMemoryServer } from 'mongodb-memory-server-global-4.4'; // in CommonJS

  correct:

  const { MongoMemoryServer } = require('mongodb-memory-server-global-4.4');

  While CommonJS `require` is supported, ESM `import` syntax is recommended for newer Node.js versions (>=20.19.0) and TypeScript projects.
• MongoMemoryServer.create()
  wrong:

  const mongo = new MongoMemoryServer();
  await mongo.start();

  correct:

  const mongo = await MongoMemoryServer.create();

  The static `create()` method is the recommended asynchronous factory for initializing and starting the server, handling binary download and setup internally.

Quickstart

Demonstrates how to start an in-memory MongoDB 4.4 server, connect a native MongoDB client, perform a basic database operation, and then properly shut down both the client and the server.

import { MongoMemoryServer } from 'mongodb-memory-server-global-4.4';
import { MongoClient } from 'mongodb';

async function runTestDatabase() {
  let mongoServer: MongoMemoryServer | null = null;
  let client: MongoClient | null = null;
  try {
    // Start a new in-memory MongoDB server configured for 4.4
    mongoServer = await MongoMemoryServer.create();
    const mongoUri = mongoServer.getUri();
    console.log(`MongoDB Memory Server started at: ${mongoUri}`);

    // Connect a MongoDB client to the in-memory server
    client = new MongoClient(mongoUri);
    await client.connect();
    console.log('MongoDB client connected successfully.');

    // Perform some database operations
    const db = client.db('testdb');
    const collection = db.collection('documents');
    await collection.insertOne({ name: 'Test Document', value: 1 });
    const docs = await collection.find({}).toArray();
    console.log('Inserted and found documents:', docs);

  } catch (error) {
    console.error('Error during test database operations:', error);
  } finally {
    // Ensure the client and server are always stopped
    if (client) {
      await client.close();
      console.log('MongoDB client closed.');
    }
    if (mongoServer) {
      await mongoServer.stop();
      console.log('MongoDB Memory Server stopped.');
    }
  }
}

runTestDatabase();