mongo-c-driver 2.0.0

Announcing 2.0.0 of libbson and libmongoc, the libraries constituting the MongoDB C Driver.

libbson

New Features

• Add support for BSON Binary Vector.

Changes

• BSON_ERROR_BUFFER_SIZE is reduced from 504 to 503 to reserve the final byte for internal use.
  • The data layout of bson_error_t remains otherwise unchanged: the size is still 512 bytes and the offset of the .code, .domain, and .message data members remain unchanged.
• The pkg-config files libbson-1.0 and libbson-static-1.0 have been renamed to bson2, and bson2-static, respectively.

CMake Packages and Imported Targets

The bson-1.0 CMake package has been removed. Instead, use or bson, and
specify a version or version range to be imported:

find_package(bson 1.30...2.0)

The new package imports different target names:

• mongo::bson_static → bson::static
• mongo::bson_shared → bson::shared
• The target bson::bson is a shim target that points to either the shared library or the static library.

Removals

• bson_as_json and bson_array_as_json are removed due to producing non-portable Legacy Extended JSON. Prefer Canonical Extended JSON or Relaxed Extended JSON for portability. To continue using Legacy Extended JSON, use bson_as_legacy_extended_json and bson_array_as_legacy_extended_json.
• Compiling with BSON_MEMCHECK defined now has no effect.
• Remove deprecated integral comparison interfaces: bson_in_range_* and bson_cmp_*.
• Remove deprecated atomic and threading interfaces: bson_atomic_* and bson_thrd_yield.
• The deprecated ENABLE_EXTRA_ALIGNMENT CMake option is removed.
  • bson_t and bson_iter_t are now aligned to the size of a pointer instead of 128.
  • bson_error_t, bson_value_t, and bson_visitor_t are now aligned to the size of a pointer instead of 8.
  • BSON_ALIGNED_BEGIN and BSON_ALIGNED_END now unconditionally apply their requested alignment.
• Remove deprecated bson_copy_to_excluding. Use bson_copy_to_excluding_noinit instead.

libmongoc

New Features

• Support aggregate operations with $lookup stage for In-Use Encryption.

Notes

• In a future minor release the minimum supported MongoDB Server version will be raised from 4.0 to 4.2. This is in accordance with MongoDB Software Lifecycle Schedules.
• Raise required version of libmongocrypt to 1.13.0 to support In-Use Encryption (corresponds to the CMake option: ENABLE_CLIENT_SIDE_ENCRYPTION).

Changes

• Passing batchSize:0 as an option to mongoc_client_watch, mongoc_database_watch, or mongoc_collection_watch
  now applies batchSize:0 to the aggregate command. Useful to request an immediate cursor. Previously the value
  was ignored.
• bson_oid_init_sequence is removed. Use bson_oid_init instead.
• mongoc_server_description_host changes the return type from mongoc_host_list_t * to const mongoc_host_list_t *.
• URI authentication credentials validation (only applicable during creation of a new mongoc_uri_t object from a connection string):
  • The requirement that a username is non-empty when specified is now enforced regardless of authentication mechanism.
  • Username and password specification requirements are now validated and returns a client error for the specified authentication mechanism.
    • e.g. it is a client error to not specify a username or a password for SCRAM-SHA-1, SCRAM-SHA-256, and PLAIN.
    • e.g. it is a client error to specify a password for MONGODB-X509.
    • e.g. it is a client error to specify a username or a password without the other for MONGODB-AWS.
  • authSource is now correctly defaulted to "$external" for MONGODB-AWS (instead of the database name or "admin").
  • authMechanism is now validated and returns a client error for invalid or unsupported values.
  • authMechanismProperties is now validated and returns a client error for invalid or unsupported properties for the specified authentication mechanism.
  • authMechanismProperties now correctly supports ':' within property values.
    • Old behavior: authMechanismProperties=A:B,C:D:E,F:G is parsed as {'A': 'B', 'C': 'D:E,F:G'}.
    • New behavior: authMechanismProperties=A:B,C:D:E,F:G is parsed as {'A': 'B': 'C': 'D:E', 'F': 'G'}.
• Calling mongoc_bulk_operation_execute on the same mongoc_bulk_operation_t repeatedly is an error. Previously this was only discouraged in documentation.
• Consistently apply __cdecl calling convention to function declarations in public API. Intended to support consumers building their code using a different default calling convention with MSVC. The mongoc and bson libraries only support being built with the __cdecl default calling convention.
• mongoc_client_set_ssl_opts now ignores a pooled mongoc_client_t and logs an error. Use mongoc_client_pool_set_ssl_opts to set TLS options on a mongoc_client_pool_t before popping any clients.
• mongoc_client_set_ssl_stream_initiator now ignores a pooled mongoc_client_t and logs an error.
• The pkg-config files libmongoc-1.0, libmongoc-static-1.0, libbson-1.0, and libbson-static-1.0 have been renamed to mongoc2, mongoc2-static, bson2, and bson2-static, respectively.

