v2.0.0-beta.1

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.1 release of the mongodb crate. This is the second beta release in preparation for the 2.0.0 stable release, and it contains a few breaking changes, new features, API improvements, and bug fixes that were not included in the first beta. As with the previous beta, we do not intend to make any further breaking changes before v2.0.0, but we may do so in another beta if any issues arise before then.

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.

Update version of bson to v2.0.0-beta.1

The exported version of bson was updated to v2.0.0-beta.1, which includes its own set of breaking changes. Check out the bson release notes for more information.

Note: chrono and uuid public API components are now gated behind the "bson/chrono-0_4" and "bson/uuid-0_8" feature flags respectively.

Replica Set Transactions (RUST-90)

This release adds driver support the for replica set transactions, which are supported in MongoDB 4.0+. Transactions require the use of a ClientSession, which was introduced in a previous release. Each operation in the transaction must pass the ClientSession into it via the _with_session suffixed version of the operation. For more information and detailed examples, see the ClientSession documentation.

use mongodb::options::{Acknowledgment, ReadConcern, TransactionOptions};
use mongodb::{
    bson::{doc, Document},
    options::WriteConcern,
};

let mut session = client.start_session(None).await?;

let txn_options = TransactionOptions::builder()
    .write_concern(WriteConcern::builder().w(Acknowledgment::Majority).build())
    .read_concern(ReadConcern::majority())
    .build();

session.start_transaction(txn_options).await?;
collection
    .insert_one_with_session(doc! { "x": 1 }, None, &mut session)
    .await?;
collection
    .delete_one_with_session(doc! { "x": 2 }, None, &mut session)
    .await?;
session.commit_transaction().await?;

The "snapshot" read concern level was also introduced as part of this feature.

Reduce the default max_pool_size to 10 (RUST-823)

In prior versions of the driver, the default max_pool_size was 100, but this is likely far too high to be a default. For some background on the motivation, see here and here. Note that this is also in line with the defaults for r2d2 and bb8.

Full Release Notes

New features

• RUST-90 Implement Replica Set transactions
• RUST-824 Add Snapshot variant to ReadConcernLevel enum

Improvements

• RUST-811 Add feature flags for chrono and uuid interop in bson (breaking)
• RUST-823 Reduce the default max_pool_size to 10 (breaking)
• RUST-830 Consolidate error labels to Error::labels (breaking)
• minor: update semver to 1.0 (thanks @dtolnay!)

v2.0.0-beta

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta release of the driver. This release contains a number of breaking changes, API improvements, new features, and bug fixes. We do not intend to make any further breaking changes before the v2.0.0 stable release, though we may do so if needed.

Highlighted breaking 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.

Update version of bson to v2.0.0-beta

The exported version of bson was updated to v2.0.0-beta, which includes its own set of breaking changes. Check out the bson release notes for more information.

Ensure API meets the Rust API Guidelines (RUST-765)

There is a community-maintained list of API guidelines that every stable Rust library is recommended to meet. The driver's current API wasn't conforming to these guidelines exactly, so a number of improvements were made to ensure that it does. Here we highlight a few of the more important changes made in this effort.

Various error API improvements (RUST-739, RUST-765)

Several improvements were made to the ErrorKind enum according to the guidelines to provide a more consistent and stable API:

• The variants no longer wrap error types from unstable dependencies (C-STABLE)
• The variant are named more consistently (C-WORD-ORDER)
  • Drop redundant Error suffix from each variant name
• Redundant error variants were consolidated

The total list of breaking changes is as follows:

• All error variants dropped the "Error" suffix (e.g. ErrorKind::ServerSelectionError => ErrorKind::ServerSelection)
• ErrorKind::ArgumentError => ErrorKind::InvalidArgument
  • ErrorKind::InvalidHostname => removed, consolidated into ErrorKind::InvalidArgument
• ErrorKind::BsonDecode => ErrorKind::BsonDeserialization
• ErrorKind::BsonEncode => ErrorKind::BsonSerialization
• ErrorKind::ResponseError => ErrorKind::InvalidResponse
• ErrorKind::DnsResolve(trust_dns_resolver::error::ResolveError) => ErrorKind::DnsResolve { message: String }
  • ErrorKind::InvalidDnsName => removed, consolidated into ErrorKind::DnsResolve
  • ErrorKind::NoDnsResults => removed, consolidated into ErrorKind::DnsResolve
  • ErrorKind::SrvLookupError => removed, consolidated into ErrorKind::DnsResolve
  • ErrorKind::TxtLookupError => removed, consolidated into ErrorKind::DnsResolve
