Introduction
This is the manual for the officially supported MongoDB Rust driver, a client side library that can be used to interact with MongoDB deployments in Rust applications. It uses the bson
crate for BSON support. The driver contains a fully async API that supports either tokio
(default) or async-std
, depending on the feature flags set. The driver also has a sync API that may be enabled via feature flag.
Warning about timeouts / cancellation
In async Rust, it is common to implement cancellation and timeouts by dropping a future after a certain period of time instead of polling it to completion. This is how tokio::time::timeout
works, for example. However, doing this with futures returned by the driver can leave the driver's internals in an inconsistent state, which may lead to unpredictable or incorrect behavior (see RUST-937 for more details). As such, it is highly recommended to poll all futures returned from the driver to completion. In order to still use timeout mechanisms like tokio::time::timeout
with the driver, one option is to spawn tasks and time out on their JoinHandle
futures instead of on the driver's futures directly. This will ensure the driver's futures will always be completely polled while also allowing the application to continue in the event of a timeout.
e.g.
#![allow(unused)] fn main() { extern crate mongodb; extern crate tokio; use std::time::Duration; use mongodb::{ Client, bson::doc, }; async fn foo() -> std::result::Result<(), Box<dyn std::error::Error>> { let client = Client::with_uri_str("mongodb://example.com").await?; let collection = client.database("foo").collection("bar"); let handle = tokio::task::spawn(async move { collection.insert_one(doc! { "x": 1 }, None).await }); tokio::time::timeout(Duration::from_secs(5), handle).await???; Ok(()) } }
Minimum supported Rust version (MSRV)
The MSRV for this crate is currently 1.57.0. This will rarely be increased, and if it ever is, it will only happen in a minor or major version release.
Installation and Features
Importing
The driver is available on crates.io. To use the driver in your application, simply add it to your project's Cargo.toml
.
[dependencies]
mongodb = "2.1.0"
Configuring the async runtime
The driver supports both of the most popular async runtime crates, namely tokio
and async-std
. By default, the driver will use tokio
, but you can explicitly choose a runtime by specifying one of "tokio-runtime"
or "async-std-runtime"
feature flags in your Cargo.toml
.
For example, to instruct the driver to work with async-std
, add the following to your Cargo.toml
:
[dependencies.mongodb]
version = "2.1.0"
default-features = false
features = ["async-std-runtime"]
Enabling the sync API
The driver also provides a blocking sync API. To enable this, add the "sync"
or "tokio-sync"
feature to your Cargo.toml
:
[dependencies.mongodb]
version = "2.3.0"
features = ["tokio-sync"]
Using the "sync"
feature also requires using default-features = false
.
Note: The sync-specific types can be imported from mongodb::sync
(e.g. mongodb::sync::Client
).
All Feature Flags
Feature | Description | Extra dependencies | Default |
---|---|---|---|
tokio-runtime | Enable support for the tokio async runtime | tokio 1.0 with the full feature | yes |
async-std-runtime | Enable support for the async-std runtime | async-std 1.0 | no |
sync | Expose the synchronous API (mongodb::sync ), using an async-std backend. Cannot be used with the tokio-runtime feature flag. | async-std 1.0 | no |
tokio-sync | Expose the synchronous API (mongodb::sync ), using a tokio backend. Cannot be used with the async-std-runtime feature flag. | tokio 1.0 with the full feature | no |
aws-auth | Enable support for the MONGODB-AWS authentication mechanism. | reqwest 0.11 | no |
bson-uuid-0_8 | Enable support for v0.8 of the uuid crate in the public API of the re-exported bson crate. | n/a | no |
bson-uuid-1 | Enable support for v1.x of the uuid crate in the public API of the re-exported bson crate. | n/a | no |
bson-chrono-0_4 | Enable support for v0.4 of the chrono crate in the public API of the re-exported bson crate. | n/a | no |
bson-serde_with | Enable support for the serde_with crate in the public API of the re-exported bson crate. | serde_with 1.0 | no |
zlib-compression | Enable support for compressing messages with zlib | flate2 1.0 | no |
zstd-compression | Enable support for compressing messages with zstd . This flag requires Rust version 1.54. | zstd 0.9.0 | no |
snappy-compression | Enable support for compressing messages with snappy | snap 1.0.5 | no |
openssl-tls | Switch TLS connection handling to use 'openssl'. | openssl 0.10.38 | no |
Connecting to the Database
Connection String
Connecting to a MongoDB database requires using a connection string, a URI of the form:
mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]
At its simplest this can just specify the host and port, e.g.
mongodb://mongodb0.example.com:27017
For the full range of options supported by the Rust driver, see the documentation for the ClientOptions::parse
method. That method will return a ClientOptions
struct, allowing for directly querying or setting any of the options supported by the Rust driver:
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::options::ClientOptions; async fn run() -> mongodb::error::Result<()> { let mut options = ClientOptions::parse("mongodb://mongodb0.example.com:27017").await?; options.app_name = Some("My App".to_string()); Ok(()) } }
Creating a Client
The Client
struct is the main entry point for the driver. You can create one from a ClientOptions
struct:
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::{Client, options::ClientOptions}; async fn run() -> mongodb::error::Result<()> { let options = ClientOptions::parse("mongodb://mongodb0.example.com:27017").await?; let client = Client::with_options(options)?; Ok(()) } }
As a convenience, if you don't need to modify the ClientOptions
before creating the Client
, you can directly create one from the connection string:
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::Client; async fn run() -> mongodb::error::Result<()> { let client = Client::with_uri_str("mongodb://mongodb0.example.com:27017").await?; Ok(()) } }
Client
uses std::sync::Arc
internally, so it can safely be shared across threads or async tasks. For example:
#![allow(unused)] fn main() { extern crate mongodb; extern crate tokio; use mongodb::{bson::Document, Client, error::Result}; use tokio::task; async fn start_workers() -> Result<()> { let client = Client::with_uri_str("mongodb://example.com").await?; for i in 0..5 { let client_ref = client.clone(); task::spawn(async move { let collection = client_ref.database("items").collection::<Document>(&format!("coll{}", i)); // Do something with the collection }); } Ok(()) } }
Client Performance
While cloning a Client
is very lightweight, creating a new one is an expensive operation. For most use cases, it is highly recommended to create a single Client
and persist it for the lifetime of your application. For more information, see the Performance chapter.
Reading From the Database
Database and Collection Handles
Once you have a Client
, you can call Client::database
to create a handle to a particular database on the server, and Database::collection
to create a handle to a particular collection in that database. Database
and Collection
handles are lightweight - creating them requires no IO, clone
ing them is cheap, and they can be safely shared across threads or async tasks. For example:
#![allow(unused)] fn main() { extern crate mongodb; extern crate tokio; use mongodb::{bson::Document, Client, error::Result}; use tokio::task; async fn start_workers() -> Result<()> { let client = Client::with_uri_str("mongodb://example.com").await?; let db = client.database("items"); for i in 0..5 { let db_ref = db.clone(); task::spawn(async move { let collection = db_ref.collection::<Document>(&format!("coll{}", i)); // Do something with the collection }); } Ok(()) } }
A Collection
can be parameterized with a type for the documents in the collection; this includes but is not limited to just Document
. The various methods that accept instances of the documents (e.g. Collection::insert_one
) require that it implement the Serialize
trait from the serde
crate. Similarly, the methods that return instances (e.g. Collection::find_one
) require that it implement Deserialize
.
Document
implements both and can always be used as the type parameter. However, it is recommended to define types that model your data which you can parameterize your Collection
s with instead, since doing so eliminates a lot of boilerplate deserialization code and is often more performant.
#![allow(unused)] fn main() { extern crate mongodb; extern crate tokio; extern crate serde; use mongodb::{ bson::doc, error::Result, }; use tokio::task; async fn start_workers() -> Result<()> { use mongodb::Client; let client = Client::with_uri_str("mongodb://example.com").await?; use serde::{Deserialize, Serialize}; // Define a type that models our data. #[derive(Clone, Debug, Deserialize, Serialize)] struct Item { id: u32, } // Parameterize our collection with the model. let coll = client.database("items").collection::<Item>("in_stock"); for i in 0..5 { // Perform operations that work with directly our model. coll.insert_one(Item { id: i }, None).await; } Ok(()) } }
For more information, see the Serde Integration section.
Cursors
Results from queries are generally returned via Cursor
, a struct which streams the results back from the server as requested. The Cursor
type implements the Stream
trait from the futures
crate, and in order to access its streaming functionality you need to import at least one of the StreamExt
or TryStreamExt
traits.
# In Cargo.toml, add the following dependency.
futures = "0.3"
#![allow(unused)] fn main() { extern crate mongodb; extern crate serde; extern crate futures; use serde::Deserialize; #[derive(Deserialize)] struct Book { title: String } async fn foo() -> mongodb::error::Result<()> { let typed_collection = mongodb::Client::with_uri_str("").await?.database("").collection::<Book>(""); // This trait is required to use `try_next()` on the cursor use futures::stream::TryStreamExt; use mongodb::{bson::doc, options::FindOptions}; // Query the books in the collection with a filter and an option. let filter = doc! { "author": "George Orwell" }; let find_options = FindOptions::builder().sort(doc! { "title": 1 }).build(); let mut cursor = typed_collection.find(filter, find_options).await?; // Iterate over the results of the cursor. while let Some(book) = cursor.try_next().await? { println!("title: {}", book.title); } Ok(()) } }
If a Cursor
is still open when it goes out of scope, it will automatically be closed via an asynchronous killCursors command executed from its Drop
implementation.
Performance
Client
Best Practices
The Client
handles many aspects of database connection behind the scenes that can require manual management for other database drivers; it discovers server topology, monitors it for any changes, and maintains an internal connection pool. This has implications for how a Client
should be used for best performance.
Lifetime
A Client
should be as long-lived as possible. Establishing a new Client
is relatively slow and resource-intensive, so ideally that should only be done once at application startup. Because Client
is implemented using an internal Arc
, it can safely be shared across threads or tasks, and clone
ing it to pass to new contexts is extremely cheap.
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::Client; use std::error::Error; // This will be very slow because it's constructing and tearing down a `Client` // with every request. async fn handle_request_bad() -> Result<(), Box<dyn Error>> { let client = Client::with_uri_str("mongodb://example.com").await?; // Do something with the client Ok(()) } // This will be much faster. async fn handle_request_good(client: &Client) -> Result<(), Box<dyn Error>> { // Do something with the client Ok(()) } }
This is especially noticeable when using a framework that provides connection pooling; because Client
does its own pooling internally, attempting to maintain a pool of Client
s will (somewhat counter-intuitively) result in worse performance than using a single one.
Runtime
A Client
is implicitly bound to the instance of the tokio
or async-std
runtime in which it was created. Attempting to execute operations on a different runtime instance will cause incorrect behavior and unpredictable failures. This is easy to accidentally invoke when testing, as the tokio::test
or async_std::test
helper macros create a new runtime for each test.
#![allow(unused)] fn main() { extern crate mongodb; extern crate once_cell; extern crate tokio; use mongodb::Client; use std::error::Error; use tokio::runtime::Runtime; use once_cell::sync::Lazy; static CLIENT: Lazy<Client> = Lazy::new(|| { let rt = Runtime::new().unwrap(); rt.block_on(async { Client::with_uri_str("mongodb://example.com").await.unwrap() }) }); // This will inconsistently fail. #[tokio::test] async fn test_list_dbs() -> Result<(), Box<dyn Error>> { CLIENT.list_database_names(None, None).await?; Ok(()) } }
To work around this issue, either create a new Client
for every async test, or bundle the Runtime
along with the client and don't use the test helper macros.
#![allow(unused)] fn main() { extern crate mongodb; extern crate once_cell; extern crate tokio; use mongodb::Client; use std::error::Error; use tokio::runtime::Runtime; use once_cell::sync::Lazy; static CLIENT_RUNTIME: Lazy<(Client, Runtime)> = Lazy::new(|| { let rt = Runtime::new().unwrap(); let client = rt.block_on(async { Client::with_uri_str("mongodb://example.com").await.unwrap() }); (client, rt) }); #[test] fn test_list_dbs() -> Result<(), Box<dyn Error>> { let (client, rt) = &*CLIENT_RUNTIME; rt.block_on(async { client.list_database_names(None, None).await })?; Ok(()) } }
or
#![allow(unused)] fn main() { extern crate mongodb; extern crate tokio; use mongodb::Client; use std::error::Error; #[tokio::test] async fn test_list_dbs() -> Result<(), Box<dyn Error>> { let client = Client::with_uri_str("mongodb://example.com").await?; CLIENT.list_database_names(None, None).await?; Ok(()) } }
Parallelism
Where data operations are naturally parallelizable, spawning many asynchronous tasks that use the driver concurrently is often the best way to achieve maximum performance, as the driver is designed to work well in such situations.
#![allow(unused)] fn main() { extern crate mongodb; extern crate tokio; use mongodb::{bson::Document, Client, error::Result}; use tokio::task; async fn start_workers() -> Result<()> { let client = Client::with_uri_str("mongodb://example.com").await?; for i in 0..5 { let client_ref = client.clone(); task::spawn(async move { let collection = client_ref.database("items").collection::<Document>(&format!("coll{}", i)); // Do something with the collection }); } Ok(()) } }
Tracing and Logging
The driver utilizes the tracing
crate to emit events at points of interest. To enable this, you must turn on the tracing-unstable
feature flag.
Stability Guarantees
This functionality 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 Subscriber
s that depend on older versions of tracing
.
Additionally, future minor releases may make changes such as:
- add or remove tracing events
- add or remove values attached to tracing events
- change the types and/or names of values attached to tracing events
- add or remove driver-defined tracing spans
- change the severity level of tracing events
Such changes will be called out in release notes.
Event Targets
Currently, events are emitted under the following targets:
Target | Description |
---|---|
mongodb::command | Events describing commands sent to the database and their success or failure. |
mongodb::server_selection | Events describing the driver's process of selecting a server in the database deployment to send a command to. |
mongodb::connection | Events describing the behavior of driver connection pools and the connections they contain. |
Consuming Events
To consume events in your application, in addition to enabling the tracing-unstable
feature flag, you must either register a tracing
-compatible subscriber or a log
-compatible logger, as detailed in the following sections.
Consuming Events with tracing
To consume events with tracing
, you will need to register a type implementing the tracing::Subscriber
trait in your application, as discussed in the tracing
docs.
Here's a minimal example of a program using the driver which uses a tracing subscriber.
First, add the following to Cargo.toml
:
tracing = "LATEST_VERSION_HERE"
tracing-subscriber = "LATEST_VERSION_HERE"
mongodb = { version = "LATEST_VERSION_HERE", features = ["tracing-unstable"] }
And then in main.rs
:
extern crate mongodb; extern crate tokio; extern crate tracing_subscriber; use std::env; use mongodb::{bson::doc, error::Result, Client}; #[tokio::main] async fn main() -> Result<()> { // Register a global tracing subscriber which will obey the RUST_LOG environment variable // config. tracing_subscriber::fmt::init(); // Create a MongoDB client. let mongodb_uri = env::var("MONGODB_URI").expect("The MONGODB_URI environment variable was not set."); let client = Client::with_uri_str(mongodb_uri).await?; // Insert a document. let coll = client.database("test").collection("test_coll"); coll.insert_one(doc! { "x" : 1 }, None).await?; Ok(()) }
This program can be run from the command line as follows, using the RUST_LOG
environment variable to configure verbosity levels and observe command-related events with severity debug or higher:
RUST_LOG='mongodb::command=debug' MONGODB_URI='YOUR_URI_HERE' cargo run
The output will look something like the following:
2023-02-03T19:20:16.091822Z DEBUG mongodb::command: Command started topologyId="63dd5e706af9908fc834fd94" command="{\"insert\":\"test_coll\",\"ordered\":true,\"$db\":\"test\",\"lsid\":{\"id\":{\"$binary\":{\"base64\":\"y/v7PiLaRwOhT0RBFRDtNw==\",\"subType\":\"04\"}}},\"documents\":[{\"_id\":{\"$oid\":\"63dd5e706af9908fc834fd95\"},\"x\":1}]}" databaseName="test" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017
2023-02-03T19:20:16.092700Z DEBUG mongodb::command: Command succeeded topologyId="63dd5e706af9908fc834fd94" reply="{\"n\":1,\"ok\":1.0}" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017 durationMS=0
Consuming Events with log
Alternatively, to consume events with log
, you will need to add tracing
as a dependency of your application, and enable either its log
or log-always
feature.
Those features are described in detail here.
Here's a minimal example of a program using the driver which uses env_logger
.
In Cargo.toml
:
tracing = { version = "LATEST_VERSION_HERE", features = ["log"] }
mongodb = { version = "LATEST_VERSION_HERE", features = ["tracing-unstable"] }
env_logger = "LATEST_VERSION_HERE"
And in main.rs
:
extern crate mongodb; extern crate tokio; extern crate env_logger; use std::env; use mongodb::{bson::doc, error::Result, Client}; #[tokio::main] async fn main() -> Result<()> { // Register a global logger. env_logger::init(); // Create a MongoDB client. let mongodb_uri = env::var("MONGODB_URI").expect("The MONGODB_URI environment variable was not set."); let client = Client::with_uri_str(mongodb_uri).await?; // Insert a document. let coll = client.database("test").collection("test_coll"); coll.insert_one(doc! { "x" : 1 }, None).await?; Ok(()) }
This program can be run from the command line as follows, using the RUST_LOG
environment variable to configure verbosity levels and observe command-related messages with severity debug or higher:
RUST_LOG='mongodb::command=debug' MONGODB_URI='YOUR_URI_HERE' cargo run
The output will look something like the following:
2023-02-03T19:20:16.091822Z DEBUG mongodb::command: Command started topologyId="63dd5e706af9908fc834fd94" command="{\"insert\":\"test_coll\",\"ordered\":true,\"$db\":\"test\",\"lsid\":{\"id\":{\"$binary\":{\"base64\":\"y/v7PiLaRwOhT0RBFRDtNw==\",\"subType\":\"04\"}}},\"documents\":[{\"_id\":{\"$oid\":\"63dd5e706af9908fc834fd95\"},\"x\":1}]}" databaseName="test" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017
2023-02-03T19:20:16.092700Z DEBUG mongodb::command: Command succeeded topologyId="63dd5e706af9908fc834fd94" reply="{\"n\":1,\"ok\":1.0}" commandName="insert" requestId=4 driverConnectionId=1 serverConnectionId=16 serverHost="localhost" serverPort=27017 durationMS=0
Web Framework Examples
Actix
The driver can be used easily with the Actix web framework by storing a Client
in Actix application data. A full example application for using MongoDB with Actix can be found here.
Rocket
The Rocket web framework provides built-in support for MongoDB via the Rust driver. The documentation for the rocket_db_pools
crate contains instructions for using MongoDB with your Rocket application.
Unstable API
To enable support for in-use encryption (client-side field level encryption and queryable encryption), enable the "in-use-encryption-unstable"
feature of the mongodb
crate. As the name implies, the API for this feature is unstable, and may change in backwards-incompatible ways in minor releases.
Client-Side Field Level Encryption
Starting with MongoDB 4.2, client-side field level encryption allows an application to encrypt specific data fields in addition to pre-existing MongoDB encryption features such as Encryption at Rest and TLS/SSL (Transport Encryption).
With field level encryption, applications can encrypt fields in documents prior to transmitting data over the wire to the server. Client-side field level encryption supports workloads where applications must guarantee that unauthorized parties, including server administrators, cannot read the encrypted data.
See also the MongoDB documentation on Client Side Field Level Encryption.
Dependencies
To get started using client-side field level encryption in your project, you will need to install libmongocrypt, which can be fetched from a variety of package repositories. If you install libmongocrypt in a location outside of the system library search path, the MONGOCRYPT_LIB_DIR
environment variable will need to be set when compiling your project.
Additionally, either crypt_shared
or mongocryptd
are required in order to use automatic client-side encryption.
crypt_shared
The Automatic Encryption Shared Library (crypt_shared) provides the same functionality as mongocryptd, but does not require you to spawn another process to perform automatic encryption.
By default, the mongodb
crate attempts to load crypt_shared from the system and if found uses it automatically. To load crypt_shared from another location, set the "cryptSharedLibPath"
field in extra_options
:
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::{bson::doc, Client, error::Result}; async fn func() -> Result<()> { let options = todo!(); let kv_namespace = todo!(); let kms_providers: Vec<_> = todo!(); let client = Client::encrypted_builder(options, kv_namespace, kms_providers)? .extra_options(doc! { "cryptSharedLibPath": "/path/to/crypt/shared", }) .build(); Ok(()) } }
If the mongodb
crate cannot load crypt_shared it will attempt to fallback to using mongocryptd by default. Include "cryptSharedRequired": true
in the extra_options
document to always use crypt_shared and fail if it could not be loaded.
For detailed installation instructions see the MongoDB documentation on Automatic Encryption Shared Library.
mongocryptd
If using crypt_shared
is not an option, the mongocryptd
binary is required for automatic client-side encryption and is included as a component in the MongoDB Enterprise Server package. For detailed installation instructions see the MongoDB documentation on mongocryptd.
mongocryptd
performs the following:
- Parses the automatic encryption rules specified to the database connection. If the JSON schema contains invalid automatic encryption syntax or any document validation syntax,
mongocryptd
returns an error. - Uses the specified automatic encryption rules to mark fields in read and write operations for encryption.
- Rejects read/write operations that may return unexpected or incorrect results when applied to an encrypted field. For supported and unsupported operations, see Read/Write Support with Automatic Field Level Encryption.
A Client
configured with auto encryption will automatically spawn the mongocryptd
process from the application's PATH
. Applications can control the spawning behavior as part of the automatic encryption options:
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::{bson::doc, Client, error::Result}; async fn func() -> Result<()> { let options = todo!(); let kv_namespace = todo!(); let kms_providers: Vec<_> = todo!(); let client = Client::encrypted_builder(options, kv_namespace, kms_providers)? .extra_options(doc! { "mongocryptdSpawnPath": "/path/to/mongocryptd", "mongocryptdSpawnArgs": ["--logpath=/path/to/mongocryptd.log", "--logappend"], }) .build(); Ok(()) } }
If your application wishes to manage the mongocryptd
process manually, it is possible to disable spawning mongocryptd
:
#![allow(unused)] fn main() { extern crate mongodb; use mongodb::{bson::doc, Client, error::Result}; async fn func() -> Result<()> { let options = todo!(); let kv_namespace = todo!(); let kms_providers: Vec<_> = todo!(); let client = Client::encrypted_builder(options, kv_namespace, kms_providers)? .extra_options(doc! { "mongocryptdBypassSpawn": true, "mongocryptdURI": "mongodb://localhost:27020", }) .build(); Ok(()) } }
mongocryptd
is only responsible for supporting automatic client-side field level encryption and does not itself perform any encryption or decryption.
Automatic Client-Side Field Level Encryption
Automatic client-side field level encryption is enabled by using the Client::encrypted_builder
constructor method. The following examples show how to setup automatic client-side field level encryption using ClientEncryption
to create a new encryption data key.
Note: Automatic client-side field level encryption requires MongoDB 4.2+ enterprise or a MongoDB 4.2+ Atlas cluster. The community version of the server supports automatic decryption as well as explicit client-side encryption.
Providing Local Automatic Encryption Rules
The following example shows how to specify automatic encryption rules via the schema_map
option. The automatic encryption rules are expressed using a strict subset of the JSON Schema syntax.
Supplying a schema_map
provides more security than relying on JSON Schemas obtained from the server. It protects against a malicious server advertising a false JSON Schema, which could trick the client into sending unencrypted data that should be encrypted.
JSON Schemas supplied in the schema_map
only apply to configuring automatic client-side field level encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.
extern crate mongodb; extern crate tokio; extern crate rand; static URI: &str = "mongodb://example.com"; use mongodb::{ bson::{self, doc, Document}, client_encryption::{ClientEncryption, MasterKey}, error::Result, mongocrypt::ctx::KmsProvider, options::ClientOptions, Client, Namespace, }; use rand::Rng; #[tokio::main] async fn main() -> Result<()> { // The MongoDB namespace (db.collection) used to store the // encrypted documents in this example. let encrypted_namespace = Namespace::new("test", "coll"); // This must be the same master key that was used to create // the encryption key. let mut key_bytes = vec![0u8; 96]; rand::thread_rng().fill(&mut key_bytes[..]); let local_master_key = bson::Binary { subtype: bson::spec::BinarySubtype::Generic, bytes: key_bytes, }; let kms_providers = vec![(KmsProvider::Local, doc! { "key": local_master_key }, None)]; // The MongoDB namespace (db.collection) used to store // the encryption data keys. let key_vault_namespace = Namespace::new("encryption", "__testKeyVault"); // The MongoClient used to access the key vault (key_vault_namespace). let key_vault_client = Client::with_uri_str(URI).await?; let key_vault = key_vault_client .database(&key_vault_namespace.db) .collection::<Document>(&key_vault_namespace.coll); key_vault.drop(None).await?; let client_encryption = ClientEncryption::new( key_vault_client, key_vault_namespace.clone(), kms_providers.clone(), )?; // Create a new data key and json schema for the encryptedField. // https://dochub.mongodb.org/core/client-side-field-level-encryption-automatic-encryption-rules let data_key_id = client_encryption .create_data_key(MasterKey::Local) .key_alt_names(["encryption_example_1".to_string()]) .run() .await?; let schema = doc! { "properties": { "encryptedField": { "encrypt": { "keyId": [data_key_id], "bsonType": "string", "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", } } }, "bsonType": "object", }; let client = Client::encrypted_builder( ClientOptions::parse(URI).await?, key_vault_namespace, kms_providers, )? .schema_map([(encrypted_namespace.to_string(), schema)]) .build() .await?; let coll = client .database(&encrypted_namespace.db) .collection::<Document>(&encrypted_namespace.coll); // Clear old data. coll.drop(None).await?; coll.insert_one(doc! { "encryptedField": "123456789" }, None) .await?; println!("Decrypted document: {:?}", coll.find_one(None, None).await?); let unencrypted_coll = Client::with_uri_str(URI) .await? .database(&encrypted_namespace.db) .collection::<Document>(&encrypted_namespace.coll); println!( "Encrypted document: {:?}", unencrypted_coll.find_one(None, None).await? ); Ok(()) }
Server-Side Field Level Encryption Enforcement
The MongoDB 4.2+ server supports using schema validation to enforce encryption of specific fields in a collection. This schema validation will prevent an application from inserting unencrypted values for any fields marked with the "encrypt"
JSON schema keyword.
The following example shows how to setup automatic client-side field level encryption using ClientEncryption
to create a new encryption data key and create a collection with the Automatic Encryption JSON Schema Syntax:
extern crate mongodb; extern crate tokio; extern crate rand; static URI: &str = "mongodb://example.com"; use mongodb::{ bson::{self, doc, Document}, client_encryption::{ClientEncryption, MasterKey}, error::Result, mongocrypt::ctx::KmsProvider, options::{ClientOptions, CreateCollectionOptions, WriteConcern}, Client, Namespace, }; use rand::Rng; #[tokio::main] async fn main() -> Result<()> { // The MongoDB namespace (db.collection) used to store the // encrypted documents in this example. let encrypted_namespace = Namespace::new("test", "coll"); // This must be the same master key that was used to create // the encryption key. let mut key_bytes = vec![0u8; 96]; rand::thread_rng().fill(&mut key_bytes[..]); let local_master_key = bson::Binary { subtype: bson::spec::BinarySubtype::Generic, bytes: key_bytes, }; let kms_providers = vec![(KmsProvider::Local, doc! { "key": local_master_key }, None)]; // The MongoDB namespace (db.collection) used to store // the encryption data keys. let key_vault_namespace = Namespace::new("encryption", "__testKeyVault"); // The MongoClient used to access the key vault (key_vault_namespace). let key_vault_client = Client::with_uri_str(URI).await?; let key_vault = key_vault_client .database(&key_vault_namespace.db) .collection::<Document>(&key_vault_namespace.coll); key_vault.drop(None).await?; let client_encryption = ClientEncryption::new( key_vault_client, key_vault_namespace.clone(), kms_providers.clone(), )?; // Create a new data key and json schema for the encryptedField. let data_key_id = client_encryption .create_data_key(MasterKey::Local) .key_alt_names(["encryption_example_2".to_string()]) .run() .await?; let schema = doc! { "properties": { "encryptedField": { "encrypt": { "keyId": [data_key_id], "bsonType": "string", "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", } } }, "bsonType": "object", }; let client = Client::encrypted_builder( ClientOptions::parse(URI).await?, key_vault_namespace, kms_providers, )? .build() .await?; let db = client.database(&encrypted_namespace.db); let coll = db.collection::<Document>(&encrypted_namespace.coll); // Clear old data coll.drop(None).await?; // Create the collection with the encryption JSON Schema. db.create_collection( &encrypted_namespace.coll, CreateCollectionOptions::builder() .write_concern(WriteConcern::MAJORITY) .validator(doc! { "$jsonSchema": schema }) .build(), ).await?; coll.insert_one(doc! { "encryptedField": "123456789" }, None) .await?; println!("Decrypted document: {:?}", coll.find_one(None, None).await?); let unencrypted_coll = Client::with_uri_str(URI) .await? .database(&encrypted_namespace.db) .collection::<Document>(&encrypted_namespace.coll); println!( "Encrypted document: {:?}", unencrypted_coll.find_one(None, None).await? ); // This would return a Write error with the message "Document failed validation". // unencrypted_coll.insert_one(doc! { "encryptedField": "123456789" }, None) // .await?; Ok(()) }
Automatic Queryable Encryption
Verison 2.4.0 of the mongodb
crate brings support for Queryable Encryption with MongoDB >=6.0.
Queryable Encryption is the second version of Client-Side Field Level Encryption. Data is encrypted client-side. Queryable Encryption supports indexed encrypted fields, which are further processed server-side.
You must have MongoDB 6.0 Enterprise to preview the feature.
Automatic encryption in Queryable Encryption is configured with an encrypted_fields
mapping, as demonstrated by the following example:
extern crate mongodb; extern crate tokio; extern crate rand; extern crate futures; static URI: &str = "mongodb://example.com"; use futures::TryStreamExt; use mongodb::{ bson::{self, doc, Document}, client_encryption::{ClientEncryption, MasterKey}, error::Result, mongocrypt::ctx::KmsProvider, options::ClientOptions, Client, Namespace, }; use rand::Rng; #[tokio::main] async fn main() -> Result<()> { let mut key_bytes = vec![0u8; 96]; rand::thread_rng().fill(&mut key_bytes[..]); let local_master_key = bson::Binary { subtype: bson::spec::BinarySubtype::Generic, bytes: key_bytes, }; let kms_providers = vec![(KmsProvider::Local, doc! { "key": local_master_key }, None)]; let key_vault_namespace = Namespace::new("keyvault", "datakeys"); let key_vault_client = Client::with_uri_str(URI).await?; let key_vault = key_vault_client .database(&key_vault_namespace.db) .collection::<Document>(&key_vault_namespace.coll); key_vault.drop(None).await?; let client_encryption = ClientEncryption::new( key_vault_client, key_vault_namespace.clone(), kms_providers.clone(), )?; let key1_id = client_encryption .create_data_key(MasterKey::Local) .key_alt_names(["firstName".to_string()]) .run() .await?; let key2_id = client_encryption .create_data_key(MasterKey::Local) .key_alt_names(["lastName".to_string()]) .run() .await?; let encrypted_fields_map = vec![( "example.encryptedCollection", doc! { "escCollection": "encryptedCollection.esc", "eccCollection": "encryptedCollection.ecc", "ecocCollection": "encryptedCollection.ecoc", "fields": [ { "path": "firstName", "bsonType": "string", "keyId": key1_id, "queries": [{"queryType": "equality"}], }, { "path": "lastName", "bsonType": "string", "keyId": key2_id, } ] }, )]; let client = Client::encrypted_builder( ClientOptions::parse(URI).await?, key_vault_namespace, kms_providers, )? .encrypted_fields_map(encrypted_fields_map) .build() .await?; let db = client.database("example"); let coll = db.collection::<Document>("encryptedCollection"); coll.drop(None).await?; db.create_collection("encryptedCollection", None).await?; coll.insert_one( doc! { "_id": 1, "firstName": "Jane", "lastName": "Doe" }, None, ) .await?; let docs: Vec<_> = coll .find(doc! {"firstName": "Jane"}, None) .await? .try_collect() .await?; println!("{:?}", docs); Ok(()) }
Explicit Queryable Encryption
Verison 2.4.0 of the mongodb
crate brings support for Queryable Encryption with MongoDB >=6.0.
Queryable Encryption is the second version of Client-Side Field Level Encryption. Data is encrypted client-side. Queryable Encryption supports indexed encrypted fields, which are further processed server-side.
Explicit encryption in Queryable Encryption is performed using the encrypt
and decrypt
methods. Automatic encryption (to allow the find_one
to automatically decrypt) is configured using an encrypted_fields
mapping, as demonstrated by the following example:
extern crate mongodb; extern crate tokio; extern crate rand; static URI: &str = "mongodb://example.com"; use mongodb::{ bson::{self, doc, Document}, client_encryption::{ClientEncryption, MasterKey}, error::Result, mongocrypt::ctx::{KmsProvider, Algorithm}, options::{ClientOptions, CreateCollectionOptions}, Client, Namespace, }; use rand::Rng; #[tokio::main] async fn main() -> Result<()> { // This must be the same master key that was used to create // the encryption key. let mut key_bytes = vec![0u8; 96]; rand::thread_rng().fill(&mut key_bytes[..]); let local_master_key = bson::Binary { subtype: bson::spec::BinarySubtype::Generic, bytes: key_bytes, }; let kms_providers = vec![(KmsProvider::Local, doc! { "key": local_master_key }, None)]; // The MongoDB namespace (db.collection) used to store // the encryption data keys. let key_vault_namespace = Namespace::new("keyvault", "datakeys"); // Set up the key vault (key_vault_namespace) for this example. let client = Client::with_uri_str(URI).await?; let key_vault = client .database(&key_vault_namespace.db) .collection::<Document>(&key_vault_namespace.coll); key_vault.drop(None).await?; let client_encryption = ClientEncryption::new( // The MongoClient to use for reading/writing to the key vault. // This can be the same MongoClient used by the main application. client, key_vault_namespace.clone(), kms_providers.clone(), )?; // Create a new data key for the encryptedField. let indexed_key_id = client_encryption .create_data_key(MasterKey::Local) .run() .await?; let unindexed_key_id = client_encryption .create_data_key(MasterKey::Local) .run() .await?; let encrypted_fields = doc! { "escCollection": "enxcol_.default.esc", "eccCollection": "enxcol_.default.ecc", "ecocCollection": "enxcol_.default.ecoc", "fields": [ { "keyId": indexed_key_id.clone(), "path": "encryptedIndexed", "bsonType": "string", "queries": { "queryType": "equality" } }, { "keyId": unindexed_key_id.clone(), "path": "encryptedUnindexed", "bsonType": "string", } ] }; // The MongoClient used to read/write application data. let encrypted_client = Client::encrypted_builder( ClientOptions::parse(URI).await?, key_vault_namespace, kms_providers, )? .bypass_query_analysis(true) .build() .await?; let db = encrypted_client.database("test"); db.drop(None).await?; // Create the collection with encrypted fields. db.create_collection( "coll", CreateCollectionOptions::builder() .encrypted_fields(encrypted_fields) .build(), ) .await?; let coll = db.collection::<Document>("coll"); // Create and encrypt an indexed and unindexed value. let val = "encrypted indexed value"; let unindexed_val = "encrypted unindexed value"; let insert_payload_indexed = client_encryption .encrypt(val, indexed_key_id.clone(), Algorithm::Indexed) .contention_factor(1) .run() .await?; let insert_payload_unindexed = client_encryption .encrypt(unindexed_val, unindexed_key_id, Algorithm::Unindexed) .run() .await?; // Insert the payloads. coll.insert_one( doc! { "encryptedIndexed": insert_payload_indexed, "encryptedUnindexed": insert_payload_unindexed, }, None, ) .await?; // Encrypt our find payload using QueryType.EQUALITY. // The value of `data_key_id` must be the same as used to encrypt the values // above. let find_payload = client_encryption .encrypt(val, indexed_key_id, Algorithm::Indexed) .query_type("equality") .contention_factor(1) .run() .await?; // Find the document we inserted using the encrypted payload. // The returned document is automatically decrypted. let doc = coll .find_one(doc! { "encryptedIndexed": find_payload }, None) .await?; println!("Returned document: {:?}", doc); Ok(()) }
Explicit Encryption
Explicit encryption is a MongoDB community feature and does not use the mongocryptd process. Explicit encryption is provided by the ClientEncryption
struct, for example:
extern crate mongodb; extern crate tokio; extern crate rand; static URI: &str = "mongodb://example.com"; use mongodb::{ bson::{self, doc, Bson, Document}, client_encryption::{ClientEncryption, MasterKey}, error::Result, mongocrypt::ctx::{Algorithm, KmsProvider}, Client, Namespace, }; use rand::Rng; #[tokio::main] async fn main() -> Result<()> { // This must be the same master key that was used to create // the encryption key. let mut key_bytes = vec![0u8; 96]; rand::thread_rng().fill(&mut key_bytes[..]); let local_master_key = bson::Binary { subtype: bson::spec::BinarySubtype::Generic, bytes: key_bytes, }; let kms_providers = vec![(KmsProvider::Local, doc! { "key": local_master_key }, None)]; // The MongoDB namespace (db.collection) used to store // the encryption data keys. let key_vault_namespace = Namespace::new("keyvault", "datakeys"); // The MongoClient used to read/write application data. let client = Client::with_uri_str(URI).await?; let coll = client.database("test").collection::<Document>("coll"); // Clear old data coll.drop(None).await?; // Set up the key vault (key_vault_namespace) for this example. let key_vault = client .database(&key_vault_namespace.db) .collection::<Document>(&key_vault_namespace.coll); key_vault.drop(None).await?; let client_encryption = ClientEncryption::new( // The MongoClient to use for reading/writing to the key vault. // This can be the same MongoClient used by the main application. client, key_vault_namespace.clone(), kms_providers.clone(), )?; // Create a new data key for the encryptedField. let data_key_id = client_encryption .create_data_key(MasterKey::Local) .key_alt_names(["encryption_example_3".to_string()]) .run() .await?; // Explicitly encrypt a field: let encrypted_field = client_encryption .encrypt( "123456789", data_key_id, Algorithm::AeadAes256CbcHmacSha512Deterministic, ) .run() .await?; coll.insert_one(doc! { "encryptedField": encrypted_field }, None) .await?; let mut doc = coll.find_one(None, None).await?.unwrap(); println!("Encrypted document: {:?}", doc); // Explicitly decrypt the field: let field = match doc.get("encryptedField") { Some(Bson::Binary(bin)) => bin, _ => panic!("invalid field"), }; let decrypted: Bson = client_encryption .decrypt(field.as_raw_binary()) .await? .try_into()?; doc.insert("encryptedField", decrypted); println!("Decrypted document: {:?}", doc); Ok(()) }
Explicit Encryption with Automatic Decryption
Although automatic encryption requires MongoDB 4.2+ enterprise or a MongoDB 4.2+ Atlas cluster, automatic decryption is supported for all users. To configure automatic decryption without automatic encryption set bypass_auto_encryption
to true
in the EncryptedClientBuilder
:
extern crate mongodb; extern crate tokio; extern crate rand; static URI: &str = "mongodb://example.com"; use mongodb::{ bson::{self, doc, Document}, client_encryption::{ClientEncryption, MasterKey}, error::Result, mongocrypt::ctx::{Algorithm, KmsProvider}, options::ClientOptions, Client, Namespace, }; use rand::Rng; #[tokio::main] async fn main() -> Result<()> { // This must be the same master key that was used to create // the encryption key. let mut key_bytes = vec![0u8; 96]; rand::thread_rng().fill(&mut key_bytes[..]); let local_master_key = bson::Binary { subtype: bson::spec::BinarySubtype::Generic, bytes: key_bytes, }; let kms_providers = vec![(KmsProvider::Local, doc! { "key": local_master_key }, None)]; // The MongoDB namespace (db.collection) used to store // the encryption data keys. let key_vault_namespace = Namespace::new("keyvault", "datakeys"); // `bypass_auto_encryption(true)` disables automatic encryption but keeps // the automatic _decryption_ behavior. bypass_auto_encryption will // also disable spawning mongocryptd. let client = Client::encrypted_builder( ClientOptions::parse(URI).await?, key_vault_namespace.clone(), kms_providers.clone(), )? .bypass_auto_encryption(true) .build() .await?; let coll = client.database("test").collection::<Document>("coll"); // Clear old data coll.drop(None).await?; // Set up the key vault (key_vault_namespace) for this example. let key_vault = client .database(&key_vault_namespace.db) .collection::<Document>(&key_vault_namespace.coll); key_vault.drop(None).await?; let client_encryption = ClientEncryption::new( // The MongoClient to use for reading/writing to the key vault. // This can be the same MongoClient used by the main application. client, key_vault_namespace.clone(), kms_providers.clone(), )?; // Create a new data key for the encryptedField. let data_key_id = client_encryption .create_data_key(MasterKey::Local) .key_alt_names(["encryption_example_4".to_string()]) .run() .await?; // Explicitly encrypt a field: let encrypted_field = client_encryption .encrypt( "123456789", data_key_id, Algorithm::AeadAes256CbcHmacSha512Deterministic, ) .run() .await?; coll.insert_one(doc! { "encryptedField": encrypted_field }, None) .await?; // Automatically decrypts any encrypted fields. let doc = coll.find_one(None, None).await?.unwrap(); println!("Decrypted document: {:?}", doc); let unencrypted_coll = Client::with_uri_str(URI) .await? .database("test") .collection::<Document>("coll"); println!( "Encrypted document: {:?}", unencrypted_coll.find_one(None, None).await? ); Ok(()) }