Skip to content

Requirements

Jump to bottom
Antonio Membrides Espinosa edited this page Jul 15, 2026 · 3 revisions

Requirements for QE: Node.js Migration Guide

Executive decision

  • For a long-term app, migrate the stack to the current 7.x Node.js driver line instead of freezing on 6.x. The current public docs are for Node.js Driver v7.x, while QE text preview support already exists in late 6.x starting at mongodb 6.19.0 plus mongodb-client-encryption 6.5.0.
  • Keep node:22-slim. Node.js driver 6.11 to 6.20 explicitly supports Node.js 22, and v7 removes only Node 16 and Node 18, which fits your current runtime direction.
  • Treat QE substring, prefix, and suffix as preview-only features. The server docs say they are public preview, should not be enabled in production, and the future GA behavior will be incompatible with the preview behavior.

What your current stack can and cannot do

  • Your current package pair, mongodb ^6.5.0 and mongodb-client-encryption ^6.0.1, is not sufficient for QE substring, prefix, and suffix support in Node.js.
  • The minimum late-6.x baseline for those QE text features is mongodb >= 6.19.0 and mongodb-client-encryption >= 6.5.0.
  • Atlas 8.3.5 is a suitable server side target for the app because the current 8.3 QE docs still document substring, prefix, and suffix as supported preview capabilities introduced in 8.2.

Minimum versions required for QE features

Practical matrix for your app

Feature Minimum on 6.x line Minimum on 7.x line Server floor
Queryable Encryption base compatibility mongodb >= 6.0.0 with mongodb-client-encryption >= 6.0.0 on matching major versions mongodb >= 7.0.0 with mongodb-client-encryption >= 7.0.0 because v7 updates the peer dependency to mongodb-client-encryption@7.0.0 QE feature family depends on the server capability you use
QE range queries mongodb >= 6.10.0 and mongodb-client-encryption >= 6.1.0 mongodb >= 7.0.0 and mongodb-client-encryption >= 7.0.0 as the minimum supported pair on the 7.x line. The range feature already existed before v7, so no higher 7.x floor is documented for it MongoDB Server >= 8.0
QE substring, prefix, suffix preview mongodb >= 6.19.0 and mongodb-client-encryption >= 6.5.0 mongodb >= 7.0.0 and mongodb-client-encryption >= 7.0.0 as the minimum supported pair on the 7.x line. These text features were already introduced in 6.19, so the 7.x floor is the branch floor, not a newer feature floor Preview capability documented for MongoDB Server >= 8.2

Interpretation

  • If you need the absolute minimum viable v6 stack for your app, use mongodb 6.19.x+ and mongodb-client-encryption 6.5.x+ to cover both QE range and QE substring, prefix, suffix preview on Atlas 8.3.5.
  • If you migrate to v7, the safest minimum branch floor is mongodb 7.0.0+ with mongodb-client-encryption 7.0.0+, but for operational reasons it is still better to pin to a recent tested 7.x pair rather than the first 7.0 build.
  • Range is production supported, while substring, prefix, and suffix remain preview in the server documentation for the 8.2 and 8.3 era behavior used by this app.

Fallback recommendation if migration to 7.x is blocked

Use this package floor as the v6 fallback target:

{
  "dependencies": {
    "mongodb": "^6.19.0",
    "mongodb-client-encryption": "^6.5.0"
  }
}

This fallback preserves all QE features relevant to your app:

  • equality
  • range
  • substring, prefix, suffix preview

Recommended long-term target

  • Runtime: node:22-slim.
  • Atlas: 8.3.5.
  • Driver line: mongodb 7.x, current public line.
  • Encryption package line: mongodb-client-encryption 7.x, same major as the driver.
  • Version pinning rule: validate and pin a tested 7.x pair together. As current references, the public upgrade docs use mongodb@7.4, and the current repository metadata shows driver 7.5.0 with peer dependency mongodb-client-encryption ^7.2.0 on the active branch.
{
  "engines": {
    "node": ">=22"
  },
  "dependencies": {
    "mongodb": "^7.4.0",
    "mongodb-client-encryption": "^7.2.0"
  }
}

Why 7.x is the right target for a long-term app

  • v7 is the current documentation and upgrade path, so it is the better baseline for an app that you plan to keep refreshed over time.
  • MongoDB does not publish a public per-driver LTS or EOL schedule for driver branches. Internal driver policy discussion explicitly states that there is no public support and EOL policy document for drivers.
  • The same internal discussion describes an internal policy target of supporting at most two major versions at a time, with bug fixes and patches backported from the current major to the previous major for one year after a new major release, and no feature backports.
  • In practice, that means v7 is the closest thing to the stable current line, while v6 is mature but should be treated as a transitional branch for this app, not the destination state.

Implementation target

Goal

Upgrade the app from the current 6.x dependency set to a 7.x dependency set while preserving QE support and enabling substring, prefix, and suffix app flows.

Non-goals

  • Do not redesign the QE app flow unless required by driver breakage.
  • Do not present substring, prefix, or suffix as production-ready features.

