Docs Home → Node.js

Upgrade Driver Versions升级驱动程序版本

On this page本页内容

Overview概述

On this page, you can learn about any changes you might need to make to your application to upgrade your driver to a new version without loss of functionality.在此页面上，您可以了解可能需要对应用程序进行的任何更改，以便在不丢失功能的情况下将驱动程序升级到新版本。

Before you upgrade, perform the following actions:升级之前，请执行以下操作：

  • Ensure the new driver version is compatible with the MongoDB Server version your application connects to and the version of Node.js that your application runs on. 确保新的驱动程序版本与应用程序连接的MongoDB Server版本以及应用程序运行的Node.js版本兼容。See the Compatibility page for this information.有关此信息，请参阅兼容性页面。
  • Address any breaking changes between the version of the driver your application currently uses and your planned upgrade version in the Breaking Changes section of this guide. 在本指南的中断更改部分中，解决应用程序当前使用的驱动程序版本与计划升级版本之间的任何中断更改。To learn more about the MongoDB Server release compatibility changes, see the Server Release Compatibility Changes section.要了解有关MongoDB Server版本兼容性更改的更多信息，请参阅服务器版本兼容性更改部分。
Tip

You can minimize the amount of changes that you need to make to your application when upgrading driver versions by using the Stable API.使用Stable API升级驱动程序版本时，您可以最大限度地减少需要对应用程序进行的更改。

Breaking Changes中断更改

A breaking change is a modification in a convention or behavior in a specific version of the driver that may prevent your application from working as expected.破坏性更改是对特定版本的驱动程序中的约定或行为的修改，可能会阻止应用程序按预期工作。

The breaking changes in this section are categorized by the major version releases that introduced them. When upgrading driver versions, address all the breaking changes between your current version and the planned upgrade version. 本节中的突破性更改按引入它们的主要版本进行了分类。升级驱动程序版本时，请解决当前版本和计划升级版本之间的所有中断更改。For example, if you are upgrading the driver from v3.x to v5.x, address all breaking changes listed under v4.x and v5.x.例如，如果您要将驱动程序从v3x升级到v5x，请解决v4x和v5x下列出的所有中断更改。

Version 5.x Breaking Changes版本5.x突破性更改

  • Driver versions 5.x are not compatible with Node.js v12 or earlier. 驱动程序版本5.x与Node.js v12或更早版本不兼容。If you want to use this version of the driver, you must use Node.js v14.20.1 or greater.如果你想使用这个版本的驱动程序，你必须使用Node.js v14.20.1或更高版本。
  • The driver removes support for callbacks in favor of a promise-based API. 驱动程序取消了对回调的支持，转而支持基于promise-based的API。The following list provides some strategies for callback users to adopt this version:以下列表为回调用户提供了一些采用此版本的策略：

    • Migrate to the promise-based API (recommended)迁移到基于承诺的API（推荐）
    • Use the promise-based API and 使用基于承诺的API和util.callbackify
    • Add mongodb-legacy to continue using callbacks添加mongodb-legacy以继续使用回调

    For more information about these strategies, see the v5.0 changelog.有关这些策略的更多信息，请参阅v5.0变更日志。

  • The driver removes support for the Collection.insert(), Collection.update(), and Collection.remove() helper methods. The following list provides instructions on how to replace the functionality of the removed methods:该驱动程序删除了对Collection.insert()、Collection.update()和Collection.remove()辅助方法的支持。以下列表提供了有关如何替换已删除方法的功能的说明：

    • Migrate from Collection.insert() to insertOne() or insertMany()从Collection.insert()迁移到insertOne()或insertMany()
    • Migrate from Collection.update() to updateOne() or updateMany()从Collection.update()迁移到updateOne()或updateMany()
    • Migrate from Collection.remove() to deleteOne() or deleteMany()从Collection.remove()迁移到deleteOne()或deleteMany()
  • The driver no longer includes AWS SDK modules by default.默认情况下，驱动程序不再包含AWS SDK模块。
  • The driver no longer automatically imports the bson-ext package.驱动程序不再自动导入bson-ext包。
  • The driver removes support for custom Promise libraries. 该驱动程序删除了对自定义Promise库的支持。The driver no longer supports the promiseLibrary option of MongoClient and the Promise.set export that allows specifying a custom Promise library.该驱动程序不再支持MongoClient的promiseLibrary选项和允许指定自定义Promise库的Promise.set导出。
  • The driver removes support for the Collection.mapReduce() helper.该驱动程序删除了对Collection.mapReduce()帮助程序的支持。
  • The BulkWriteResult type no longer has the publicly enumerable result property.BulkWriteResult类型不再具有可公开枚举的result属性。
  • The following types, options, and methods have been removed:已删除以下类型、选项和方法：

    • BulkResult.lastOp() method方法
    • opTime property of BulkResultBulkResult的opTime属性
    • BulkWriteOptions.keepGoing option选项
    • WriteConcernError.err() method方法
    • AddUserOptions.digestPassword option
    • Kerberos gssapiCanonicalizeHostName optionKerberosgssapiCanonicalizeHostName选项
    • slaveOk options and method removed in favor of secondaryOkslaveOk选项和方法已删除，支持secondaryOk
    • ObjectID type removed in favor of ObjectId已删除ObjectID类型以支持ObjectID
    • AsyncIterator interface removed in favor of AsyncGenerator已删除AsyncIterator接口以支持AsyncGenerator