CMake Packages and Imported Targets

The mongoc-1.0 (and bson-1.0) CMake packages have been removed. Instead, use
mongoc or bson, and specify a version or version range to be imported:

find_package(mongoc 1.30...2.0)

The new packages import different target names:

• mongo::mongoc_static → mongoc::static
• mongo::mongoc_shared → mongoc::shared
• The target mongoc::mongoc is a shim target that points to either the shared library or the static library.

The BSON library has had similar name changes.

Removals

• The bson_md5_t struct and associated API is removed.
• The client side matching feature, mongoc_matcher_t and related functions are removed.
• mongoc_server_description_ismaster is removed. Use the equivalent mongoc_server_description_hello instead.
• MONGOC_QUERY_SLAVE_OK is removed. Use the equivalent MONGOC_QUERY_SECONDARY_OK instead.
• MONGOC_URI_SLAVEOK is removed. It was unused.
• mongoc_client_command, mongoc_database_command, and mongoc_collection_command are removed. Use mongoc_client_command_simple, mongoc_database_command_simple, and mongoc_collection_command_simple instead.
• MONGOC_URI_MAXIDLETIMEMS and MONGOC_URI_WAITQUEUEMULTIPLE are removed. They were unused.
• bson_string_t and associated functions are removed.
• Support for ENABLE_SASL=CYRUS on Windows is removed. Use ENABLE_SASL=SSPI or ENABLE_SASL=OFF instead.
  • The associated Windows-only option CYRUS_PLUGIN_PATH_PREFIX is removed.
• Support for the deprecated minPoolSize URI option is removed along with associated API: MONGOC_URI_MINPOOLSIZE and mongoc_client_pool_min_size.
• Support for LibreSSL (the CMake option ENABLE_SSL=LIBRESSL) is removed. Associated API is removed (MONGOC_ENABLE_SSL_LIBRESSL and mongoc_stream_tls_libressl_new).
• MONGOC_WRITE_CONCERN_W_ERRORS_IGNORED (value -1) is removed. Use MONGOC_WRITE_CONCERN_W_UNACKNOWLEDGED (value 0) which is handled equivalently. If specified in a URI, replace: mongodb://host/?w=-1 with mongodb://host/?w=0.
• The deprecated CMake option ENABLE_AUTOMATIC_INIT_AND_CLEANUP is removed. See Initialization and cleanup for expected use of mongoc_init() and mongoc_cleanup().
• mongoc_client_get_database_names is removed. Use mongoc_client_get_database_names_with_opts instead.
• mongoc_client_find_databases is removed. Use mongoc_client_find_databases_with_opts instead.
• mongoc_client_get_max_message_size is removed.
• mongoc_client_get_max_bson_size is removed.
• Deprecated mongoc_apm_command_*_get_server_connection_id functions are removed. Use mongoc_apm_command_*_get_server_connection_id_int64 instead.
• Deprecated index management API is removed:
  • mongoc_collection_create_index_with_opts, mongoc_collection_create_index, and mongoc_collection_ensure_index are removed. Use mongoc_collection_create_indexes_with_opts instead.
  • mongoc_index_opt_t, mongoc_index_opt_geo_t mongoc_index_opt_wt_t are removed. Pass options using bson_t to mongoc_collection_create_indexes_with_opts instead.
  • mongoc_collection_find_indexes is removed. Use mongoc_collection_find_indexes_with_opts instead.
  • See MongoDB documentation for working with indexes.
• Deprecated cursor API is removed:
  • mongoc_cursor_is_alive is removed. Use the equivalent mongoc_cursor_more instead.
  • mongoc_cursor_set_hint is removed. Use the equivalent mongoc_cursor_set_server_id instead.
  • mongoc_cursor_get_hint is removed. Use the equivalent mongoc_cursor_get_server_id instead.
  • mongoc_cursor_new_from_command_reply is removed. Use mongoc_cursor_new_from_command_reply_with_opts instead.
