Repository files navigation

This is the officially supported MongoDB Rust driver, a client side library that can be used to interact with MongoDB deployments in Rust applications. It uses thebson crate for BSON support. The driver contains a fully async API that requirestokio. The driver also has a sync API that may be enabled via feature flags.

For more details, including features, runnable examples, troubleshooting resources, and more, please see theofficial documentation.

• Rust 1.71.1+ (See theMSRV policy for more information)
• MongoDB 4.0+

The driver tests against Linux, MacOS, and Windows in CI.

The driver is available oncrates.io. To use the driver in your application, simply add it to your project'sCargo.toml.

[dependencies]mongodb ="3.2.3"

Version 1 of this crate has reached end of life and will no longer be receiving any updates or bug fixes, so all users are recommended to always depend on the latest 2.x release. See the2.0.0 release notes for migration information if upgrading from a 1.x version.

The driver also provides a blocking sync API. To enable this, add the"sync" feature to yourCargo.toml:

[dependencies.mongodb]version ="3.2.3"features = ["sync"]

Note: The sync-specific types can be imported frommongodb::sync (e.g.mongodb::sync::Client).

The driver can be used easily with the Actix web framework by storing aClient in Actix application data. A full example application for using MongoDB with Actix can be foundhere.

The Rocket web framework provides built-in support for MongoDB via the Rust driver. The documentation for therocket_db_pools crate contains instructions for using MongoDB with your Rocket application.

In order to connect to a pre-4.2 Atlas instance that's M2 or bigger, theopenssl-tls feature flag must be enabled. The flag is not required for clusters smaller than M2 or running server versions 4.2 or newer.

On Windows, there is a known issue in thetrust-dns-resolver crate, which the driver uses to perform DNS lookups, that causes severe performance degradation in resolvers that use the system configuration. Since the driver uses the system configuration by default, users are recommended to specify an alternate resolver configuration on Windows (e.g.ResolverConfig::cloudflare()) until that issue is resolved. This only has an effect when connecting to deployments using amongodb+srv connection string.

In async Rust, it is common to implement cancellation and timeouts by dropping a future after acertain period of time instead of polling it to completion. This is howtokio::time::timeout works, forexample. However, doing this with futures returned by the driver can leave the driver's internals inan inconsistent state, which may lead to unpredictable or incorrect behavior (seeRUST-937 for moredetails). As such, it ishighly recommended to poll all futures returned from the driver tocompletion. In order to still use timeout mechanisms liketokio::time::timeout with the driver,one option is to spawn tasks and time out on theirJoinHandle futures instead of onthe driver's futures directly. This will ensure the driver's futures will always be completely polledwhile also allowing the application to continue in the event of a timeout.

To file a bug report or submit a feature request, please open a ticket on ourJira project:

• Create an account and login atjira.mongodb.org
• Navigate to the RUST project atjira.mongodb.org/browse/RUST
• ClickCreate Issue - If the ticket you are filing is a bug report, please include as much detail as possible about the issue and how to reproduce it.

Before filing a ticket, please use the search functionality of Jira to see if a similar issue has already been filed.

We encourage and would happily accept contributions in the form of GitHub pull requests. Before opening one, be sure to run the tests locally; check out thetesting section for information on how to do that. Once you open a pull request, your branch will be run against the same testing matrix that we use for ourcontinuous integration system, so it is usually sufficient to only run the integration tests locally against a standalone. Remember to always run the linter tests before opening a pull request.

In order to run the tests (which are mostly integration tests), you must have access to a MongoDB deployment. You may specify aMongoDB connection string in theMONGODB_URI environment variable, and the tests will use it to connect to the deployment. IfMONGODB_URI is unset, the tests will attempt to connect to a local deployment on port 27017.

Note: The integration tests will clear out the databases/collections they need to use, but they do not clean up after themselves.

To actually run the tests, you can usecargo like you would in any other crate:

cargotest --verbose# runs against localhost:27017export MONGODB_URI="mongodb://localhost:123"cargotest --verbose# runs against localhost:123

The authentication tests will only be included in the test run if certain requirements are met:

• The deployment must have--auth enabled
• Credentials must be specified inMONGODB_URI
• The credentials specified inMONGODB_URI must be valid and have root privileges on the deployment

export MONGODB_URI="mongodb://user:pass@localhost:27017"cargotest --verbose# auth tests included

Certain tests will only be run against certain topologies. To ensure that the entire test suite is run, make sure to run the tests separately against standalone, replicated, and sharded deployments.

export MONGODB_URI="mongodb://my-standalone-host:27017"# mongod running on 27017cargotest --verboseexport MONGODB_URI="mongodb://localhost:27018,localhost:27019,localhost:27020/?replicaSet=repl"# replicaset running on ports 27018, 27019, 27020 with name replcargotest --verboseexport MONGODB_URI="mongodb://localhost:27021"# mongos running on 27021cargotest --verbose

To run the tests with TLS/SSL enabled, you must enable it on the deployment and inMONGODB_URI.

export MONGODB_URI="mongodb://localhost:27017/?tls=true&tlsCertificateKeyFile=cert.pem&tlsCAFile=ca.pem"cargotest --verbose

Note: When you open a pull request, your code will be run against a comprehensive testing matrix, so it is usually not necessary to run the integration tests against all combinations of topology/auth/TLS locally.

Our linter tests use the nightly version ofrustfmt to verify that the source is formatted properly and the stable version ofclippy to statically detect any common mistakes.You can userustup to install them both:

rustup component add clippy --toolchain stablerustup component add rustfmt --toolchain nightly

Our linter tests also userustdoc to verify that all necessary documentation is present and properly formatted.rustdoc is included in the standard Rust distribution.

To run the linter tests, run thecheck-clippy.sh,check-rustfmt.sh, andcheck-rustdoc.sh scripts in the.evergreen directory. To run all three, use thecheck-all.sh script.

bash .evergreen/check-all.sh

Commits to main are run automatically onevergreen.

The MSRV for this crate is currently 1.71.1. Increases to the MSRV will only happen in a minor or major version release, and will be to a Rust version at least six months old.

This project is licensed under theApache License 2.0.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).