升级驱动程序版本
概述
本页面描述了在升级到新版本的C++驱动程序时,您必须对应用程序进行的更改。
升级前,请执行以下操作
确保新的C++驱动程序版本与您的应用程序连接的MongoDB服务器版本以及您的应用程序编译的C++标准版本兼容。有关版本兼容性信息,请参阅C++驱动程序兼容性页面。
解决驱动程序版本与您计划升级的版本之间的任何破坏性更改,请参阅破坏性更改部分。
提示
为确保在升级驱动程序版本时跨MongoDB服务器版本的兼容性,请使用稳定API。
破坏性更改的定义
注意
该C++驱动程序遵循语义版本控制。 驱动程序在任何版本中都可能破坏构建系统或软件包兼容性。补丁版本可能会撤销意外破坏API的更改。
有关更多信息,请参阅API和ABI版本控制。
破坏性更改是指从驱动程序的特定版本开始更改约定或行为。如果不在升级驱动程序之前解决此类更改,则可能导致您的应用程序无法正常工作。
本节中的破坏性更改按引入它们的驱动程序版本进行分类。在升级驱动程序版本时,解决当前版本和升级版本之间的所有破坏性更改。
示例
升级到版本4.0
如果您正在将C++驱动程序从3.x版本升级到4.0版本,请解决列出的3.x版本及更高版本的所有破坏性更改
破坏性更改的类型
C++驱动程序的新版本可能会引入以下类型的破坏性更改
API更改涉及C++驱动程序库的API。这些更改伴随着API主版本的提升。您可能需要编辑项目中C++源代码以解决这些更改。
示例
移除了函数的声明
v1::func()
。(定义仍提供以保持ABI兼容性。)移除了内联函数
v_noabi::func()
。移除了
v_noabi::func()
。将
bsoncxx::foo
的重新声明从v1::foo
更改为v2::foo
。要继续使用旧接口,请将bsoncxx::foo
指定为bsoncxx::v1::foo
。
ABI 变更涉及 C++ 驱动库的 ABI。这些变更伴随着 ABI 版本号的增加,也可能伴随着 API 主版本号的增加。您可能需要重新构建项目或编辑 C++ 源代码以应对这些变更。
不 支持对
v_noabi
命名空间中声明的实体对应的符号的 ABI 稳定性。此类符号的破坏性变更不一定伴随着 ABI 版本号的增加。示例
删除了导出的符号
v_noabi::func()
。删除了导出的符号
v1::func()
。删除了
v1::type
的导出符号。
构建系统 变更涉及 C++ 驱动库的构建系统或打包。这些变更不一定伴随着 API 主版本号或 ABI 版本号的增加。为了应对这些变更,您可能需要修改构建系统配置或更新项目包或依赖管理设置。您还可能需要修改或重新构建 C++ 源代码。
示例
删除了配置变量
ENABLE_FOO
。将配置变量
ENABLE_BAR
的默认值从OFF
更改为ON
。取消支持平台 A、编译器 B 或架构 C。
破坏性变更
以下各节描述了每个驱动版本发布引入的破坏性变更。
版本 4.0
4.0版本构建系统重大更改
4.0版本驱动程序对构建系统引入了以下重大更改
不再支持Boost和MNMLSTC/core外部polyfill库。您不能再设置以下配置选项
ENABLE_BSONCXX_POLY_USE_IMPLS
。此选项默认设置为ON
。BSONCXX_POLY_USE_MNMLSTC
.BSONCXX_POLY_USE_SYSTEM_MNMLSTC
.BSONCXX_POLY_USE_BOOST
.
不再支持
MONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX
配置选项。现在默认尊重CMake的CMAKE_INSTALL_PREFIX
行为。默认将
ENABLE_TESTS
配置选项设置为OFF
。要重新启用构建测试目标,必须将ENABLE_TESTS
设置为ON
。要包括测试目标在“all”目标中,还必须将BUILD_TESTING
选项设置为ON
。
4.0版本API重大更改
4.0版本驱动程序对API引入了以下重大更改
不再支持将
bsoncxx::stdx::string_view
和bsoncxx::stdx::optional<T>
配置为Boost或MNMLSTC/core库等价物的别名。有关上下文,请参阅构建系统重大更改部分。删除以下头文件
<bsoncxx/stdx/make_unique.hpp>
<bsoncxx/types/value.hpp>
<bsoncxx/util/functor.hpp>
<mongocxx/options/create_collection.hpp>
删除以下过时的
utf8
类型和函数,这些函数有等效的string
类型从
bsoncxx::v_noabi::type
类中删除k_utf8
。相反,使用k_string
。从
bsoncxx::v_noabi::types
类中移除b_utf8
。相反,使用b_string
。从
bsoncxx::v_noabi::document::element
、bsoncxx::v_noabi::array::element
和bsoncxx::v_noabi::types::bson_value::view
类中移除get_utf8()
。相反,使用get_string()
。从
bsoncxx::v_noabi::exception::error_code
类中移除k_cannot_append_utf8
。相反,使用k_cannot_append_string
。从
bsoncxx::v_noabi::exception::error_code
类中移除k_need_element_type_k_utf8
。相反,使用k_need_element_type_k_string
。
移除
mongocxx::stdx
命名空间。请在您的代码中替换以下类型mongocxx::stdx::optional<T>
。相反,使用bsoncxx::stdx::optional<T>
。mongocxx::stdx::string_view
。相反,使用bsoncxx::stdx::string_view
。
移除以下未记录的
using
指令和声明从
<bsoncxx/builder/list.hpp>
头文件中移除bsoncxx::builder::types
。相反,使用<bsoncxx/types.hpp>
中的bsoncxx::types
。从
<bsoncxx/builder/stream/helpers.hpp>
头文件中移除bsoncxx::builder::stream::concatenate
。相反,使用<bsoncxx/builder/concatenate.hpp>
中的bsoncxx::builder::concatenate
。从
<mongocxx/events/topology_description.hpp>
头文件中移除mongocxx::events::read_preference
。相反,使用<mongocxx/read_preference.hpp>
中的mongocxx::read_preference
。
第 4.0 版本的 ABI 破坏性更改
第 4.0 版本驱动程序对 ABI 引入了以下破坏性更改
第 3.11 版本
版本3.11中构建系统的重大变更
版本3.11驱动程序对构建系统引入以下重大变更
取消对MongoDB Server v3.6的支持。
需要MongoDB C驱动程序v1.28.0或更高版本。
版本3.11中的ABI重大变更
版本3.11驱动程序对ABI引入以下重大变更
在bsoncxx ABI中删除以下私有成员函数的导出
bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)
bsoncxx::v_noabi::types::bson_value::view::_init(void*)
bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)
bsoncxx::v_noabi::types::bson_value::view::view(void*)
在mongocxx ABI中删除以下私有成员函数的导出
mongocxx::v_noabi::options::change_stream::as_bson()
mongocxx::v_noabi::options::aggregate::append( bsoncxx::v_noabi::builder::basic::document&)
mongocxx::v_noabi::options::index::storage_options()
使用MSVC编译时,所有导出的函数符号均声明为
__cdecl
。如果您在构建项目时使用替代默认调用约定,则这是一个破坏ABI的变更。
版本 3.10
版本 3.10 中构建系统的破坏性变更
版本 3.10 的驱动程序对构建系统引入了以下破坏性变更
弃用了对调用
find_package(libbsoncxx)
和find_package(libmongocxx)
的支持。请使用find_package(bsoncxx)
和find_package(mongocxx)
代替。弃用了由旧版 CMake 软件包配置文件提供的
LIBBSONCXX_*
和LIBMONGOCXX_*
CMake 变量。请使用mongo::bsoncxx_*
和mongo::mongocxx_*
CMake 目标代替。删除了
BSONCXX_POLY_USE_STD_EXPERIMENTAL
CMake 选项,并弃用了选择实验性 C++ 标准库作为填充选项的支持。
版本 3.9
3.9 版本构建系统破坏性更改
3.9 驱动引入以下破坏性更改
从 CMake 项目构建树中删除了对导出目标的支持
放弃了对 macOS 10.14、macOS 10.15 和 Ubuntu 14.04 的支持
需要 MongoDB C 驱动程序 v1.25.0 或更高版本
需要 CMake v3.15 或更高版本以支持
FetchContent
模块
版本 3.8 及更早版本
对于 3.8 版本及更早的驱动程序版本,请参阅每个版本的发布说明和相关 JIRA 工单,详情请访问 GitHub.