• Deprecated CRUD API is removed:
  • mongoc_collection_save is removed. Use mongoc_collection_insert_one or mongoc_collection_replace_one instead.
  • mongoc_collection_delete is removed. Use mongoc_collection_delete_one or mongoc_collection_delete_many instead.
  • mongoc_delete_flags_t and mongoc_reply_flags_t are removed.
  • mongoc_collection_find is removed. Use mongoc_collection_find_with_opts instead.
  • mongoc_collection_insert_bulk is removed. Use mongoc_collection_insert_many instead.
  • mongoc_collection_create_bulk_operation is removed. Use mongoc_collection_create_bulk_operation_with_opts instead.
  • mongoc_collection_get_last_error is removed. To get results from write operations, instead use:
    • mongoc_collection_update_one
    • mongoc_collection_update_many
    • mongoc_collection_replace_one
    • mongoc_collection_delete_one
    • mongoc_collection_delete_many
    • mongoc_collection_insert_one
    • mongoc_collection_insert_many
    • mongoc_bulkwrite_t
    • mongoc_bulk_operation_t
  • mongoc_bulk_operation_delete is removed. Use mongoc_bulk_operation_remove() instead.
  • mongoc_bulk_operation_delete_one is removed. Use mongoc_bulk_operation_remove_one instead.
  • mongoc_bulk_operation_get_hint is removed. Use mongoc_bulk_operation_get_server_id instead.
  • mongoc_bulk_operation_set_hint is removed. Use mongoc_bulk_operation_set_server_id instead.
  • mongoc_collection_count and mongoc_collection_count_with_opts are removed. Use mongoc_collection_count_documents or mongoc_collection_estimated_document_count instead.
• mongoc_collection_stats is removed. Use the $collStats aggregation pipeline stage with mongoc_collection_aggregate instead.
• mongoc_collection_validate is removed. Run the validate command directly with mongoc_client_read_command_with_opts instead.
• Deprecated API for mongoc_database_t is removed:
  • mongoc_database_find_collections is removed. Use mongoc_database_find_collections_with_opts instead.
  • mongoc_database_get_collection_names is removed. Use mongoc_database_get_collection_names_with_opts instead.
• Deprecated GridFS API has been removed:
  • mongoc_gridfs_find is removed. Use mongoc_gridfs_find_with_opts instead.
  • mongoc_gridfs_find_one is removed. Use mongoc_gridfs_find_one_with_opts instead.
• Deprecated TLS stream API is removed:
  • mongoc_stream_tls_do_handshake is removed. Use mongoc_stream_tls_handshake instead.
  • mongoc_stream_tls_check_cert is removed. Use mongoc_stream_tls_handshake instead.
  • mongoc_stream_tls_new is removed. Use mongoc_stream_tls_new_with_hostname instead.
• Deprecated URI API has been removed:
  • mongoc_uri_get_service is removed. Use mongoc_uri_get_srv_hostname instead.
  • mongoc_uri_get_read_prefs is removed. Use mongoc_uri_get_read_prefs_t instead.
  • mongoc_uri_get_ssl is removed. Use mongoc_uri_get_tls instead.
• Deprecated write concern API is removed:
  • mongoc_write_concern_get_fsync is removed. Use mongoc_write_concern_get_journal instead.
  • mongoc_write_concern_set_fsync is removed. Use mongoc_write_concern_set_journal instead.
• The libmongoc-ssl-1.0 pkg-config file has been removed.

Forwarding headers (#include <bson.h> and #include <mongoc.h>)

The compatibility "forwarding" headers have been removed (previously added in 1.13.0). This means it is no longer valid to include the literal header names mongoc.h or bson.h directly:

#include <bson.h> // No longer provided!
#include <mongoc.h> // No longer provided!

Instead, the names must be prefixed with the parent directory: mongoc/mongoc.h and bson/bson.h:

#include <bson/bson.h>
#include <mongoc/mongoc.h>

mongoc_client_kill_cursor

mongoc_client_kill_cursor is removed. It did not accept a server identifier. It was only reliable when connected to a single server.

Sending killCursors is not typically needed. mongoc_cursor_t manages the cursor lifetime. If needed, use a generic command helper to manually send a killCursors command:

bson_t *cmd = BCON_NEW ("killCursors", "coll", "cursors", "[", BCON_INT64 (cursor_id), "]");
bool ok = mongoc_client_command_simple_with_server_id (client, "db", cmd, NULL, server_id, NULL, &error);
if (!ok) {
  printf ("Failed to send 'killCursors': %s\n", error.message);
}
bson_destroy (cmd);

mongoc_client_get_server_status

mongoc_client_get_server_status is removed. Use a command helper to run the "serverStatus" command instead:

bson_t *cmd = BCON_NEW("serverStatus", BCON_INT32(1));
if (!mongoc_client_command_simple(client, "db", cmd, NULL, &reply, &error)) {
    printf("Failed to send 'serverStatus': %s\n", error.message);
} else {
  // TODO: use `reply`
}
bson_destroy(&reply);
bson_destroy(cmd);

Links

• All the issues resolved in 2.0.0
• Documentation

v1 support notice

New features will no longer be added to the 1.x versions. Critical bug fixes and security patches will continue to be backported to 1.x versions until April 1, 2026. After this date, 1.x versions will not be maintained.

Contributors

Thanks to everyone who contributed to this release.

• Kevin Albertson
• Ezra Chung
• Colby Pike
• Micah Scott
• Jeroen Ooms
• Lin Raymond