Upgrade Driver Versions

Overview

This page describes the changes you must make to your application when you upgrade to a new version of the C++ driver.

Before you upgrade, perform the following actions:

Ensure the new C++ driver version is compatible with the MongoDB Server versions your application connects to and the C++ standard version your application compiles with. For version compatibility information, see Compatibility.
Address any breaking changes between the driver version your application is using and your planned upgrade version in the Breaking Changes section.

Tip

To ensure compatibility across MongoDB Server versions when upgrading driver versions, use the Stable API.

Definition of Breaking Changes

Note

The C++ driver follows semantic versioning. The driver may break build system or package compatibility in any release. Patch releases may revert accidental API breaking changes.

For more information, see API and ABI Versioning.

A breaking change is a change of a convention or a behavior starting in a specific version of the driver. This type of change may prevent your application from working properly if not addressed before upgrading the driver.

The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions.

Example

Upgrading to Version 4.0

If you're upgrading the C++ driver from version 3.x to version 4.0, address all breaking changes that are listed for versions 3.x up to and including version 4.0

Types of Breaking Changes

New versions of the C++ driver can introduce the following types of breaking changes:

API changes concern the API of the C++ driver libraries. These changes are accompanied by an API major version bump. You might need to edit C++ source code in your project to address these changes.
Example
- Removes the declaration of function v1::func(). (The definition is still provided for ABI compatibility.)
- Removes the inline function v_noabi::func().
- Removes v_noabi::func().
- Changes the redeclaration of bsoncxx::foo from v1::foo to v2::foo. To continue using the old interface, qualify bsoncxx::foo as bsoncxx::v1::foo.
ABI changes concern the ABI of the C++ driver libraries. These changes are accompanied by an ABI version bump, and may also be accompanied by an API major version bump. You might need to rebuild your project or edit your C++ source code to address these changes.
ABI stability is not supported for symbols corresponding to entities declared in the v_noabi namespace. Breaking changes for such symbols are not necessarily accompanied by an ABI version bump.
Example
- Removes the exported symbol v_noabi::func().
- Removes the exported symbol v1::func().
- Removes the exported symbols for v1::type.
Build system changes concern the build system or packaging of the C++ driver libraries. These changes are not necessarily accompanied by either an API major version bump or an ABI version bump. To address these changes, you might need to modify your build system configurations or update your project's package or dependency management settings. You might also need to modify or rebuild your C++ source code.
Example
- Removes the ENABLE_FOO configuration variable.
- Changes the default value of the ENABLE_BAR configuration variable from OFF to ON.
- Drops support for platform A, compiler B, or architecture C.

Breaking Changes

The following sections describe the breaking changes introduced by each driver version release.

Version 4.2

Build System Breaking Changes in v4.2

The v4.2 driver introduces the following breaking changes to the build system:

Drops support for macOS 11 and macOS 12

Version 4.1

Build System Breaking Changes in v4.1

The v4.1 driver introduces the following breaking changes to the build system:

Requires MongoDB C Driver v2.0.0 or later

Sets the ENABLE_TESTS configuration option to OFF by default for auto-downloaded versions of the C driver. This is an expansion of the change made in v4.0.

ABI Breaking Changes in v4.1

The v4.1 driver introduces the following breaking changes to the ABI:

Declares C++17 polyfill implementations for optional<T> and string_view in the bsoncxx::v1::stdx namespace. The bsoncxx::v_noabi::stdx namespace now contains type aliases to their v1 equivalents.
Note
This does not affect users who compile with C++17 or newer and have not set BSONCXX_POLY_USE_IMPLS=ON

Version 4.0

Build System Breaking Changes in v4.0

The v4.0 driver introduces the following breaking changes to the build system:

Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no longer set the following configuration options:
- ENABLE_BSONCXX_POLY_USE_IMPLS. This option is implicitly set to ON.
- BSONCXX_POLY_USE_MNMLSTC.
- BSONCXX_POLY_USE_SYSTEM_MNMLSTC.
- BSONCXX_POLY_USE_BOOST.
Drops support for the MONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX configuration option. Default CMake behavior for CMAKE_INSTALL_PREFIX is now respected.

Sets the ENABLE_TESTS configuration option to OFF by default. To re-enable building test targets, you must set ENABLE_TESTS to ON. To include test targets in the "all" target, you must also set the BUILD_TESTING option to ON.
Note
This change does not apply to auto-downloaded versions of the C driver. The change for auto-downloaded versions was added in v4.1.

