Docs Menu
Docs Home
/ / /
C Driver

Upgrade Driver Versions

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.

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

The 2.0.0 release of libbson includes the following breaking changes:

  • Reduces the value of the BSON_ERROR_BUFFER_SIZE macro from 504 to 503 to reserve the final byte for internal use.

  • Renames the following pkg-config files:

    • libbson-1.0: Renamed to bson2

    • libbson-static-1.0: Renamed to bson2-static

  • Removes the bson-1.0 CMake package. Instead, use bson 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 to bson::static

    • mongo::bson_shared: Renamed to bson::shared

  • Adds the bson::bson target, which points to either the static library or shared library depending on the value of the BSON_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.

The 2.0 release of libmongoc includes the following breaking changes:

  • If you pass the batchSize:0 option to mongoc_client_watch, mongoc_database_watch, or mongoc_collection_watch, the aggregate command no longer ignores this option and applies it.

  • Removes bson_oid_init_sequence. Instead, use bson_oid_init.

  • Changes the return type of mongoc_server_description_host from mongoc_host_list_t * to const 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, the authSource 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 within authMechanismProperties values. For example, setting authMechanismProperties=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 same mongoc_bulk_operation_t repeatedly.

  • Consistently applies the __cdecl calling convention to function declarations in the public API.

  • mongoc_client_set_ssl_opts ignores a pooled mongoc_client_t and logs an error. Before popping a client, use mongoc_client_pool_set_ssl_opts to set TLS options on a mongoc_client_pool_t.

  • mongoc_client_set_ssl_stream_initiator ignores a pooled mongoc_client_t and logs an error.

  • Renames the following pkg-config files:

    • libmongoc-1.0: Renamed to mongoc2

    • libmongoc-static-1.0: Renamed to mongoc2-static

  • Removes the mongoc-1.0 CMake package. Instead, use mongoc 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 to mongoc::static

    • mongo::mongoc_shared: Renamed to mongoc::shared

  • Adds the mongoc::mongoc target, which points to either the static library or shared library depending on the value of the MONGOC_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.

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

The 1.28.0 release of libbson includes the following breaking changes:

  • Removes automatic ccache detection and usage

  • Removes Mongo_USE_CCACHE

The 1.28.0 release of libmongoc includes the following breaking changes:

  • Raises the minimum wire protocol version from 6 to 7

  • Raises the required libmongocrypt version to v1.11.0 to support In-Use Encryption

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.

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.

The 1.24 release of libmongoc includes the following breaking changes:

  • Requires MongoDB Server version 7.0 and later to use Queryable Encryption

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.

  • 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.

Back

Compatibility

On this page

  • Overview
  • Breaking Changes
  • Version 2.0.0
  • Version 1.29.0
  • Version 1.28.0
  • Version 1.27.0
  • Version 1.26.2
  • Version 1.24
  • Server Release Compatibility Changes
  • Version 1.28.0 Release Support Changes