Version 4.x Breaking Changes版本4x突破性更改

  • Driver versions 4.x are not compatible with Node.js v12.8 or earlier. 驱动程序版本4x与Node.js v12.8或更早版本不兼容。If you want to use this version of the driver, You must use Node.js v12.9 or greater.如果你想使用这个版本的驱动程序，你必须使用Node.js v12.9或更高版本。
  • Cursor types no longer extend Readable directly.Cursor类型不再直接扩展Readable。
  • You cannot use a ChangeStream instance as an iterator after using it as an EventEmitter. 在将ChangeStream实例用作EventEmitter之后，不能将其用作迭代器。You also cannot do the reverse—using an EventEmitter instance as an iterator after using it as a ChangeStream.在将EventEmitter实例用作ChangeStream之后，也不能将其用作迭代器来执行相反的操作。
  • The following methods no longer accept a callback parameter:以下方法不再接受callback参数：

    • Collection.find()
    • Collection.aggregate()
    • Db.aggregate()
  • The default value of the maxPoolSize connection option is now 100.maxPoolSize连接选项的默认值现在是100。
  • The driver no longer supports the gssapiServiceName Kerberos option. 驱动程序不再支持gssapiServiceName Kerberos选项。Users should use authMechanismProperties.SERVICE_NAME instead.用户应改为使用authMechanismProperties.SERVICE_NAME。
  • The driver no longer accepts non-boolean types, such as 0 or 1, for boolean options.对于布尔选项，驱动程序不再接受非布尔类型，如0或1。
  • The db.collection type no longer accepts a callback.db.collection类型不再接受回调。
  • The Db type is no longer an EventEmitter. Db类型不再是EventEmitter。You can listen to any events directly from the MongoClient instance.您可以直接从MongoClient实例中侦听任何事件。
  • The driver removes support for the Collection.group() helper.该驱动程序删除了对Collection.group()帮助程序的支持。
  • The driver no longer includes the deprecated GridStore API.驱动程序不再包含不推荐使用的GridStore API。

For more information about these changes, see the v4.0 changelog.有关这些更改的详细信息，请参阅v4.0更改日志。

Server Release Compatibility Changes服务器版本兼容性更改

A server release compatibility change is a modification to the driver that discontinues support for a set of MongoDB Server versions.服务器版本兼容性更改是对驱动程序的修改，它终止了对一组MongoDB server版本的支持。

The driver discontinues support for a MongoDB Server version after it reaches end-of-life (EOL).该驱动程序在MongoDB Server版本达到报废（EOL）后停止支持该版本。

To learn more about the MongoDB support for EOL products, see the Legacy Support Policy.要了解更多关于MongoDB对EOL产品的支持，请参阅旧版支持政策。

Version 4.2 Server Release Support Changes4.2版服务器版本支持更改