mongodb

6.19.0 (2025-08-26)

The MongoDB Node.js team is pleased to announce version 6.19.0 of the mongodb package!

Release Notes

Experimental Support for Queryable Encryption Text Field Prefix, Suffix and Substring Queries

When using Queryable Encryption with both automatic encryption and explicit encryption, text fields can now be queried using prefix, suffix and substring queries. This feature requires mongodb-client-encryption@>=6.5.0.

Allow a secureContext for Auto Encryption and Client Encryption TLS options

This can be provided in the tlsOptions option both both objects.

import * as tls from 'tls';
import { ClientEncryption, MongoClient } from 'mongodb';

const caFile = await fs.readFile(process.env.CSFLE_TLS_CA_FILE);
const certFile = await fs.readFile(process.env.CSFLE_TLS_CLIENT_CERT_FILE);
const secureContextOptions = {
  ca: caFile,
  key: certFile,
  cert: certFile
};
const options = {
  keyVaultNamespace: 'db.coll',
  kmsProviders: {
    aws: {}
    }
  },
  tlsOptions: {
    aws: {
      secureContext: tls.createSecureContext(secureContextOptions),
    }
  }
};

const client = this.configuration.newClient({}, { autoEncryption: { ...options, schemaMap } });
const clientEncryption = new ClientEncryption(client, options);

collection.findOne() and collection.find() will no longer potentially leave open cursors on the server

The findOne command will now always set the limit option to 1 and singleBatch to true. The limit, noCursorResponse and batchSize options have also been deprecated, and the command will guarantee no more cursors can be orphaned and no killCursors command will be potentially executed.

find will now set limit to batchSize + 1 when both options were equal, to avoid leaving cursors open.

Clients no longer send a ping on connect

When authentication is enabled, the MongoClient will no longer send a ping command when connecting since it is unnecessary. Instead it will check a connection out of the pool to force the initial handshake, and check it back in.

Features

