The MongoDB Node.js driver at version 7: three runtime dependencies and seven optional peers

The install footprint is three packages

The manifest for version 7.6.0 lists exactly three runtime dependencies.

  "dependencies": {
    "@mongodb-js/saslprep": "^1.5.0",
    "bson": "^7.3.2",
    "mongodb-connection-string-url": "^7.0.2"
  },

Each one has an obvious job. bson is the BSON serializer that turns JavaScript objects into the binary form the wire protocol requires, mongodb-connection-string-url is the parser behind MongoClient's URI handling, and saslprep is the string preparation step that SCRAM authentication needs for passwords containing non-ASCII characters. There is no ORM, no pooler and no HTTP client hiding in that list. A bare install gives you a client and nothing else, which is a deliberate design and also the reason people are surprised the first time they try to enable compression.

The package ships source alongside the build output. The files array includes lib, src, etc/prepare.js, mongodb.d.ts and tsconfig.json, and the types entry is mongodb.d.ts rather than a types subdirectory. Publishing the TypeScript sources means the type declarations and the implementation cannot drift apart, since the declarations are generated from the same files. It also means a debugger can step through the actual driver code when you need to understand a stack trace.

Every real feature is an optional peer dependency

Seven packages appear in peerDependencies, and every one of them is flagged optional in peerDependenciesMeta. The list is @aws-sdk/credential-providers at ^3.806.0, @mongodb-js/zstd at ^7.0.0, gcp-metadata at ^7.0.1, kerberos at ^7.0.0, mongodb-client-encryption at ^7.2.0, snappy at ^7.3.2 and socks at ^2.8.6. None of them install on their own.

This is the part of the design that has real consequences. zstd and snappy are compression codecs, so the README's compression story depends on you adding the codec package yourself. kerberos is the GSSAPI path, which matters for corporate LDAP shops. mongodb-client-encryption is the entire client side field level encryption feature, and gcp-metadata plus @aws-sdk/credential-providers are how the driver talks to Google and AWS KMS without forcing a cloud SDK on everybody. socks is the SOCKS5 proxy.

The README states the rule for the ecosystem around these packages, that only packages with versions in the supported ranges are stable when used in combination. The bson row of that compatibility table is the one to read first.

