MongoDB Rust Driver
This repository contains the officially supported MongoDB Rust driver, a client side library that can be used to interact with MongoDB deployments in Rust applications. It depends on the community-supported bson
library for BSON support.
Index
- Installation
- Example Usage
- Bug Reporting / Feature Requests
- Contributing
- Running the tests
- Continuous Integration
- License
Installation
Requirements
Driver Version | Required Rust Version |
---|---|
master | 1.43+ |
0.10.x | 1.43+ |
0.9.x | 1.39+ |
- MongoDB 3.6+
Importing
The driver is available on crates.io. To use the driver in your application, simply add it to your project's Cargo.toml
. You will also want to add bson
as well.
[]
= "0.10.0"
= "0.14.1"
Example Usage
Below are simple examples of using the driver. For more specific examples and the API reference, see the driver's docs.rs page.
Connecting to a MongoDB deployment
use ;
// Parse a connection string into an options struct.
let mut client_options = parse?;
// Manually set an option.
client_options.app_name = Some;
// Get a handle to the deployment.
let client = with_options?;
// List the names of the databases in that deployment.
for db_name in client.list_database_names?
Getting a handle to a database
// Get a handle to a database.
let db = client.database;
// List the names of the collections in that database.
for collection_name in db.list_collection_names?
Inserting documents into a collection
use ;
// Get a handle to a collection in the database.
let collection = db.collection;
let docs = vec!;
// Insert some documents into the "mydb.books" collection.
collection.insert_many?;
Finding documents in a collection
use ;
use FindOptions;
// Query the documents in the collection with a filter and an option.
let filter = doc! ;
let find_options = builder.sort.build;
let cursor = collection.find?;
// Iterate over the results of the cursor.
for result in cursor
Atlas note
Currently, the driver has issues connecting to Atlas tiers above M2 unless the server version is at least 4.2. We're working on fixing this, but in the meantime, a workaround is to upgrade your cluster to 4.2. The driver has no known issues with either M0 or M2 instances.
Bug Reporting / Feature Requests
To file a bug report or submit a feature request, please open a ticket on our Jira project:
- Create an account and login at jira.mongodb.org
- Navigate to the RUST project at jira.mongodb.org/browse/RUST
- Click Create 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.
Contributing
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 the testing 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 our continuous 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.
Running the tests
Integration and unit tests
In order to run the tests (which are mostly integration tests), you must have access to a MongoDB deployment. You may specify a MongoDB connection string in the MONGODB_URI
environment variable, and the tests will use it to connect to the deployment. If MONGODB_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 use cargo
like you would in any other crate:
Auth tests
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 in
MONGODB_URI
- The credentials specified in
MONGODB_URI
must be valid and have root privileges on the deployment
Topology-specific tests
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.
# mongod running on 27017
# mongos running on 27021
Run the tests with TLS/SSL
To run the tests with TLS/SSL enabled, you must enable it on the deployment and in MONGODB_URI
.
Note: When you open a pull request, your code will be run against a comprehensive testing matrix, so it is usually not necessary run the integration tests against all combinations of topology/auth/TLS locally.
Linter Tests
Our linter tests use the nightly version of rustfmt
to verify that the source is formatted properly and the stable version of clippy
to statically detect any common mistakes.
You can use rustup
to install them both:
To run the linter tests, run the check-clippy.sh
and check-rustfmt.sh
scripts in the .evergreen
directory:
&&
Continuous Integration
Commits to master are run automatically on evergreen.
License
This project is licensed under the Apache License 2.0.