mongodb-memory-server-percona

Drop-in replacement for mongodb-memory-server that runs Percona Server for MongoDB with the open-source inMemory storage engine.

The MongoDB Community downloader in mongodb-memory-server does not work with Percona binaries (different URL layout, no archive index, and Percona's tarball ships ABI-incompatible libldap-2.5 / libssl 3.0 against modern Ubuntu). This package handles the full pipeline: download Percona, stage libldap from Ubuntu's archive, write a wrapper that fixes LD_LIBRARY_PATH, then hand the wrapper to mongodb-memory-server-core as systemBinary.

Why Percona inMemory

MongoDB Community 7.0+ removed ephemeralForTest and only ships wiredTiger — which is journaled, on-disk, and ~10× slower to boot than the old in-memory engine. MongoDB's official inMemory engine is Enterprise-only.

Percona Server for MongoDB ships an open-source inMemory engine that keeps the dataset entirely in RAM (no journal, no checkpoint, no disk files). For test workloads, it beats Percona WiredTiger on writes by 10–40% and is on par for reads.

Install

npm install --save-dev mongodb-memory-server-percona
# Stage the Percona binary into ~/.cache/mongodb-memory-server-percona/
npx mongodb-memory-server-percona-fetch

The fetch step downloads ~150 MB compressed (~440 MB on disk) and is cached across projects. It runs once per machine per Percona version. MongoMemoryServer.create() will auto-fetch on first use unless you pass autoFetch: false.

Currently supports linux/x64 only (this is what Percona publishes binary tarballs for).

Usage

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

const server = await MongoMemoryServer.create();
const uri = server.getUri();
// ... use the URI with mongoose / mongodb driver ...
await server.stop();

The API matches mongodb-memory-server's MongoMemoryServer.create() exactly. Defaults: Percona 8.0.20-8 with storageEngine: 'inMemory'.

Options

await MongoMemoryServer.create({
  perconaVersion: '8.0.20-8',           // or '7.0.12-7'
  perconaCacheDir: '/tmp/percona',      // default ~/.cache/mongodb-memory-server-percona
  autoFetch: true,                      // download if missing (default true)
  // Plus everything mongodb-memory-server-core accepts:
  instance: { dbName: 'mydb', port: 27017 },
  binary: { /* systemBinary, version, etc. */ },
});

Environment variables

| Var | What it does | |-----|--------------| | PSMDB_VERSION | Percona version (default 8.0.20-8) | | PSMDB_FLAVOR | Tarball flavor: bookworm-minimal (8.x default), glibc2.35-minimal (7.x), jammy-minimal | | PSMDB_BASE_URL | Override download host (e.g. point at an internal minio mirror) | | PSMDB_LIBLDAP_DEB_URL | Override the libldap-2.5 .deb URL | | MONGO_MEMORY_SERVER_PERCONA_CACHE | Override the binary cache directory |

Mirroring with minio / S3 / internal CDN

The package downloads from https://downloads.percona.com/downloads/... by default. To serve the same tarballs from a local mirror, mirror this prefix and set PSMDB_BASE_URL:

# Mirror once (anywhere with internet access):
mc cp \
  https://downloads.percona.com/downloads/percona-server-mongodb-8.0/percona-server-mongodb-8.0.20-8/binary/tarball/percona-server-mongodb-8.0.20-8-x86_64.bookworm-minimal.tar.gz \
  myminio/percona/percona-server-mongodb-8.0/percona-server-mongodb-8.0.20-8/binary/tarball/

# Then in CI:
export PSMDB_BASE_URL=https://minio.internal.example.com/percona

Path layout below PSMDB_BASE_URL is identical to downloads.percona.com/downloads. Same trick works for PSMDB_LIBLDAP_DEB_URL.

Vitest integration

A complete fixture-based example lives in examples/vitest-mongoose/. Drop-in for the mongodb-memory-server-global import in your globalSetup.ts:

// testutils/globalSetup.ts
import { MongoMemoryServer } from 'mongodb-memory-server-percona';

export async function setup() {
  globalThis.__MONGOD__ = await MongoMemoryServer.create();
  // ... write URI to globalConfig.json as before ...
}

export async function teardown() {
  await globalThis.__MONGOD__?.stop();
}

testutils/vitestEnvironment.ts, connectMongoose, clearDbAndRestartCounters, etc. don't need any changes — they just see a regular MongoDB URI.

Logging / debugging mongod

Percona's mongod is quiet by default. Three layers of verbosity:

# 1. Logs from mongodb-memory-server (binary resolution, instance lifecycle).
DEBUG=MongoMS:* npm test

# 2. mongod's own logs (passed straight through). Stack -v up to 5 times.

await MongoMemoryServer.create({
  instance: {
    args: ['-v', '-v'],          // verbose mongod, ~debug-1
    // or specific components:
    // args: ['--setParameter', 'logComponentVerbosity={query:{verbosity:2}}'],
  },
});

// 3. mongodb-memory-server-core can pipe mongod stdout/stderr to console:
await MongoMemoryServer.create({
  instance: {
    args: ['-v', '-v'],
  },
  // any string keys core supports go here; e.g. for replicaset variants:
  // launchMode: 'spawn',
});

For the staging download itself, the package logs [mongodb-memory-server-percona] fetching ... to stdout. Pass a custom logger to fetchPercona({ log }) to redirect it.

Behind a feature flag

import { MongoMemoryServer as PerconaMMS } from 'mongodb-memory-server-percona';
import { MongoMemoryServer as CommunityMMS } from 'mongodb-memory-server-global';

const MMS = process.env.USE_PERCONA === 'true' ? PerconaMMS : CommunityMMS;
const mongod = await MMS.create({ /* ... */ });

Why upstream mongodb-memory-server doesn't ship this

Tracked in typegoose/mongodb-memory-server#742. Maintainer is open to a PR but won't add it himself. The blockers:

1. URL layout mismatch. MMS's downloader hard-codes fastdl.mongodb.org's flat path scheme and reads MongoDB's "Releases archive" page to enumerate versions. Percona's path is deeper (/downloads/percona-server-mongodb-8.0/percona-server-mongodb-8.0.20-8/binary/tarball/...) and there is no equivalent index.
2. SYSTEM_BINARY is the official workaround, but MMS runs mongod --version on the binary on startup. On Ubuntu 24.04+ this fails: Percona links against libldap-2.5 (Ubuntu 24.04+ ships openldap 2.6, ABI-incompatible) and bundles libssl 3.0 (system libcurl wants 3.2 symbols). mongod exits without stdout and MMS used to crash on stdout.toString(). Fixed in 10.1.3-beta.1 with absolute-path normalization + a SYSTEM_BINARY_VERSION_CHECK=false escape hatch — but the underlying loader breakage was never fixed upstream.
3. inMemory is not a Community storage engine. MMS's StorageEngine union doesn't list it, so passing storageEngine: 'inMemory' requires a TypeScript cast.

This package fixes all three: stages the right tarball, copies libldap-2.5 / liblber-2.5 from Ubuntu jammy's archive into lib/private/, hides the bundled libssl on hosts with newer system OpenSSL, generates a mongod-wrapper.sh that sets LD_LIBRARY_PATH, and feeds the wrapper to systemBinary.

Sizes (compressed download)

| | Download | Disk | |---|---|---| | Percona 8.0.20-8 (bookworm-minimal) | 158 MB | ~440 MB | | Percona 7.0.12-7 (glibc2.35-minimal) | 131 MB | ~440 MB | | MongoDB 8.0.4 community | 95 MB | ~210 MB | | MongoDB 7.0.14 community | 80 MB | ~210 MB |

Percona is roughly 2× the size of community MongoDB because it bundles enterprise-style crypto/auth deps (LDAP, SASL, Kerberos).

License

MIT.