| [bson](https://www.npmjs.com/package/bson)                                           | ^1.0.0             | ^4.0.0             | ^5.0.0             | ^6.0.0          | ^6.0.0             | ^7.0.0        |

That row is also a versioning warning. bson 7 is paired with driver 7 only. Projects that pinned mongodb 4 and then upgraded the driver without touching their bson override are the source of a large share of the serialization bugs reported against this repository, because the two packages share a wire format and a class hierarchy.

Version 7.6.0 removes an old server and adds a proxy hook

The most recent release in this repository is v7.6.0, published on 2026-08-24 for a change date of 2026-08-21. Two of its notes matter for anyone still running an older deployment.

The first is a removal with a loud warning attached: support for MongoDB 4.2 is gone, and when the driver connects to a server of version 4.2 or less it throws an error rather than degrading. Note the mismatch with the README, which says the driver currently supports 4.4+ servers. The README describes the intended floor going forward, while the 7.6.0 note describes a hard failure at 4.2. There is a gap between those two statements, and if you are pinned on 4.4 the README is the more useful of the two because nothing will throw on you.

The second note is more useful day to day. Client side field level encryption can now route KMS requests through an HTTP proxy by setting kmsConnectCallback on ClientEncryption or on the auto encryption options. The callback receives the host and port and returns a connected socket, for example a tunnel opened with HTTP CONNECT, and the driver then performs the KMS TLS handshake over that socket using the provider's configured TLS options. The release notes are explicit about the gap this fills: the existing SOCKS5 proxyOptions does not cover HTTP forward proxies, so CSFLE and Queryable Encryption were unusable in environments that require one. If your key management traffic has to cross a corporate forward proxy, that callback is the supported way to do it rather than a wrapper library.

Explicit resource management stopped being experimental

The v7.4.0 release, dated 2026-06-25, promoted the async dispose methods on MongoClient, ClientSession, ChangeStream and cursors from experimental to stable. The reasoning given in the notes is external and worth repeating, because it explains why a database driver cares about a language proposal: TC39 Explicit Resource Management reached Stage 4 in 2025 and Node.js enabled it as a stable feature in Node.js 24. The experimental flags have been removed from the APIs.

The practical effect is that await using works on the connection lifecycle in a way the driver now considers supported rather than provisional. The optionality pattern that keeps this cheap to ship is the same one used across the whole manifest, where every package carries its own optional flag, so a feature that needs native code or a cloud SDK never lands in a default install.

The same release also changed a correctness detail that has no API surface at all. When a session has causal consistency enabled, write operations now include readConcern.afterClusterTime, matching what reads already did. That is the mechanism behind the read your own writes guarantee surviving a primary failover in sharded clusters, and until this release it held for reads but not for writes, which is the kind of asymmetry that only shows up during an incident.

Queryable Encryption text queries were renamed out of preview

The v7.5.0 release from 2026-07-07 promoted Queryable Encryption string queries to general availability for MongoDB 9.0, and the promotion came with renames rather than additions. TextOpts became StringOpts, the TextPreview algorithm became String, and the prefix, suffix and substring query types are now generally available. The three preview names, prefixPreview, suffixPreview and substringPreview, are deprecated with a stated intention of removal in a future release.

Code written against the preview names will keep running for now and will need editing eventually, so this is a good moment to grep for TextPreview and TextOpts before the removal lands rather than after. The capability underneath is worth understanding on its own terms: it allows exact and range style matching against encrypted fields, which was the hard part of encrypted search, since the server cannot compute over data it cannot read.

The same release tightened shutdown. Since v6.17.0, MongoClient.close() has eagerly closed checked out connections so in flight operations fail fast with a MongoClientClosedError instead of holding the client open, and v7.5.0 extends that behavior to all servers rather than a subset. For long lived processes this is a behavior change worth testing, because operations that used to finish during a shutdown may now be interrupted.

Bugs go to JIRA, releases are GPG signed

The support section of the README is unusual enough to be worth repeating, because it contradicts what most people expect from a GitHub project. Bug reports and feature requests go to jira.mongodb.org, under the NODE project, after creating an account. Reports filed in JIRA for the NODE, PYTHON, CSHARP and JAVA projects and the SERVER core project are public. The README also asks that you do not email the developers directly.

In practice this means GitHub Issues is not where a confirmed driver bug is tracked, and the issue count of 26 open issues on the repository should be read with that in mind rather than as the project's whole backlog.

Supply chain verification is documented in more detail than most drivers bother with. Releases are created automatically and signed with the Node team's GPG key, and the GitHub release contains a detached signature file named mongodb-X.Y.Z.tgz.sig next to the tarball.

gpg --import node-driver.asc

To check a package you pulled yourself, ask npm where the tarball is and verify it.

npm view [email protected] dist.tarball

gpg --verify mongodb-X.Y.Z.tgz.sig mongodb-X.Y.Z.tgz

One honest caveat from the README itself: no GPG verification happens when you install through npm, and the GitHub tarball and the npm tarball are identical in content. That is why the provenance attestation matters, since npm registry publishes carry one that cryptographically links the package to its source repository and build workflow.

npm audit signatures

The repository root carries a matching set of supply chain files, including sbom.json for a software bill of materials and THIRD-PARTY-NOTICES, alongside release-please-config.json and .release-please-manifest.json, which is the automation behind the release tags.

Editorial conclusion

Read package.json before you read the documentation site, because for this driver the manifest is where the decisions are. The runtime install is bson, saslprep and the connection string parser, which means compression, Kerberos, native TLS for client side encryption and SOCKS proxying are all things you opt into by name. Version 7 is where the interesting breakage lives: 7.6.0 refuses to connect to a server of version 4.2 or older and throws instead, 7.5.0 renamed the Queryable Encryption text API to a string API, and 7.4.0 turned await using into a supported path rather than an experimental flag. One more thing to keep in mind when triaging: bug reports go to jira.mongodb.org under the NODE project, not to GitHub Issues, so an issue filed in the wrong tracker can sit unread for months.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mongodb/node-mongodb-native on GitHub
3. Project website
4. README
5. Releases