Introduction

Crates.io docs.rs License

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.61.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.7.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.7.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

FeatureDescriptionExtra dependenciesDefault
tokio-runtimeEnable support for the tokio async runtimetokio 1.0 with the full featureyes
async-std-runtimeEnable support for the async-std runtimeasync-std 1.0no
syncExpose the synchronous API (mongodb::sync), using an async-std backend. Cannot be used with the tokio-runtime feature flag.async-std 1.0no
tokio-syncExpose 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 featureno
aws-authEnable support for the MONGODB-AWS authentication mechanism.reqwest 0.11no
bson-uuid-0_8Enable support for v0.8 of the uuid crate in the public API of the re-exported bson crate.n/ano
bson-uuid-1Enable support for v1.x of the uuid crate in the public API of the re-exported bson crate.n/ano
bson-chrono-0_4Enable support for v0.4 of the chrono crate in the public API of the re-exported bson crate.n/ano
bson-serde_withEnable support for the serde_with crate in the public API of the re-exported bson crate.serde_with 1.0no
zlib-compressionEnable support for compressing messages with zlibflate2 1.0no
zstd-compressionEnable support for compressing messages with zstd. This flag requires Rust version 1.54.zstd 0.9.0no
snappy-compressionEnable support for compressing messages with snappysnap 1.0.5no
openssl-tlsSwitch TLS connection handling to use 'openssl'.openssl 0.10.38no

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, cloneing 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 Collections 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 cloneing 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 Clients 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 Subscribers 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:

TargetDescription
mongodb::commandEvents describing commands sent to the database and their success or failure.
mongodb::server_selectionEvents describing the driver's process of selecting a server in the database deployment to send a command to.
mongodb::connectionEvents 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(())
}