API Breaking Changes in v4.0

The v4.0 driver introduces the following breaking changes to the API:

Drops support for configuring bsoncxx::stdx::string_view and bsoncxx::stdx::optional<T> as aliases for Boost or MNMLSTC/core library equivalents. For context, see the Build System Breaking Changes section.
Removes the following header files:
- <bsoncxx/stdx/make_unique.hpp>
- <bsoncxx/types/value.hpp>
- <bsoncxx/util/functor.hpp>
- <mongocxx/options/create_collection.hpp>
Removes the following deprecated utf8 types and functions that have string equivalents:
- k_utf8 from the bsoncxx::v_noabi::type class. Instead, use k_string.
- b_utf8 from the bsoncxx::v_noabi::types class. Instead, use b_string.
- get_utf8() from the bsoncxx::v_noabi::document::element, bsoncxx::v_noabi::array::element, and bsoncxx::v_noabi::types::bson_value::view classes. Instead, use get_string().
- k_cannot_append_utf8 from the bsoncxx::v_noabi::exception::error_code class. Instead, use k_cannot_append_string.
- k_need_element_type_k_utf8 from the bsoncxx::v_noabi::exception::error_code class. Instead, use k_need_element_type_k_string.
Removes the mongocxx::stdx namespace. Replace the following types in your code:
- mongocxx::stdx::optional<T>. Instead, use bsoncxx::stdx::optional<T>.
- mongocxx::stdx::string_view. Instead, use bsoncxx::stdx::string_view.
Removes the following undocumented using directives and declarations:
- bsoncxx::builder::types from the <bsoncxx/builder/list.hpp> header file. Instead, use bsoncxx::types from <bsoncxx/types.hpp>.
- bsoncxx::builder::stream::concatenate from the <bsoncxx/builder/stream/helpers.hpp> header file. Instead, use bsoncxx::builder::concatenate from <bsoncxx/builder/concatenate.hpp>.
- mongocxx::events::read_preference from the <mongocxx/events/topology_description.hpp> header file. Instead, use mongocxx::read_preference from <mongocxx/read_preference.hpp>.

ABI Breaking Changes in v4.0

The v4.0 driver introduces the following breaking changes to the ABI:

Drops support for configuring bsoncxx::stdx::string_view and bsoncxx::stdx::optional<T> as aliases for Boost or MNMLSTC/core library equivalents. For context, see the Build System Breaking Changes section.
Removes deprecated utf8 functions that have string equivalents. For a full list of these changes, see the API Breaking Changes section.

Version 3.11

Build System Breaking Changes in v3.11

The v3.11 driver introduces the following breaking changes to the build system:

Drops support for MongoDB Server v3.6.
Requires MongoDB C Driver v1.28.0 or later.
If the ENABLE_TESTS configuration option is set to ON, C++14 or later is required. You can opt out of the C++14 requirement by disabling tests with ENABLE_TESTS=OFF during CMake configuration.

ABI Breaking Changes in v3.11

The v3.11 driver introduces the following breaking changes to the ABI:

Removes export of the following private member functions in the 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*)

Removes export of the following private member functions in the 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()
```
Declare all exported functions symbols with __cdecl when compiled with MSVC. This is an ABI breaking change if you use an alternative default calling convention when building projects.

Version 3.10

Build System Breaking Changes in v3.10

The v3.10 driver introduces the following breaking changes to the build system:

Drops support for calling find_package(libbsoncxx) and find_package(libmongocxx). Use find_package(bsoncxx) and find_package(mongocxx) instead.
Drops support for the LIBBSONCXX_* and LIBMONGOCXX_* CMake variables provided by the legacy CMake package config files. Use the mongo::bsoncxx_* and mongo::mongocxx_* CMake targets instead.
Removes the BSONCXX_POLY_USE_STD_EXPERIMENTAL CMake option and drops support for selecting the experimental C++ standard library as a polyfill option.

Version 3.9

Build System Breaking Changes in v3.9

The v3.9 driver introduces the following breaking changes:

Removes support for exported targets from the CMake project build tree
Drops support for macOS 10.14, macOS 10.15, and Ubuntu 14.04
Requires MongoDB C Driver v1.25.0 or later
Requires CMake v3.15 or later to support the FetchContent module

Version 3.8 and Earlier

For driver versions 3.8 and earlier, see the release notes and associated JIRA tickets for each release on GitHub.

Back

What's New

Testing