Migration checklist from v6 to v7

1. Upgrade package majors in lockstep

  • Change mongodb from 6.x to 7.x.
  • Change mongodb-client-encryption from 6.x to 7.x in the same change set. The v7 upgrade guide explicitly moves the peer dependency to mongodb-client-encryption@7.0.0.
  • Keep driver and encryption package on the same major. The v6 guide already enforced matching major versions, and v7 continues that alignment pattern through the peer dependency matrix.

2. Keep the QE-specific feature expectations clear

  • QE substring, prefix, and suffix support in Node.js first arrived in driver v6.19 and requires mongodb-client-encryption 6.5 or later. Upgrading to 7.x is about long-term maintainability, not about unlocking a newer minimum for the feature itself.
  • The server side feature is still documented as preview in current QE docs, so plan for future adjustments when GA lands.

3. Fix imports if your code still uses the pre-v6 pattern

  • In Node.js driver v6 and later, ClientEncryption should be imported from mongodb, not from mongodb-client-encryption.
import { MongoClient, ClientEncryption } from "mongodb";

4. Remove deprecated client options that v7 no longer wants around

  • Remove useNewUrlParser if it is still present.
  • Remove useUnifiedTopology if it is still present.
  • Remove any leftover deprecated SSL-prefixed configuration if it survived prior migrations, and prefer TLS-prefixed options or secureContext patterns already required by modern driver behavior.
const client = new MongoClient(uri, {
  autoEncryption: autoEncryptionOptions
});

5. Review AWS authentication only if your app uses it

  • If the app uses MONGODB-AWS, v7 now requires @aws-sdk/credential-providers and no longer supports the old URI-encoded AWS credential style in the connection string.
  • If your app does not use AWS auth, this item is irrelevant and can be skipped.

6. Set batchSize explicitly where you care about cursor behavior

  • v7 removes the old default cursor batchSize of 1000. If any app path depends on that behavior for memory, latency, or output pacing, set it explicitly.
const cursor = collection.find(query).batchSize(100);

7. Replace cursor or change stream transform usage if present

  • v7 removes support for transform functions passed into cursor and change stream streams. Replace stream({ transform: fn }) with stream().map(fn).
const stream = cursor.stream().map(JSON.stringify);

8. Update peer and optional dependency expectations

  • v7 updates peer dependency ranges for @mongodb-js/zstd, kerberos, and related packages.
  • If your app does not use compression, Kerberos, or AWS auth, you can avoid adding extra packages beyond mongodb-client-encryption.
  • If you do use Zstandard compression, update that package to a 7.x-compatible line as part of the same change set.

9. Recheck encryption error handling

  • v7 normalizes encryption errors so they subclass MongoError, and one crypto connection error path changes to MongoRuntimeError instead of MissingDependencyError.
  • If your app prints or pattern-matches error names, update those checks to target the stable error hierarchy rather than old string comparisons.

10. Keep the Docker image, but rebuild native dependencies cleanly

  • Your node:22-slim base image is a reasonable long-term choice for this app direction because your runtime is already on a modern supported line, and the v7 branch is explicitly dropping only Node 16 and 18.
  • After changing package majors, force a clean reinstall so the native encryption bindings are rebuilt against the new dependency graph.
FROM node:22-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

CMD ["node", "index.js"]

Search and patch plan

Run a targeted search over the repo for the following patterns and patch each result deliberately:

  • mongodb-client-encryption import sites for ClientEncryption.
  • useNewUrlParser.
  • useUnifiedTopology.
  • stream({ transform: or equivalent cursor transform usage.
  • authMechanism=MONGODB-AWS if applicable.
  • Any explicit dependency pins to mongodb 6.x or mongodb-client-encryption 6.x.
  • Any error handling that assumes old encryption error classes or names.

Minimal package diff

 "dependencies": {
-  "mongodb": "^6.5.0",
-  "mongodb-client-encryption": "^6.0.1"
+  "mongodb": "^7.4.0",
+  "mongodb-client-encryption": "^7.2.0"
 }

Validation checklist after migration

  • The app starts successfully in node:22-slim and connects to Atlas 8.3.5.
  • Automatic encryption initializes successfully with the 7.x dependency pair.
  • A QE-enabled collection can be created or reused with your existing key management flow.
  • Equality and range flows still work after the package upgrade.
  • Prefix query returns expected matches on encrypted data.
  • Suffix query returns expected matches on encrypted data.
  • Substring query returns expected matches on encrypted data.
  • App copy and comments clearly label these text features as preview and not production-ready.

Final recommendation

Migrate now to a validated 7.x pair and keep the rest of the app architecture stable. For your use case, v7 is the better long-term foundation, while the QE text capability requirement itself is already satisfied by late 6.x and therefore should not be the only reason to upgrade. The real reasons to upgrade are lifecycle alignment, current-doc alignment, and lower maintenance cost for a app you intend to keep current over time.

Sources

Clone this wiki locally