• ErrorKind::RustlsConfig(rustls::TLSerror) => ErrorKind::InvalidTlsConfig { message: String }
  • ErrorKind::ParseError => removed, consolidated into ErrorKind::InvalidTlsConfig
• ErrorKind::WaitQueueTimeoutError => removed, the wait_queue_timeout option is no longer supported (RUST-757)
• ErrorKind::OperationError => removed, consolidated into ErrorKind::InvalidResponse and ErrorKind::Internal as appropriate

Stabilize or eliminate public dependencies on unstable types (C-STABLE, RUST-739)

The driver included types from a number of unstable (pre-1.0) dependencies in its public API, which presented a problem for the stability of the driver itself. tokio was one such example of this, which is why when it went 1.0, the driver needed a 2.0 release. In an effort to ensure that the driver will no longer be subject to the semver breaks of unstable dependencies and can stay on 2.0 for the foreseeable future, the public dependencies on unstable types were removed altogether or stabilized such that they will always be present.

Here are the notable changes made as part of that:

• Cursor types now implement the Stream trait from futures-core rather than futures.
  • futures-core will be moving directly to 1.0 next, whereas futures may have several semver-incompatible versions.
  • The 2.0 version of the driver will continue to depend on futures-core 0.3 (current release), even after futures-core 1.0 is released and/or the Stream trait is included in the standard library. The cursor types will also implement each of the Stream traits from futures-core 1.0 and std as necessary, and users can depend on and import the one they wish to use.
  • It's possible no changes will need to be made in the driver to transition to std::Stream. See (rust-lang/futures-rs#2362)
• ErrorKind variants that wrapped unstable errors were removed or refactored (see above)
• Introduced a ResolverConfig type that opaquely wraps a trust_dns_resolver::ResolverConfig
• TlsOptions::into_rustls_config was removed from the public API

Wrap Error::kind in a Box (RUST-742)

In v2.0.0-alpha.1, we removed the Arc wrapper around Error::kind in order to improve the ergonomics of our Error type. The ErrorKind enum is quite large, however, which in turn made Error and mongodb::error::Result large too. In order to balance the ergonomics improvements of having an owned Error::kind with the small size of an Arc wrapped Error::kind, we decided to wrap it in a Box. This reduces the size of Error greatly while also allowing users to get an owned ErrorKind if they wish via the * operator.

Options builders Improvements (RUST-615)

The driver uses the typed-builder crate to generate the builders for its various options structs (e.g. ClientOptions::builder()). In this release, we updated its version to 0.9.0 and with that, introduced the following improvements:

• the builder methods for Option<T> fields now accept T instead of impl Into<Option<T>>
  • previously, every method required impl Into<T>, so fields that were options required the explicit Some(...) to enable type inference on the interior type.
  • As part of this, the builder methods for T also just accept T, rather than Into<T>, allowing for type inference
• incomplete .build() and repeated setters will now issue improved errors via deprecation warnings. See the typed-builder documentation for more information.

// old
let options = ClientOptions::builder()
    .hosts(vec![StreamAddress {
        hostname: "localhost".to_string(),
        port: Some(27017),
    }])
    .read_concern(Some(ReadConcernLevel::Local.into()))
    .build();
                             
// new
let options = ClientOptions::builder()
    .hosts(vec![ServerAddress::Tcp {
        host: "localhost".to_string(),
        port: Some(27017),
    }])
    .read_concern(ReadConcernLevel::Local.into())
    .build();

Accept impl Borrow<T> in various CRUD methods (RUST-754)

Prior to this release, methods such as Collection::insert_one accepted an owned T despite not actually requiring ownership of the value. This could lead to wasteful clones that hurt performance. As an improvement, these methods were updated to accept impl Borrow<T>, which means either owned or borrowed types may be passed in.

Return types that implement Deserialize from Client::list_databases and Database::list_collections (RUST-740)

These methods used to return Vec<Document> and Cursor<Document> respectively, both of which do not take advantage of the fact that the format of the returned documents is known and stable. To improve on that, these methods were updated to return Vec<DatabaseSpecification> and Cursor<CollectionSpecification> instead, which should make the responses more ergonomic to work with.

Refactor StreamAddress (RUST-760)

StreamAddress was used to specify via the ClientOptions which hosts the driver was to connect to. This type was inaccurate though, since it usually contains DNS names that get resolved to one or more socket addresses rather than the socket address itself. Furthermore, in the future the driver may want to support other ways of connecting to MongoDB servers, such as Unix Domain Sockets, which would further make the StreamAddress name confusing. To improve the accuracy of the type's name enable it to be more easily extended in the future, it was refactored to the following type:

#[non_exhaustive]
pub enum ServerAddress {
    Tcp { host: String, port: Option<u16> }
}

This is similar to the equivalent types provided by the tokio-postgres and redis crates.

Note: this change only affects users that construct their own ClientOptions structs (as opposed to parsing them from a connection string) or consumers of CMAP events.

Full Release Notes

New features

• RUST-808 Upgrade bson to 2.0.0-beta (breaking)
• RUST-615 Upgrade typed-builder to 0.9.0 (breaking)
• RUST-738 Implement Clone on BSON error types (breaking)
• RUST-740 Return Deserialize types from list_databases and list_collections (breaking)
• RUST-754 Accept references in insert and replace methods (breaking)
• RUST-796 Provide easy way to reborrow session in between cursor iterations (breaking)

Improvements

• RUST-739 Don't re-export types from unstable dependencies (breaking)
• RUST-742 Reduce size of Error and ErrorKind (breaking)
• RUST-760 Refactor StreamAddress to ServerAddress enum (breaking)
• RUST-757 Remove wait_queue_timeout (breaking)
• RUST-761 Rename CreateCollectionOptions::validation to CreateCollectionOptions::validator (breaking)
• RUST-764 Use unsigned integers for values that should always be positive (breaking)
• RUST-765 Ensure API fol...

v2.0.0-alpha.1

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-alpha.1 release of the driver. This is the second alpha release in preparation for the 2.0 version of the driver, and it contains a number of breaking changes, new features, and bug fixes.

This release also contains all of the changes that were included in v1.2.0 but not in v2.0.0-alpha. Check out the release notes for v1.2.0 for more information.

Note: this release also updates the MSRV to 1.47

Release Notes

Breaking Changes

Document no longer the default generic type for Collection and Cursor (RUST-735)

The generic parameter must now always explicitly specified when referring to these types. Additionally, the Database::collection and Database::collection_with_options helpers now require a generic parameter to be specified as well. This was done to ease and promote the use of serde with the driver. As part of this, Database::collection_with_type was removed as it was no longer necessary.

// old
let collection = db.collection("foo");
let typed_collection = db.collection_with_type::<MySerdeType>("foo");
struct C { cursor: Cursor }
struct Tc { cursor: Cursor<MySerdeType> }

// new
let collection = db.collection::<Document>("foo");
let typed_collection = db.collection::<MySerdeType>("foo");
struct C { cursor: Cursor<Document> }
struct Tc { cursor: Cursor<MySerdeType> }

Improved Error Matching (RUST-679)

The error API was updated to allow for easier matching by removing the Arc wrapper around Error::kind. Instead, the Arc was moved into the cases that did not implement Clone.

// old
match e.kind.as_ref() {
    ErrorKind::Io(e) => todo!(),
    _ => todo!()
}

// new
match e.kind {
    ErrorKind::Io(e) => todo!(),
    _ => todo!()
}

New Features

• RUST-52 Drivers sessions API
• RUST-735 Collection helpers return Collection<T> (breaking)

Improvements

• RUST-679 Simplify error API to ease pattern matching (breaking)
• RUST-719 Correct casing in ServerType variants (breaking)
• RUST-705 Switch from err-derive to thiserror
• RUST-658 Change estimated_document_count() to use the $collStats aggregation stage

Bug Fixes

• RUST-714 Deadlock possible during retry
• RUST-675 Server selection fails despite having a selectable server
• RUST-717 Hint should be in deletes array for command, not in top-level document
• RUST-718 Enforce update versus replace semantics
• RUST-728 Inherit Collection options in find method

v1.2.1

Description

The MongoDB Rust driver team is pleased to announce the v1.2.1 release of the driver. This release fixes a few high priority issues, so it is highly recommended that all users of the 1.x driver upgrade to use this version.

Bug Fixes

• RUST-714 Fix a possible deadlock that could occur during retry
• RUST-728 Inherit collection options in find helpers and count_documents

v1.2.0

Description

The MongoDB Rust driver team is pleased to announce the v1.2.0 release of the driver.

Release Notes

Serde Integration Improvements

This release contains several improvements to the driver's integration with Serde.

• RUST-562 Return deserializable data types from find methods
• RUST-561 Accept serializable data types as arguments to insert methods

Connection Pooling Improvements

This release contains several bug fixes and improvements to the connection pooling behavior in the driver. These improvements should both improve performance and also reduce the risk of “connection storms”.

Some highlighted changes:

• The driver was erroneously holding onto the mutex on the connection pool while establishing connections, greatly limiting throughput. This has been fixed, so now the pool may be used even when new connections are being established. (RUST-542)
• Concurrent connection creation is now limited to 2 at a time, reducing the spike in connections that can happen after an increase in load, a primary election, or a reduction in throughput server-side. This limit also favors the reuse of existing connections over concurrently creating large amounts of connections, which in initial benchmarks is shown to have a positive impact on throughput. (RUST-556)
• The server selection algorithm now considers the load of suitable servers when choosing among them, opting for nodes currently experiencing less load. This should more evenly distribute the workload across the deployment. (RUST-575)
• Once the driver notices a server has gone down, it now “pauses” the associated connection pool, ensuring no new connection establishment attempts can be made against that server until it enters a known state again. Previously, there was a window in which these connection establishments could still be attempted even after the driver noticed that a server went down, and these establishment attempts could put unnecessary strain on such servers that were likely already struggling. (RUST-690)
• The driver no longer incorrectly uses the “maxPoolSize” URI option to set “minPoolSize”. (RUST-566)

Other New Features

• RUST-514 Add optional bson u2i feature
• RUST-617 Add BSON benchmarks
• RUST-611 Add benchmarks to driver
• RUST-325 Implement hedged read support
• RUST-197 Add plain authentication
• RUST-533 Add sync ClientOptions::parse
• RUST-371 Implement speculative authentication

Improvements

• RUST-623 Upgrade os_info to 3.0.1
• RUST-690 Pause connection pool when server is marked Unknown
• RUST-613 Upgrade typed-builder to 0.4.0
• RUST-598 Perform handshake when establishing monitoring connections
• RUST-562 Exclude unnecessary files

Bug Fixes

• RUST-592 Fix race condition in server monitoring
• RUST-576 Fix count_document fails when writeConcern set on Collection
• RUST-565 Properly report connection closures due to error

v2.0.0-alpha

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-alpha release of the driver, with support for tokio 1.x.

Release Notes

This release is an unstable alpha which has the primary goal of introducing official support for tokio 1.x. It currently contains features that are not yet complete, but we wanted to get this release out as soon as possible to enable users to start working with the driver and tokio 1.x. The API is unstable and subject to breakages as we work towards a stable 2.0 release.

v1.1.1

Description

The MongoDB Rust driver team is pleased to announce the v1.1.1 release of the driver.

Release Notes

Bug Fixes

• RUST-544 Ensure correct termination of monitoring tasks
• #241 remove accidental dependency on openssl
• RUST-541 Include async runtime information in client metadata

v1.1.0

Description

The MongoDB Rust driver team is pleased to announce the v1.1.0 release of the driver.

Release Notes

In addition to the changes for v1.1.0-beta, the following changes were made in v1.1.0:

Bug Fixes

• RUST-384 Close connection which was dropped during command execution (#214)
• RUST-530 Decrement connection count when connection is dropped due to unfinished operation

New Features

• RUST-51 Implement retryable writes

v1.1.0-beta

Description

The MongoDB Rust driver team is pleased to announce the v1.1.0-beta release of the driver.

Release Notes

Bug fixes

• RUST-8 Create/modify collection helpers needs to support creating "validators"
• RUST-524 Add non_exhaustive label to structs and enums missing it

New Features

• RUST-13 Add "indexOptionDefaults" to createCollection()
• RUST-128 Implement retryable reads
• RUST-359 Implement MONGODB-AWS authentication support
• RUST-362 Allow passing hint to findAndModify operations
• RUST-372 Allow passing hint to delete operations
• RUST-376 Allow pasing hint to update operations
• RUST-370 Add "errInfo" field to write concern errors
• RUST-483 Allow alternate SRV resolver configs

Improvements

• RUST-170 Enable and configure TCP Keepalive by default
• RUST-479 Lift restriction on authSource without credentials
• RUST-502 Standardize behavior of empty authSource URI option

v1.0.0

Description

The MongoDB Rust driver team is pleased to announce the first stable release of the driver, v1.0.0. This release marks the general availability of the driver. Additionally, per semver requirements, no breaking API changes will be made to the 1.x branch of the driver.

Major Features

See the releases notes for v0.11.0 for recent changes made to the driver before this release.

Special thanks

Thanks to everyone who contributed code and/or advice along our path to 1.0, including @nevi-me, @ttdonovan, @petoknm, @judy2k, @freakmaxi, @brunobell, @andywswan, @UmerMIB, @DarkEld3r, @yoshuawuyts, and @LucioFranco!