Overview
本页介绍了升级到新版本的C驱动程序时必须对应用程序进行的更改。
升级前,请执行以下操作:
确保新的C驾驶员版本与应用程序连接到的MongoDB Server版本以及应用程序运行的平台兼容。有关版本兼容性信息,请参阅 C驾驶员兼容性页面。
在破坏性变更部分解决应用程序使用的当前驱动程序版本与计划升级版本之间的任何破坏性变更。要了解有关 MongoDB Server 版本兼容性更改的更多信息,请参阅服务器版本兼容性更改部分。
提示
为了最大限度地减少应用程序将来升级驾驶员版本时所需的更改数量,请使用 Stable API。要学习;了解详情,请参阅 Stable API指南。
重大更改
注意
C 驱动程序遵循语义版本控制。驱动程序可能会在任何版本中破坏构建系统或包的兼容性。补丁版本可能会撤销意外的 API 破坏性变更。
重大更改是对从特定版本的驱动程序开始的约定或行为的更改。 如果在升级驱动程序之前未解决,此类更改可能会导致应用程序无法正常工作。
本部分中的破坏性变更 (breaking change) 按引入它们的驱动程序版本进行分类。升级驱动程序版本时,请解决当前版本和升级版本之间的所有破坏性变更 (breaking change)。
C驱动程序由两个库组成:libbson 和 libmongoc。本指南的各部分介绍了每个库中包含的重大更改。
例子
升级到版本 2.0.0
如果您要将 C 驱动程序从版本 1.x 升级到版本 2.0.0,解决版本 1.x 直至(包括)版本 2.0.0 列出的所有破坏性变更
版本 2.1.0
libbson 重大更改
libbson 的 2.1.0发布包含以下重大更改:
删除了对Debian 9 和Debian 10 的支持。
CMake项目将 CMake 策略最高版本设置为
4.0。上一个驱动程序版本不会设立策略最高版本。这可能是构建系统的破坏性变更 (breaking change),具体取决于您的 CMake 版本和 CMake 配置选项。
libmongoc 重大更改
libmongoc 的 2.1.0发布包含以下重大更改:
删除了对Debian 9 和Debian 10 的支持。
CMake项目将 CMake 策略最高版本设置为
4.0。上一个驱动程序版本不会设立策略最高版本。这可能是构建系统的破坏性变更 (breaking change),具体取决于您的 CMake 版本和 CMake 配置选项。
版本 2.0.0
libbson v2.0.0 中的重大更改
libbson 的 2.0.0发布包含以下重大更改:
将
BSON_ERROR_BUFFER_SIZE宏的值从504减少到503,以保留最终字节以供内部使用。重命名以下
pkg-config文件:libbson-1.0:重命名为bson2libbson-static-1.0:重命名为bson2-static
删除
bson-1.0CMake包。相反,请使用bson并指定要导入的版本或版本范围,如以下示例所示:find_package(bson 1.30...2.0) 重命名以下导入的目标:
mongo::bson_static:重命名为bson::staticmongo::bson_shared:重命名为bson::shared
添加
bson::bson目标,该目标指向静态库或共享库,具体取决于BSON_DEFAULT_IMPORTED_LIBRARY_TYPECMake 选项的值。如果未设立此选项且两种库类型都可用,则bson::bson将使用静态库。
libmongoc v2.0.0 中的重大更改
libmongoc 的 2.0发布包含以下重大更改:
如果将
batchSize:0选项传递给mongoc_client_watch、mongoc_database_watch或mongoc_collection_watch,则aggregate命令将不再忽略并应用该选项。删除
bson_oid_init_sequence。请改用bson_oid_init。将
mongoc_server_description_host的返回类型从mongoc_host_list_t *更改为const mongoc_host_list_t *。对 URI身份验证凭证验证实施以下更改,这些更改在从连接字符串创建新的
mongoc_uri_t对象时应用:要求所有身份验证机制的用户名均为非空。
验证用户名和密码规范要求,并为指定的身份验证机制返回客户端错误。
对于
MONGODB-AWS身份验证机制,authSource值默认为$external。验证
authMechanism值并返回无效值的客户端错误。验证
authMechanismProperties值,并因指定身份验证机制的属性无效而返回客户端错误。正确解析
authMechanismProperties值中的冒号 (:) 字符。示例,设置authMechanismProperties=A:B,C:D:E,F:G会导致驱动程序将该值解析为{'A': 'B', 'C': 'D:E,F:G'}。现在解析为{'A': 'B': 'C': 'D:E', 'F': 'G'}。
如果您重复对同一
mongoc_bulk_operation_t调用mongoc_bulk_operation_execute,则会产生错误。对公共API中的函数声明一致应用
__cdecl调用约定。mongoc_client_set_ssl_opts忽略池化的mongoc_client_t并记录错误。在弹出客户端之前,使用mongoc_client_pool_set_ssl_opts在mongoc_client_pool_t上设立TLS 选项。mongoc_client_set_ssl_stream_initiator忽略池化的mongoc_client_t并记录错误。重命名以下
pkg-config文件:libmongoc-1.0:重命名为mongoc2libmongoc-static-1.0:重命名为mongoc2-static
删除
mongoc-1.0CMake包。相反,请使用mongoc并指定要导入的版本或版本范围,如以下示例所示:find_package(mongoc 1.30...2.0) 重命名以下导入的目标:
mongo::mongoc_static:重命名为mongoc::staticmongo::mongoc_shared:重命名为mongoc::shared
添加
mongoc::mongoc目标,该目标指向静态库或共享库,具体取决于MONGOC_DEFAULT_IMPORTED_LIBRARY_TYPECMake 选项的值。如果未设立此选项且两种库类型都可用,则mongoc::mongoc将使用静态库。
版本 1.29.0
libmongoc v1.29.0 中的重大更改
libmongoc 的 1.29.0发布包含以下重大更改:
删除对 Visual Studio 2013 的支持
将所需的
libmongocrypt依赖项版本提高到 1.12.0,以支持“正在使用的加密”功能
版本 1.28.0
libbson v1.28.0 中的重大更改
libbson 的 1.28.0发布包含以下重大更改:
删除
ccache的自动检测和使用删除
Mongo_USE_CCACHE
libmongoc v1.28.0 中的重大更改
libmongoc 的 1.28.0发布包含以下重大更改:
将最低传输协议版本从
6提高到7将所需的
libmongocrypt版本提高到 v1.11.0 以支持正在使用的加密
版本 1.27.0
libmongoc v1.27.0 中的重大更改
libmongoc 的 1.27.0发布包含以下重大更改:
将所需的 libmongocrypt 版本提高到 1.10.0 以支持正在使用的加密。这对应于 CMake 选项
ENABLE_CLIENT_SIDE_ENCRYPTION。
版本 1.26.2
libmongoc v1.26.2 中的重大更改
libmongoc 的 1.26.2发布包含以下重大更改:
默认下,禁用在Windows上使用 Cyrus SASL 加载插件。 要重新启用,请将 CMake 选项
CYRUS_PLUGIN_PATH_PREFIX设立为 Cyrus SASL 插件的绝对路径前缀。
版本 1.24
libmongoc v1.24 中的重大更改
libmongoc 的 1.24发布包含以下重大更改:
需要MongoDB Server 7.0 及更高版本才能使用Queryable Encryption
服务器版本兼容性更改
服务器版本兼容性更改是对驱动程序的修改,停止对一组 MongoDB 服务器版本的支持。
该驱动程序在 MongoDB Server 版本的生命周期结束 (EOL) 后将停止支持。
要学习;了解有关MongoDB对 EOL 产品的支持的更多信息,请参阅传统支持策略。