v2.5.0

The MongoDB Rust driver team is pleased to announce the v2.5.0 release of the mongodb crate, now available for download from crates.io.

Highlighted Changes

In-Use Encryption: Automatically Create Keys

This release adds the ClientEncryption::create_encrypted_collection helper method, which will automatically create encryption keys as needed when creating a collection with the encrypted_fields option.

Convenient Transactions

This release adds the ClientSession::with_transaction helper method, which will handle automatically creating, retrying, and committing or aborting a transaction.

Included Changes

Below are a selected list of changes with user impact; for a full list of changes see this GitHub query.

New Features

• RUST-1587 Implement server selection tracing events (#805)
• RUST-1314 Support on-demand AWS credentials for in-use encryption (#831)
• RUST-107 Convenient transactions (#849)
• RUST-1411 Add create_encrypted_collection helper (#853)

Improvements

• RUST-1069 Defer implicit session check out until after connection check out (#811)
• RUST-1582 Expose collection.client() as public (#822) (Thanks LuisOsta!)
• RUST-1503 Test csfle against older server versions (#832)
• RUST-1607: allow uuidRepresentation in connection string (#838) (Thanks terakilobyte!)
• RUST-1501 Collect FaaS platform metadata (#844)
• RUST-1585 Do not perform server selection to determine sessions support (#854)

Bugfixes

• RUST-1576 Allow "timeseries"-typed collections in list_collections output (#814)
• RUST-1574 Default errmsg field to empty string (#829)
• RUST-1632 provide a parse_async method (#855)

v2.4.0

The MongoDB Rust driver team is pleased to announce the v2.4.0 release of the mongodb crate, now available for download from crates.io.

Highlighted Changes

In-Use Encryption

This release brings support for Client-Side Field Level Encryption and Queryable Encryption. For detailed installation and usage instructions, please see the Encryption section of the driver manual. Please note that the API is currently unstable and may change in breaking ways in future releases.

GridFS

This release adds support for GridFS, allowing storage and retrieval of files that exceed the BSON document size limit. Please see the documentation of the new gridfs module for more information.

Streaming Monitoring Protocol

This release can now use the streaming monitoring protocol with MongoDB 4.4+ servers, reducing the time it takes for the client to discover server state changes compared to the old polling protocol.

Tracing Integration

The driver now emits tracing events at points of interest. To consume these events, you must enable the driver’s tracing-unstable feature flag and either:

• register a tracing Subscriber in your application (see the tracing docs), OR
• register a log-compatible logger in your application (see the log documentation for details), and enable a log compatibility feature flag for tracing, as detailed here.

This API is considered unstable as the tracing crate has not reached 1.0 yet; future minor versions of the driver may upgrade the tracing dependency to a new version which is not backwards-compatible with Subscribers that depend on older versions of tracing.

Events will be emitted under the following targets:

• mongodb::command: Events related to command execution starting, succeeding, or failing.
• mongodb::connection: Events related to the driver’s underlying connection pools and their connections.

Future work will introduce events under additional targets and may add driver-defined tracing spans for intervals of interest.

MSRV Increase

The minimum supported Rust version (MSRV) for this crate is now Rust 1.57.

Included Changes

Below are a selected list of changes with user impact; for a full list of changes see this GitHub query.

New Features

• RUST-1384 Implement auto encryption (#717)
• RUST-1385 Implement explicit encryption (#726)
• RUST-1305 Use uuid 1.x internally and add support for bson uuid 1.x (#709)
• RUST-1400 GridFS download methods (#747)
• RUST-1478 GridFS upload methods (#751)
• RUST-1401 Additional GridFS API (#763)
• RUST-580 Add tracing integration and command tracing events (#757)
• RUST-1510 Implement connection pool tracing messages (#766)

Improvements

• RUST-360 Streaming monitoring protocol (#721)
• RUST-1071 Add comment field to all options structs
• minor: improve compile error when sync and tokio-runtime features are enabled (#788)
• extend error types to impl serialization (#797) (Thanks borngraced!)

Bugfixes

• RUST-1443 Ensure monitors close after server is removed from topology (#744)
• RUST-1576 Allow "timeseries"-typed collections in list_collections output (#814)
• minor: fix documentation of new features (#823)

Tasks

• RUST-1253 Add AWS Lambda Examples (#714)
• Deps: bump dependencies (#722) (Thanks Some-Dood!)
• RUST-1445 Bump MSRV to 1.57 (#727)
• RUST-1403 Remove oldtime feature from chrono dependency (#691) (Thanks oskgo!)
• RUST-1450 Bump pretty_assertions dependency to 1.3.0 (#734)
• Fix typo in README (#735) (Thanks sgasse!)
• minor: document cursor/change stream Drop implementations (#745)
• RUST-1560 Fix README typo (#798) (Thanks lonesometraveler!)

v2.4.0-beta.2

The MongoDB Rust driver team is pleased to announce the v2.4.0-beta.2 release of the mongodb crate, now available for download from crates.io. Please note that this is a beta release; the API for in-use encryption may change between this and the final 2.4.0 release.

Highlighted Changes

This release fixes a bug that caused the documentation for in-use encryption not to render on docs.rs.

v2.4.0-beta.1

The MongoDB Rust driver team is pleased to announce the v2.4.0-beta.1 release of the mongodb crate, now available for download from crates.io. Please note that this is a beta release; the API for in-use encryption may change between this and the final 2.4.0 release.

Highlighted Changes

This release fixes a bug that could cause list_collections to fail when timeseries collections were present; see RUST-1576 for details.

v2.4.0-beta

The MongoDB Rust driver team is pleased to announce the v2.4.0-beta release of the mongodb crate, now available for download from crates.io. Please note that this is a beta release; the API for in-use encryption may change between this and the final 2.4.0 release.

Highlighted Changes

In-Use Encryption

This release brings support for Client-Side Field Level Encryption and Queryable Encryption. For detailed installation and usage instructions, please see the Encryption section of the driver manual. Please note that rewrapManyDataKey and automatic KMS credentials are not yet supported in the Rust driver.

GridFS

This release adds support for GridFS, allowing storage and retrieval of files that exceed the BSON document size limit. Please see the documentation of the new gridfs module for more information.

Streaming Monitoring Protocol

This release can now use the streaming monitoring protocol with MongoDB 4.4+ servers, reducing the time it takes for the client to discover server state changes compared to the old polling protocol.

Tracing Integration

The driver now emits tracing events at points of interest. To consume these events, you must enable the driver’s tracing-unstable feature flag and either:

• register a tracing Subscriber in your application (see the tracing docs), OR
• register a log-compatible logger in your application (see the log documentation for details), and enable a log compatibility feature flag for tracing, as detailed here.

This API is considered unstable as the tracing crate has not reached 1.0 yet; future minor versions of the driver may upgrade the tracing dependency to a new version which is not backwards-compatible with Subscribers that depend on older versions of tracing.

Events will be emitted under the following targets:

• mongodb::command: Events related to command execution starting, succeeding, or failing.
• mongodb::connection: Events related to the driver’s underlying connection pools and their connections.

Future work will introduce events under additional targets and may add driver-defined tracing spans for intervals of interest.

MSRV Increase

The minimum supported Rust version (MSRV) for this crate is now Rust 1.57.

Included Changes

Below are a selected list of changes with user impact; for a full list of changes see this GitHub query.

New Features

• RUST-1384 Implement auto encryption (#717)
• RUST-1385 Implement explicit encryption (#726)
• RUST-1305 Use uuid 1.x internally and add support for bson uuid 1.x (#709)
• RUST-1400 GridFS download methods (#747)
• RUST-1478 GridFS upload methods (#751)
• RUST-1401 Additional GridFS API (#763)
• RUST-580 Add tracing integration and command tracing events (#757)
• RUST-1510 Implement connection pool tracing messages (#766)

Improvements

• RUST-360 Streaming monitoring protocol (#721)
• RUST-1071 Add comment field to all options structs
• minor: improve compile error when sync and tokio-runtime features are enabled (#788)
• extend error types to impl serialization (#797) (Thanks borngraced!)

Bugfixes

• RUST-1443 Ensure monitors close after server is removed from topology (#744)

Tasks

• RUST-1253 Add AWS Lambda Examples (#714)
• Deps: bump dependencies (#722) (Thanks Some-Dood!)
• RUST-1445 Bump MSRV to 1.57 (#727)
• RUST-1403 Remove oldtime feature from chrono dependency (#691) (Thanks oskgo!)
• RUST-1450 Bump pretty_assertions dependency to 1.3.0 (#734)
• Fix typo in README (#735) (Thanks sgasse!)
• minor: document cursor/change stream Drop implementations (#745)
• RUST-1560 Fix README typo (#798) (Thanks lonesometraveler!)

v2.3.1

The MongoDB Rust driver team is pleased to announce the v2.3.1 release of the mongodb crate, now available for download from crates.io.

This release fixes a bug that caused connection establishment when using async-std to be blocking, and another bug that would cause the driver to attempt to continue monitoring servers that were removed from the topology.

Full Release Notes

Bugfixes

• [RUST-1464] - async-std connection establishment is blocking
• [RUST-1443] - Monitors do not exit when servers are removed from the topology

v2.3.0

The MongoDB Rust driver team is pleased to announce the v2.3.0 release of the mongodb crate, now available for download from crates.io.

Highlighted Changes

The following sections detail some of the major changes included in this release. For a full list of changes, see the Full Release Notes section below.

MSRV Increase (RUST-1263)

The minimum supported Rust version (MSRV) for this crate is now Rust 1.53.

MongoDB 6.0 Support

This release adds support for a number of new features added in MongoDB 6.0, including change streams with document pre- and post-images and clustered collections.

MongoDB 6.0 is now GA and available for use on MongoDB Atlas, and can also be downloaded here. Release notes for MongoDB 6.0 can be found here.

Changes to mongodb::Collection::estimated_document_count implementation (RUST-1216)

When adding support for MongoDB 5.0, the driver's implementation of estimated_document_count was changed from using the count command to the aggregate command with the $collStats aggregation stage. This change first appeared in our 2.0.0-alpha.1 release. This change inadvertently broke support for using this method on views, as they do not support using $collStats.
In this release, we have reverted that change, and estimated_document_count is now once again implemented using the count command.
Please note that due to an oversight, count was omitted from the MongoDB Stable API version 1 in MongoDB server versions 5.0.0-5.0.8 and 5.1.0-5.3.1. Consequently, users of the Stable API who use estimated_document_count are recommended to either upgrade their MongoDB clusters to 5.0.9+ or 5.3.2+ (if on Atlas), or to set ClientOptions.server_api.strict to false when constructing Clients.

New ConnectionString type

RUST-1193 introduced a new public mongodb::options::ConnectionString type, which models a MongoDB connection string. This type can be used to parse a connection string and inspect and manipulate its contents, and to initialize a mongodb::options::ClientOptions, and in turn a mongodb::Client.

For example:

use mongodb::{
    Client,
    options::{ClientOptions, ConnectionString},
};

let mut conn_str = ConnectionString::parse("mongodb://localhost:27017/?appName=myApp1")?;
println!("{:?}", conn_str.app_name); // prints: Some("myApp1")
conn_str.app_name = Some("newAppName".to_string());
println!("{:?}", conn_str.app_name); // prints: Some("newAppName")

let options = ClientOptions::parse_connection_string(conn_str).await?;
let client = Client::with_options(options)?;

The differences between a ConnectionString and ClientOptions are that:

1. ConnectionString only contains client options that are universal across MongoDB drivers and can be set via a MongoDB connection string, whereas ClientOptions also contains Rust driver-specific options,
2. When using a mongodb+srv connection string, initializing a ClientOptions will perform SRV and TXT lookup, whereas initializing a ConnectionString will not. Note that if a ConnectionString is initialized and then used to construct a ClientOptions or a Client, SRV/TXT lookup will be performed at that time.

Included Tickets

Below are a selected list of tickets with user impact; for a full list of completed tickets see this Jira query.

Bug

• [RUST-332] - Operations don't report errors for invalid setName in single topologies
• [RUST-1274] - commitTransaction retry sometimes fails with InvalidOptions error
• [RUST-1328] - ServerDescriptionChangedEvents for servers with errors always emitted even when description does not change
• [RUST-1337] - Significant performance regression in large reads

New Feature

• [RUST-910] - Add server connectionId to command monitoring events
• [RUST-1070] / [RUST-1145] - Support let option for multiple CRUD commands
• [RUST-1166] - Change streams support for user-facing PIT pre- and post-images
• [RUST-1193] - Introduce ConnectionString type
• [RUST-1215] - Add comment option to EstimatedDocumentCountOptions
• [RUST-1271] - Clustered Indexes for all Collections
• [RUST-1290] - Always report wallTime in the change stream event output

Task

• [RUST-1263] - Bump MSRV to 1.53
• [RUST-1311] - Bump maxWireVersion for MongoDB 6.0

Improvement

• [RUST-488] - Allow using both async and sync API
• [RUST-585] - Refactor Topology to use channels instead of locks
• [RUST-803] - Use "hello" command for monitoring if supported
• [RUST-1152] - Use hello command + OP_MSG when 'loadBalanced=True'
• [RUST-1168] - Do not error when parsing change stream event documents
• [RUST-1216] - Use the count command instead of collStats to implement estimated_document_count
• [RUST-616] - Raise an error if response messageLength > ismaster.maxMessageSizeBytes

v2.3.0-beta

The MongoDB Rust driver team is pleased to announce the v2.3.0-beta release of the mongodb crate.

Highlighted Changes

The following sections detail some of the major changes included in this release. For a full list of changes, see the Full Release Notes section below.

MSRV Increase (RUST-1263)

The minimum supported Rust version (MSRV) for this crate is now Rust 1.53.

MongoDB 6.0 Support

This release adds support for a number of new features added in MongoDB 6.0, including change streams with document pre- and post-images and clustered collections.

The latest release candidate for MongoDB 6.0 is currently available for download here as well as on MongoDB Atlas.

Changes to mongodb::Collection::estimated_document_count implementation (RUST-1216)

When adding support for MongoDB 5.0, the driver's implementation of estimated_document_count was changed from using the count command to the aggregate command with the $collStats aggregation stage. This change first appeared in our 2.0.0-alpha.1 release. This change inadvertently broke support for using this method on views, as they do not support using $collStats.
In this release, we have reverted that change, and estimated_document_count is now once again implemented using the count command.
Please note that due to an oversight, count was omitted from the MongoDB Stable API version 1 in MongoDB server versions 5.0.0-5.0.8 and 5.1.0-5.3.1. Consequently, users of the Stable API who use estimated_document_count are recommended to either upgrade their MongoDB clusters to 5.0.9+ or 5.3.2+ (if on Atlas), or to set ClientOptions.server_api.strict to false when constructing Clients.

New ConnectionString type

RUST-1193 introduced a new public mongodb::options::ConnectionString type, which models a MongoDB connection string. This type can be used to parse a connection string and inspect and manipulate its contents, and to initialize a mongodb::options::ClientOptions, and in turn a mongodb::Client.

For example:

use mongodb::{
    Client,
    options::{ClientOptions, ConnectionString},
};

let mut conn_str = ConnectionString::parse("mongodb://localhost:27017/?appName=myApp1")?;
println!("{:?}", conn_str.app_name); // prints: Some("myApp1")
conn_str.app_name = Some("newAppName".to_string());
println!("{:?}", conn_str.app_name); // prints: Some("newAppName")

let options = ClientOptions::parse_connection_string(conn_str).await?;
let client = Client::with_options(options)?;

The differences between a ConnectionString and ClientOptions are that:

1. ConnectionString only contains client options that are universal across MongoDB drivers and can be set via a MongoDB connection string, whereas ClientOptions also contains Rust driver-specific options,
2. When using a mongodb+srv connection string, initializing a ClientOptions will perform SRV and TXT lookup, whereas initializing a ConnectionString will not. Note that if a ConnectionString is initialized and then used to construct a ClientOptions or a Client, SRV/TXT lookup will be performed at that time.

Included Tickets

Below are a selected list of tickets with user impact; for a full list of completed tickets see this Jira query.

Bug

• [RUST-332] - Operations don't report errors for invalid setName in single topologies
• [RUST-1274] - commitTransaction retry sometimes fails with InvalidOptions error
• [RUST-1328] - ServerDescriptionChangedEvents for servers with errors always emitted even when description does not change
• [RUST-1337] - Significant performance regression in large reads

New Feature

• [RUST-1166] - Change streams support for user-facing PIT pre- and post-images
• [RUST-1193] - Introduce ConnectionString type
• [RUST-1271] - Clustered Indexes for all Collections
• [RUST-1290] - Always report 'wallTime' in the change stream event output

Task

• [RUST-1263] - Bump MSRV to 1.53
• [RUST-1311] - Bump maxWireVersion for MongoDB 6.0

Improvement

• [RUST-488] - Allow using both async and sync API
• [RUST-585] - Refactor Topology to use channels instead of locks
• [RUST-803] - Use "hello" command for monitoring if supported
• [RUST-1152] - Use hello command + OP_MSG when 'loadBalanced=True'
• [RUST-1168] - Do not error when parsing change stream event documents
• [RUST-1216] - Use the count command instead of collStats to implement estimatedDocumentCount

v2.2.2

Description

The MongoDB Rust driver team is pleased to announce the 2.2.2 release of the mongodb crate. This release fixes a performance regression introduced in 2.2.0 for large reads when using rustls. It also fixes a rare bug that can cause commitTransaction retries to fail.

Full Release Notes

Bugfixes

• RUST-1337 Use tokio's AsyncRead and AsyncWrite traits (#669)
  • This change fixes the performance regression mentioned above.
• RUST-1274 Fix commitTransaction on checkout retries (#651)

v2.2.1

The MongoDB Rust driver team is pleased to announce the v2.2.1 release of the mongodb crate.

This release includes a single change that upgrades the version of our rustc_version_runtime dependency from 0.1.4 to 0.2.1. The older version of rustc_version_runtime would create a file in the crate's src directory as part of the build process, which meant building the crate would fail on read-only file systems such as that used by docs.rs in the documentation process.

Included tickets

• [RUST-1272] - docs.rs failed to build mongodb-2.2.0