• NODE-4179: allow secureContext in KMS TLS options (#4578) (0ea6eaa)
• NODE-6472: findOne and find no longer keep open cursors (#4580) (be7f808)
• NODE-7020: remove ping on connect (#4607) (3d296b7)
• NODE-7059, NODE-7008: add support for text queries for QE string fields (#4597) (e4492f3)

Documentation

• Reference
• API
• Changelog

We invite you to try the mongodb library immediately, and report any issues to the NODE project.

6.18.0 (2025-07-22)

The MongoDB Node.js team is pleased to announce version 6.18.0 of the mongodb package!

Release Notes

New appendMetadata API allows clients to add handshake metadata post construction

Driver information such as name, version, and platform are allowed:

import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URI);
client.appendMetadata({ name: 'my library', version: '1.0', platform: 'NodeJS' });

Cursors lazily instantiate sessions

In previous versions, sessions were eagerly allocated whenever a cursor was created, regardless of whether or not a cursor was actually iterated (and the session was actually needed). Some driver APIs (FindCursor.count(), AggregationCursor.explain() and FindCursor.explain()) don't actually iterate the cursor they are executed on. This can lead to client sessions being created and never being cleaned up.

With this update, sessions are not allocated until the cursor is iterated.

Idle connections are now pruned during periods of no activity even when minPoolSize=0

A MongoClient configured with a maxIdleTimeMS and minPoolSize of 0 is advantageous for workloads that have sustained periods of little or no activity because it allows the connection pool to close connections that are unused during these periods of inactivity. However, due to a bug in the ConnectionPool implementation, idle / perished connections were not cleaned up unless minPoolSize was non-zero.

With the changes in this PR, the ConnectionPool now always cleans up idle connections, regardless of minPoolSize.

ChangeStream event interfaces include a wallTime property

This property is available on all types with the exception of reshard collection and refine collection shard key events. Thanks to @qhello for bringing this bug to our attention!

CommandSucceededEvent and CommandFailedEvent events now have a databaseName property

CommandSucceededEvent and CommandFailedEvent now include the name of the database against which the command was executed.

Deprecations

Transaction state getters are deprecated

These were for internal use only and include:

Transaction#options
Transaction#recoveryToken
Transaction#isPinned
Transaction#isStarting
Transaction#isActive
Transaction#isCommitted

ClientMetadata, ClientMetadataOptions, and CancellationToken have been deprecated

These types will be removed in an upcoming major version of the driver.

CommandOptions.noResponse is deprecated

[!CAUTION] noResponse is not intended for use outside of MongoClient.close(). Do not use this option.

The Node driver has historically supported an option, noResponse, that is used internally when a MongoClient is closed. This option was accidentally public. This option will be removed in an upcoming major release.

Features

• NODE-5055: Add databaseName property to command monitoring events (#4586) (3faf0c9)
• NODE-7009: add client metadata on demand (#4574) (b9636ee)
• NODE-7053: deprecate noResponse option (#4589) (1115319)
• NODE-6865: deprecate transaction getters (#4567) (da46aea)
• NODE-6991: deprecate unintentionally public client metadata types (#4566) (ca6554b)

Bug Fixes

• NODE-4845: allocate sessions lazily in cursors (#4575) (5761703)
• NODE-6589: background task does not prune idle connections when minPoolSize=0 (#4569) (7cbb641)
• NODE-6955: add missing wallTime property TS change stream event interfaces (#4541) (f153c6f)

Documentation

• Reference
• API
• Changelog

We invite you to try the mongodb library immediately, and report any issues to the NODE project.

6.17.0 (2025-06-03)

The MongoDB Node.js team is pleased to announce version 6.17.0 of the mongodb package!

Release Notes

Support for MongoDB 4.0 is removed

[!WARNING] When the driver connects to a MongoDB server of version 4.0 or less, it will now throw an error.

OIDC machine workflows now retry on token expired errors during initial authentication

This resolves issues of a cached OIDC token in the driver causing initial authentication to fail when the token had expired. The affected environments were "azure", "gcp", and "k8s".

keepAliveInitialDelay may now be configured at the MongoClient level

When not present will default to 120 seconds. The option value must be specified in milliseconds.

import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URI, { keepAliveInitialDelay: 100000 });

updateOne and replaceOne now support a sort option

The updateOne and replaceOne operations in each of the ways they can be performed support a sort option starting in MongoDB 8.0. The driver now supports the sort option the same way it does for find or findOneAndModify-style commands:

const sort = { fieldName: -1 };

collection.updateOne({}, {}, { sort });
collection.replaceOne({}, {}, { sort }); 

collection.bulkWrite([ 
  { updateOne: { filter: {}, update: {}, sort } },
  { replaceOne: { filter: {}, replacement: {}, sort } },
]);

client.bulkWrite([
  { name: 'updateOne', namespace: 'db.test', filter: {}, update: {}, sort },
  { name: 'replaceOne', namespace: 'db.test', filter: {}, replacement: {}, sort }
]);

MongoClient close shuts outstanding in-use connections

The MongoClient.close() method now shuts connections that are in-use allowing the event loop to close if the only remaining resource was the MongoClient.

Support Added for Configuring the DEK cache expiration time.

Default value is 60000. Requires using mongodb-client-encryption >= 6.4.0

For ClientEncryption:

import { MongoClient, ClientEncryption } from 'mongodb';
const client = new MongoClient(process.env.MONGODB_URI);
const clientEncryption = new ClientEncryption(client, { keyExpirationMS: 100000, kmsProviders: ... });

For auto encryption:

import { MongoClient, ClientEncryption } from 'mongodb';
const client = new MongoClient(process.env.MONGODB_URI, {
  autoEncryption: {
    keyExpirationMS: 100000,
    kmsProviders: ...
  }
});

Update operations will now throw if ignoreUndefined is true and all operations are undefined.

When using any of the following operations they will now throw if all atomic operations in the update are undefined and the ignoreUndefined option is true. This is to avoid accidental replacement of the entire document with an empty document. Examples of this scenario:

import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URI);

client.bulkWrite(
  [
    {
      name: 'updateMany',
      namespace: 'foo.bar',
      filter: { age: { $lte: 5 } },
      update: { $set: undefined, $unset: undefined }
    }
  ],
  { ignoreUndefined: true }
);

const collection = client.db('test').collection('test');

collection.bulkWrite(
  [
    {
      updateMany: {
        filter: { age: { $lte: 5 } },
        update: { $set: undefined, $unset: undefined }
      }
    }
  ],
  { ignoreUndefined: true }
);

collection.findOneAndUpdate(
  { a: 1 },
  { $set: undefined, $unset: undefined },
  { ignoreUndefined: true }
);

collection.updateOne({ a: 1 }, { $set: undefined, $unset: undefined }, { ignoreUndefined: true });

collection.updateMany({ a: 1 }, { $set: undefined, $unset: undefined }, { ignoreUndefined: true });

Socket errors are always treated as network errors

Network errors perform an important role in the driver, impacting topology monitoring processes and retryablity. A bug in the driver's socket implementation meant that in scenarios where server disconnects occurred while no operation was in progress on the socket resulted in errors that were not considered network errors.

Socket errors are now unconditionally treated as network errors.

Features

• NODE-6245: add keepAliveInitialDelay config (#4510) (d6c0eb3)
• NODE-6290: add sort support to updateOne and replaceOne (#4515) (28857b7)
• NODE-6882: eagerly close checked out connections when client is closed (#4499) (64fdb3e)
• NODE-6884: remove support for 4.0 (#4534) (6fe6ccc)
• NODE-6952: support configuring DEK cache expiration (#4538) (c529f07)
• NODE-6963: use BSON 6.10.4 (#4549) (aee490a)

Bug Fixes

• NODE-6638: throw if all atomic updates are undefined (#4519) (9625b2d)
• NODE-6864: socket errors are not always converted to MongoNetworkErrors (#4473) (2d86095)
• NODE-6962: OIDC machine workflows use OIDCCallbacks internally (#4546) (bd6030f)

Documentation

• Reference
• API
• Changelog

We invite you to try the mongodb library immediately, and report any issues to the NODE project.