What's New

Important: This release drops support for MongoDB Server version 4.0 and raises the minimum supported version to 4.2. We recommend making changes to your application to accommodate breaking changes. See the Release Notes section in the Server manual to learn more about upgrading.

Introduces support for version 3.0 of the BSON crate. By default, the driver uses version 2.15 for backwards compatibility. To use version 3.0, add the bson-3 feature to the features list for the driver crate in your project's Cargo.toml. BSON 3.0 updates several APIs in backwards-incompatible ways. The following changes might require updates to your application:

• Introduces a unified bson::error::Error type that consolidates error handling across the crate with consistent fields and granular error information.

• Adds &CStr and CString types for BSON keys and regular expressions to prevent null byte issues that previously caused panics. The following example shows how to update your code by using the &CStr and CString types:

  let mut computed_key = "foo".to_owned();
  computed_key.push_str("bar");
  // Non-static values need to be checked at runtime
  let computed_key = CString::try_from(computed_key)?;
  let doc_buf = rawdoc! {
     // String literal keys in `rawdoc!` are implicitly checked at compile-time.
     "hello": "world",
     computed_key: 42,
     "regex": Regex {
         // `&CStr` implements many common traits like `ToOwned`
         pattern: cstr!("needle").to_owned(),
         options: cstr!("").to_owned(),
     }
  };
  // `append` keys must now be a `&CStr` or `CString`.
  doc_buf.append(cstr!("a key"), "a value");

• Provides all conversions between raw types and their reference types via standard library traits.

• Makes serde an optional feature that is disabled by default. Serialization and deserialization functions now have serialize_to or deserialize_from prefixes for clarity.

• Simplifies UTF-8 lossy decoding with the Utf8Lossy wrapper type and new conversion methods.

• Updates serde helper functions to work with the serde_as annotation from the serde_with crate for more flexible type conversions. For more information, see Data Modeling and Serialization.

• For detailed instructions migrating from BSON 2.x to BSON 3.0, see the Migrating from 2.x to 3.0 guide on GitHub.

Important: The next minor release will drop support for MongoDB Server version 4.0 and raise the minimum supported version to 4.2. We recommend making changes to your application to accommodate breaking changes. See the Release Notes section in the Server manual to learn more about upgrading.

Increases the Minimum Supported Rust Version to 1.71.1. To learn more about driver compatibility, see the Compatibility page.

Marks the in-use encryption feature as stable with the same backwards compatibility guarantees as the driver. The feature flag is named in-use-encryption. This is a policy change and the API is not changed from the previous release.

Allows SRV hostnames with fewer than three parts.

Allows you to supply a sort option when performing update operations.

Adds OIDC authentication support for Kubernetes environments.

To use OIDC to authenticate from a Kubernetes environment, set the authMechanismProperties connection option to ENVIRONMENT:k8s in your connection string. You can use this feature when connecting to an environment running in Amazon's Elastic Kubernetes Service, Google Kubernetes Engine, or Azure Kubernetes Service.

Adds support for more than one Key Management Service (KMS) provider of the same type. To learn more about KMS providers, see Queryable Encryption in the MongoDB Server manual.

Adds support for v2 of the Queryable Encryption range protocol. Range indexes for Queryable Encryption are now GA.

Adds the type field to the SearchIndexModel type to allow programmatic creation of Atlas Search and Atlas Vector Search indexes. To learn more, see the Atlas Search and Vector Search Indexes guide.

Implements the Happy Eyeballs algorithm for managing TCP connections. To learn more about this algorithm, see the Rust documentation for the happy_eyeballs crate.

The driver publishes a TopologyDescriptionChangedEvent event when a topology closes.

Fixes an issue in which aggregations wouldn't compile when run within explicit sessions and also implemented custom types.

Fixes an issue in which the Collection::watch() method didn't use the type parameter of the Collection instance it was run on.

Implements a fluent API, which introduces the following syntax changes for passing options and starting sessions:

• To set asynchronous method options, chain option builder methods directly to the method call instead of passing an options struct parameter.

• To set synchronous method options, chain option builder methods to the method call, then call the run() method.

• If you must construct a separate options struct, chain the with_options() method to the method call and pass your options struct as a parameter.

• To start a session, chain the session() method to the method call instead of using a separate method that has a _with_session suffix.

Adds support for bulk write operations. To learn more about these operations, see the Bulk Operations guide.

Introduces the EventHandler type to reduce the amount of boilerplate code required for event monitoring. For examples that use the EventHandler type, see the guides in the Monitoring section.

Removes support for the async-std asynchronous runtime. To learn more about this change, see the Configure the Asynchronous Runtime section of the Asynchronous and Synchronous APIs guide.

Requires the use of a compat feature if a Rust driver application is compiled with the no-default-features command line flag. The rustls and dns-resolution features are now optional.

Removes support for the bson-* driver features. You can select these features by including bson as a direct dependency in your application.

Removes support for read and write concern constants. Instead, use helper methods to set ReadConcern and WriteConcern values.

Adds Send + Sync constraints to the Collection<T> type.

Removes the ClientOptions::compressor field if no compressor features are enabled.

Changes the type of ReadPreferenceOptions fields. These fields now have a Option<ReadPreferenceOptions> type.

Removes the CollectionOptions::human_readable_serialization option. Instead, use the bson::HumanReadable wrapper type to serialize user data into human-readable form.

Adds support for value conversion through the Into trait for all option struct builders.

Renames the comment_bson field to comment for AggregateOptions, FindOptions, and FindOneOptions structs.

Adds MongoDB Atlas Search index management methods. To learn more about these methods, see the Atlas Search and Vector Search Indexes guide.

Improves network connectivity and operation reliability by implementing the following behaviors:

• Performs retries on a greater range of error types that the driver encounters.

• Avoids retries for mongos instances experiencing network connectivity issues.

Adds the human_readable_serialization option to the CollectionOptions struct. This option instructs the driver to serialize values passed to CRUD methods as a human-readable format. The default value of this option is false.

Adds the run_cursor_command() method to run a database command and retrieve the response as a Cursor type. To learn more, see the Run a Command guide.

Adds SDAM event logging when you use the tracing-unstable feature flag.

Adds the following configurations for Client and connection management:

• max_connecting: an option that you can set in a ClientOptions struct to specify how many connections you can establish in parallel. To learn more about this option, see Connection Pool in the Performance Considerations guide.

• Client::warm_connection_pool(): a method that you can use to create new connections in the connection pool to provide more predictable performance. When you use this method, the driver attempts to create connections up to the number specified in the min_pool_size setting.

• Client::shutdown(): a method that you can use to stop background tasks and wait for handlers to drop. This method can be helpful if you use event handlers to reference external resources, as these handlers might be used in tasks even after the Client is closed.

Supports AWS Identity and Access Management (IAM) roles for service accounts, such as Elastic Kubernetes Service (EKS) accounts.

Supports GCP-attached service accounts when using the Cloud Key Management System (KMS).

Supports fetching on-demand CSFLE credentials from the Azure KMS.

Implements the FromStr trait for the Namespace struct. This change allows you to parse a string that includes a database and collection name, such as "testdb.testcollection" into a Namespace instance.

Includes the server_id in a ConnectionInfo struct as an i64 type.

Removes most type constraints on values referenced by a Cursor.

Updates the libmongocrypt version in the driver dependencies in order to use the Queryable Encryption feature with equality queries.