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 platform your application runs on. For version compatibility information, see the C driver Compatibility page.
Address any breaking changes between the current driver version your application uses and your planned upgrade version in the Breaking Changes section. To learn more about MongoDB Server release compatibility changes, see the Server Release Compatibility Changes section.
Tip
To minimize the number of changes your application requires when upgrading driver versions in the future, use the Stable API. To learn more, see the Stable API guide.
Breaking Changes
Note
The C driver follows semantic versioning. The driver may break build systems or package compatibility in any release. Patch releases may revert accidental API breaking changes.
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.
The C driver consists of two libraries: libbson
and libmongoc
. The
sections of this guide describe the breaking changes included in each library.
Example
Upgrading to Version 2.0.0
If you're upgrading the C driver from version 1.x to version 2.0.0, address all breaking changes that are listed for versions 1.x up to and including version 2.0.0
Version 2.0.0
libbson Breaking Changes in v2.0.0
The 2.0.0 release of libbson
includes the following breaking changes:
Reduces the value of the
BSON_ERROR_BUFFER_SIZE
macro from504
to503
to reserve the final byte for internal use.Renames the following
pkg-config
files:libbson-1.0
: Renamed tobson2
libbson-static-1.0
: Renamed tobson2-static
Removes the
bson-1.0
CMake package. Instead, usebson
and specify a version or version range to be imported, as shown in the following example:find_package(bson 1.30...2.0) Renames the following imported targets:
mongo::bson_static
: Renamed tobson::static
mongo::bson_shared
: Renamed tobson::shared
Adds the
bson::bson
target, which points to either the static library or shared library depending on the value of theBSON_DEFAULT_IMPORTED_LIBRARY_TYPE
CMake option. If you don't set this option and both library types are available,bson::bson
uses the static library.
libmongoc Breaking Changes in v2.0.0
The 2.0 release of libmongoc
includes the following breaking changes:
If you pass the
batchSize:0
option tomongoc_client_watch
,mongoc_database_watch
, ormongoc_collection_watch
, theaggregate
command no longer ignores this option and applies it.Removes
bson_oid_init_sequence
. Instead, usebson_oid_init
.Changes the return type of
mongoc_server_description_host
frommongoc_host_list_t *
toconst mongoc_host_list_t *
.Implements the following changes to URI authentication credentials validation, which apply when creating a new
mongoc_uri_t
object from a connection string:Requires that usernames are non-empty for all authentication mechanisms.
Validates username and password specification requirements and returns a client error for the specified authentication mechanism.
For the
MONGODB-AWS
authentication mechanism, theauthSource
value defaults to$external
.Validates
authMechanism
values and returns a client error for invalid values.Validates
authMechanismProperties
values and returns a client error for invalid properties for the specified authentication mechanism.Correctly parses colon (
:
) characters withinauthMechanismProperties
values. For example, settingauthMechanismProperties=A:B,C:D:E,F:G
caused the driver to parse the value as{'A': 'B', 'C': 'D:E,F:G'}
. This is now parsed as{'A': 'B': 'C': 'D:E', 'F': 'G'}
.
Generates an error if you call
mongoc_bulk_operation_execute
on the samemongoc_bulk_operation_t
repeatedly.Consistently applies the
__cdecl
calling convention to function declarations in the public API.mongoc_client_set_ssl_opts
ignores a pooledmongoc_client_t
and logs an error. Before popping a client, usemongoc_client_pool_set_ssl_opts
to set TLS options on amongoc_client_pool_t
.mongoc_client_set_ssl_stream_initiator
ignores a pooledmongoc_client_t
and logs an error.Renames the following
pkg-config
files:libmongoc-1.0
: Renamed tomongoc2
libmongoc-static-1.0
: Renamed tomongoc2-static
Removes the
mongoc-1.0
CMake package. Instead, usemongoc
and specify a version or version range to be imported, as shown in the following example:find_package(mongoc 1.30...2.0) Renames the following imported targets:
mongo::mongoc_static
: Renamed tomongoc::static
mongo::mongoc_shared
: Renamed tomongoc::shared
Adds the
mongoc::mongoc
target, which points to either the static library or shared library depending on the value of theMONGOC_DEFAULT_IMPORTED_LIBRARY_TYPE
CMake option. If you don't set this option and both library types are available,mongoc::mongoc
uses the static library.
Version 1.29.0
libmongoc Breaking Changes in v1.29.0
The 1.29.0 release of libmongoc
includes the following breaking changes:
Drops support for Visual Studio 2013
Raises required version of the
libmongocrypt
dependency to 1.12.0 to support the In-Use Encryption feature
Version 1.28.0
libbson Breaking Changes in v1.28.0
The 1.28.0 release of libbson
includes the following breaking changes:
Removes automatic
ccache
detection and usageRemoves
Mongo_USE_CCACHE
libmongoc Breaking Changes in v1.28.0
The 1.28.0 release of libmongoc
includes the following breaking changes:
Raises the minimum wire protocol version from
6
to7
Raises the required
libmongocrypt
version to v1.11.0 to support In-Use Encryption
Version 1.27.0
libmongoc Breaking Changes in v1.27.0
The 1.27.0 release of libmongoc
includes the following breaking changes:
Raises the required version of libmongocrypt to 1.10.0 to support In-Use Encryption. This corresponds to the CMake option
ENABLE_CLIENT_SIDE_ENCRYPTION
.
Version 1.26.2
libmongoc Breaking Changes in v1.26.2
The 1.26.2 release of libmongoc
includes the following breaking changes:
By default, disables plugin loading with Cyrus SASL on Windows. To re-enable, set the CMake option
CYRUS_PLUGIN_PATH_PREFIX
to the absolute path prefix of the Cyrus SASL plugins.
Version 1.24
libmongoc Breaking Changes in v1.24
The 1.24 release of libmongoc
includes the following breaking changes:
Requires MongoDB Server version 7.0 and later to use Queryable Encryption
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.
The driver discontinues support for a MongoDB Server version after it reaches end-of-life (EOL).
To learn more about MongoDB support for EOL products, see the Legacy Support Policy.
Version 1.28.0 Release Support Changes
This driver version drops support for MongoDB Server versions 3.6 and earlier. To use any driver from versions 1.28.0 and later, your MongoDB Server must be version 4.0 or later. This driver version supports MongoDB Server 8.0 features. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.