Releases: mongodb/mongo-rust-driver
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 Client
s.
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:
ConnectionString
only contains client options that are universal across MongoDB drivers and can be set via a MongoDB connection string, whereasClientOptions
also contains Rust driver-specific options,- When using a
mongodb+srv
connection string, initializing aClientOptions
will perform SRV and TXT lookup, whereas initializing aConnectionString
will not. Note that if aConnectionString
is initialized and then used to construct aClientOptions
or aClient
, 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 withInvalidOptions
error - [RUST-1328] -
ServerDescriptionChangedEvent
s 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 toEstimatedDocumentCountOptions
- [RUST-1271] - Clustered Indexes for all Collections
- [RUST-1290] - Always report
wallTime
in the change stream event output
Task
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 Client
s.
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:
ConnectionString
only contains client options that are universal across MongoDB drivers and can be set via a MongoDB connection string, whereasClientOptions
also contains Rust driver-specific options,- When using a
mongodb+srv
connection string, initializing aClientOptions
will perform SRV and TXT lookup, whereas initializing aConnectionString
will not. Note that if aConnectionString
is initialized and then used to construct aClientOptions
or aClient
, 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
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
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
v2.2.0
Description
The MongoDB Rust driver team is pleased to announce the v2.2.0 release of the mongodb
crate.
Highlighted Changes
The following sections detail some of the more important changes included in this release. For a full list of changes, see the Full Release Notes section below.
Change Streams (RUST-521, RUST-74, RUST-522, RUST-1149, RUST-523, RUST-1104)
This release adds support for Change Streams, which allow applications to access real-time data changes without the complexity and risk of tailing the oplog. Applications can use change streams to subscribe to all data changes on a single collection, a database, or an entire deployment, and immediately react to them.
let mut change_stream = coll.watch(None, None).await?;
let coll_ref = coll.clone();
task::spawn(async move {
coll_ref.insert_one(doc! { "x": 1 }, None).await;
});
while let Some(event) = change_stream.next().await.transpose()? {
println!("operation performed: {:?}, document: {:?}", event.operation_type, event.full_document);
// operation performed: Insert, document: Some(Document({"x": Int32(1)}))
}
Raw BSON Incorporation (RUST-1133, RUST-1175)
This release uses the new raw BSON types introduced in v2.2 of the bson
crate for internal operations, boosting performance in certain circumstances. It also allows for zero-copy deserialization when working with cursors via the new Cursor::deserialize_current
method:
use serde::Deserialize;
#[derive(Debug, Deserialize)]
struct Cat<'a> {
#[serde(borrow)]
name: &'a str
}
let coll = db.collection::<Cat>("cat");
let mut cursor = coll.find(None, None).await?;
while cursor.advance().await? {
println!("{:?}", cursor.deserialize_current()?);
}
MSRV and Dependency Update (RUST-1192, RUST-1220)
This release updates the version of all dependencies used by the Rust driver to their most recent, which required an update of the MSRV to 1.51.
OpenSSL Support (RUST-1083)
This release adds optional support for using OpenSSL for TLS streams via the new openssl-tls
feature. Note that rustls
is still required as a dependency in this case to avoid breaking backwards compatibility; this will be removed in a future major version release.
Full Release Notes
New Features
- RUST-521 Implement naive streaming and resume token caching for change streams (#531)
- RUST-1133 Update driver to use the raw BSON API (#546)
- RUST-74 Add cluster_time to ChangeStreamEvent (#548)
- RUST-522 Implement resume functionality for change streams (#547)
- RUST-1149 Prose tests for change streams. (#561)
- RUST-523 Support change streams in unified spec tests (#564)
- RUST-1104 sync wrapper for the change stream API (#566)
- RUST-1106 Make the change streams API visible (#571)
- RUST-43 Add change streams examples for documentation (#572)
- RUST-1138 Add bson-serde_with feature flag (#580)
- RUST-1175 Support zero-copy deserialization from cursors (#579)
- RUST-995 Add tokio-sync feature flag (#578)
- RUST-1083 Add openssl as an optional TLS provider (#590)
Bugfixes
- minor: derive TypedBuilder for TimeseriesOptions (#557)
- minor: fix external crate links (#552)
- RUST-1163 Fix load balancer tests (#576)
- RUST-812 Reduce flakiness of in_window::load_balancing_test (#568)
- RUST-1163 Fix load balancer auth tests (#581)
- RUST-1268 Use rustc_version_runtime for runtime metadata (#622)
Improvements
- RUST-1088 Always specify error labels at the top level (#553)
- RUST-894 Unskip write_error::details test on sharded clusters (#526)
- RUST-395 Log skipped tests (#523)
- RUST-1143 Bump max wire version to 15 (#573)
- RUST-1077 Update read/write concern document tests (#567)
- RUST-1173 Replace "Versioned API" references with "Stable API" (#585)
- RUST-1192 Bump MSRV to 1.49.0 (#584)
- RUST-1207 Bump zstd to v0.10 (#588) (thanks @moy2010!)
- RUST-1220 Bump outdated dependencies (#596)
- RUST-886 Use lossy UTF-8 decoding for responses to insert and update commands (#601)
- RUST-803 Conditionally use hello for monitoring (#600)
- RUST-1064 Retry on handshake failure (#598)
v2.2.0-beta
Description
The MongoDB Rust driver team is pleased to announce the v2.2.0-beta release of the mongodb
crate.
Highlighted Changes
The following sections detail some of the more important changes included in this release. For a full list of changes, see the Full Release Notes section below.
Change Streams (RUST-521, RUST-74, RUST-522, RUST-1149, RUST-523, RUST-1104)
This release adds support for Change Streams, which allow applications to access real-time data changes without the complexity and risk of tailing the oplog. Applications can use change streams to subscribe to all data changes on a single collection, a database, or an entire deployment, and immediately react to them.
let mut change_stream = coll.watch(None, None).await?;
let coll_ref = coll.clone();
task::spawn(async move {
coll_ref.insert_one(doc! { "x": 1 }, None).await;
});
while let Some(event) = change_stream.next().await.transpose()? {
println!("operation performed: {:?}, document: {:?}", event.operation_type, event.full_document);
// operation performed: Insert, document: Some(Document({"x": Int32(1)}))
}
Raw BSON Incorporation (RUST-1133, RUST-1175)
This release uses the new raw BSON types introduced in v2.2 of the bson
crate for internal operations, boosting performance in certain circumstances. It also allows for zero-copy deserialization when working with cursors via the new Cursor::deserialize_current
method:
use serde::Deserialize;
#[derive(Debug, Deserialize)]
struct Cat<'a> {
#[serde(borrow)]
name: &'a str
}
let coll = db.collection::<Cat>("cat");
let mut cursor = coll.find(None, None).await?;
while cursor.advance().await? {
println!("{:?}", cursor.deserialize_current()?);
}
MSRV and Dependency Update (RUST-1192, RUST-1220)
This release updates the version of all dependencies used by the Rust driver to their most recent, which required an update of the MSRV to 1.51.
OpenSSL Support (RUST-1083)
This release adds optional support for using OpenSSL for TLS streams via the new openssl-tls
feature. Note that rustls
is still required as a dependency in this case to avoid breaking backwards compatibility; this will be removed in a future major version release.
Full Release Notes
New Features
- RUST-521 Implement naive streaming and resume token caching for change streams (#531)
- RUST-1133 Update driver to use the raw BSON API (#546)
- RUST-74 Add cluster_time to ChangeStreamEvent (#548)
- RUST-522 Implement resume functionality for change streams (#547)
- RUST-1149 Prose tests for change streams. (#561)
- RUST-523 Support change streams in unified spec tests (#564)
- RUST-1104 sync wrapper for the change stream API (#566)
- RUST-1106 Make the change streams API visible (#571)
- RUST-43 Add change streams examples for documentation (#572)
- RUST-1138 Add bson-serde_with feature flag (#580)
- RUST-1175 Support zero-copy deserialization from cursors (#579)
- RUST-995 Add tokio-sync feature flag (#578)
- RUST-1083 Add openssl as an optional TLS provider (#590)
Bugfixes
- minor: derive TypedBuilder for TimeseriesOptions (#557)
- minor: fix external crate links (#552)
- RUST-1163 Fix load balancer tests (#576)
- RUST-812 Reduce flakiness of in_window::load_balancing_test (#568)
- RUST-1163 Fix load balancer auth tests (#581)
Improvements
- RUST-1088 Always specify error labels at the top level (#553)
- RUST-894 Unskip write_error::details test on sharded clusters (#526)
- RUST-395 Log skipped tests (#523)
- RUST-1143 Bump max wire version to 15 (#573)
- RUST-1077 Update read/write concern document tests (#567)
- RUST-1173 Replace "Versioned API" references with "Stable API" (#585)
- RUST-1192 Bump MSRV to 1.49.0 (#584)
- RUST-1207 Bump zstd to v0.10 (#588) (thanks @moy2010!)
- RUST-1220 Bump outdated dependencies (#596)
- RUST-886 Use lossy UTF-8 decoding for responses to insert and update commands (#601)
- RUST-803 Conditionally use hello for monitoring (#600)
- RUST-1064 Retry on handshake failure (#598)
v2.1.0
Description
The MongoDB Rust driver team is pleased to announce the v2.1.0
release of the mongodb
crate. This release contains a number of new features, bug fixes, and improvements, most notably support for Atlas Serverless.
Highlighted changes
The following sections detail some of the more important breaking changes included in this release. For a full list of changes, see the Full Release Notes section below.
Update dependency on bson
to v2.1.0
The exported version of bson
was updated to v2.1.0
, which includes its own set of changes. Check out the bson
release notes for more information.
Support for Atlas Serverless (RUST-653, RUST-983)
This release introduces load balancer support to the Rust driver, which enables it to be used with Atlas Serverless. As part of that, the test suite of the driver was updated to include testing against live Atlas Serverless instances to ensure full compatibility.
Wire protocol compression (RUST-54)
This release adds optional support for compressing the messages sent between the driver and the server. The available compression algorithms are zstd, snappy, and zlib, and they can be enabled via the zstd-compression
, snappy-compression
, and zlib-compression
feature flags respectively. By default, none of the feature flags are enabled.
let mut options = ClientOptions::parse("mongodb://localhost:27017").await?;
// the server will select the algorithm it supports from the list provided by the driver
options.compressors = Some(vec![
Compressor::Snappy,
Compressor::Zlib {
level: Default::default(),
},
Compressor::Zstd {
level: Default::default(),
},
]);
let client = Client::with_options(options)?;
let resp = client
.database("admin")
.run_command(
doc! {
"ping": 1
},
None,
)
.await?;
println!("{}", resp);
Causal consistency (RUST-48)
This release adds driver support for causal consistency and enables it by default on all ClientSession
s. For more information on the guarantees provided by causal consistency, check out the MongoDB manual.
let options = SessionOptions::builder().causal_consistency(true).build();
let mut session = client.start_session(Some(options)).await?;
let coll_options = CollectionOptions::builder()
.read_concern(ReadConcern::majority())
.write_concern(WriteConcern::builder().w(Acknowledgment::Majority).build())
.build();
let collection = client
.database("foo")
.collection_with_options("bar", coll_options);
collection
.insert_one_with_session(doc! { "read": "me" }, None, &mut session)
.await?;
collection
.find_one_with_session(doc! { "read": "me" }, None, &mut session)
.await?
.expect("causal consistency guarantees we can read our own writes");
Full Release Notes
New Features
- RUST-653 Load Balancer Support (#415, #421, #422, #495, #446, #461, #469, #470, #465, #473, #477, #480, #495, #510)
- RUST-903 Serverless Testing (#494, #497, #505, #504)
- RUST-48 Causal consistency support (#493)
- RUST-54 Add support for reading and writing OP_COMPRESSED (#476)
- RUST-1048 Expose the default database from Client and ClientOptions (#488) (thanks @WindSoilder!)
- RUST-892 Implement
FromStr
forServerAddress
(#458)
Bugfixes
- RUST-1122 Fix x509 auth for pkcs8 keys and Atlas free tier (#532) (thanks for reporting @Zageron!)
- RUST-856 Fix race between server selection and server monitoring (#460)
- RUST-992 Fix default authSource for PLAIN authentication (#451)
- RUST-1037 secondaryPreferred read preference is not forwarded to mongos (#480)
- RUST-1046 Fix iteration of session cursors when batchSize doesn't divide result size (#483)
- RUST-1047 Ensure
TopologyClosedEvent
is the last SDAM event emitted (#485) - RUST-1060 Omit non-pub fields from
Debug
output ofClientOptions
(#512)
Improvements
- RUST-993 Implement
Clone
forCollection<T>
even whenT
isn'tClone
(#454) - RUST-949 Use SDAM monitoring in auth_error test
- RUST-1021 Use
ServerAddress::parse
for URI parsing (#471) - RUST-1032 Avoid redundant allocations in
Collection::clone_with_type
(#467) (thanks @PhotonQuantum!) - RUST-1076 Remove conditional definition of driver modules (#511)
- RUST-807 Disallow maxPoolSize=0 (#491)
- RUST-1027 Update maxWireVersion to 14 in support of 5.1 (#503)
- RUST-1076 Remove conditional module definitions (#511)
Task
v1.2.5
v2.1.0-beta
Description
The MongoDB Rust driver team is pleased to announce the v2.1.0-beta
release of the mongodb
crate. This release is a preview of the upcoming v2.1.0
release, which will be functionally the same but may contain fixes for any bugs identified in this beta. This release contains a number of new features, bug fixes, and improvements, most notably support for Atlas Serverless.
Highlighted changes
The following sections detail some of the more important breaking changes included in this release. For a full list of changes, see the Full Release Notes section below.
Update dependency on bson
to v2.1.0-beta
The exported version of bson
was updated to v2.1.0-beta
, which includes its own set of changes. Check out the bson
release notes for more information.
Support for Atlas Serverless (RUST-653, RUST-983)
This release introduces load balancer support to the Rust driver, which enables it to be used with Atlas Serverless. As part of that, the test suite of the driver was updated to include testing against live Atlas Serverless instances to ensure full compatibility.
Wire protocol compression (RUST-54)
This release adds optional support for compressing the messages sent between the driver and the server. The available compression algorithms are zstd, snappy, and zlib, and they can be enabled via the zstd-compression
, snappy-compression
, and zlib-compression
feature flags respectively. By default, none of the feature flags are enabled.
let mut options = ClientOptions::parse("mongodb://localhost:27017").await?;
// the server will select the algorithm it supports from the list provided by the driver
options.compressors = Some(vec![
Compressor::Snappy,
Compressor::Zlib {
level: Default::default(),
},
Compressor::Zstd {
level: Default::default(),
},
]);
let client = Client::with_options(options)?;
let resp = client
.database("admin")
.run_command(
doc! {
"ping": 1
},
None,
)
.await?;
println!("{}", resp);
Causal consistency (RUST-48)
This release adds driver support for causal consistency and enables it by default on all ClientSession
s. For more information on the guarantees provided by causal consistency, check out the MongoDB manual.
let options = SessionOptions::builder().causal_consistency(true).build();
let mut session = client.start_session(Some(options)).await?;
let coll_options = CollectionOptions::builder()
.read_concern(ReadConcern::majority())
.write_concern(WriteConcern::builder().w(Acknowledgment::Majority).build())
.build();
let collection = client
.database("foo")
.collection_with_options("bar", coll_options);
collection
.insert_one_with_session(doc! { "read": "me" }, None, &mut session)
.await?;
collection
.find_one_with_session(doc! { "read": "me" }, None, &mut session)
.await?
.expect("causal consistency guarantees we can read our own writes");
Full Release Notes
New Features
- RUST-653 Load Balancer Support (#415, #421, #422, #495, #446, #461, #469, #470, #465, #473, #477, #480, #495, #510)
- RUST-903 Serverless Testing (#494, #497, #505, #504)
- RUST-48 Causal consistency support (#493)
- RUST-54 Add support for reading and writing OP_COMPRESSED (#476)
- RUST-1048 Expose the default database from Client and ClientOptions (#488) (thanks @WindSoilder!)
- RUST-892 Implement
FromStr
forServerAddress
(#458)
Bugfixes
- RUST-856 Fix race between server selection and server monitoring (#460)
- RUST-992 Fix default authSource for PLAIN authentication (#451)
- RUST-1037 secondaryPreferred read preference is not forwarded to mongos (#480)
- RUST-1046 Fix iteration of session cursors when batchSize doesn't divide result size (#483)
- RUST-1047 Ensure
TopologyClosedEvent
is the last SDAM event emitted (#485) - RUST-1060 Omit non-pub fields from
Debug
output ofClientOptions
(#512)
Improvements
- RUST-993 Implement
Clone
forCollection<T>
even whenT
isn'tClone
(#454) - RUST-949 Use SDAM monitoring in auth_error test
- RUST-1021 Use
ServerAddress::parse
for URI parsing (#471) - RUST-1032 Avoid redundant allocations in
Collection::clone_with_type
(#467) (thanks @PhotonQuantum!) - RUST-1076 Remove conditional definition of driver modules (#511)
- RUST-807 Disallow maxPoolSize=0 (#491)
- RUST-1027 Update maxWireVersion to 14 in support of 5.1 (#503)
- RUST-1076 Remove conditional module definitions (#511)