[−][src]Crate mongodb_cwal

MongoDB Rust Driver

A driver written in pure Rust, providing a native interface to MongoDB.

Connecting to MongoDB

The Client is an entry-point to interacting with a MongoDB instance.

// Direct connection to a server. Will not look for other servers in the topology.
let client = Client::connect("localhost", 27017)
    .expect("Failed to initialize client.");

// Connect to a complex server topology, such as a replica set
// or sharded cluster, using a connection string uri.
let client = Client::with_uri("mongodb://localhost:27017,localhost:27018/")
    .expect("Failed to initialize client.");

// Specify a read preference, and rely on the driver to find secondaries.
let mut options = ClientOptions::new();
options.read_preference = Some(ReadPreference::new(ReadMode::SecondaryPreferred, None));
let client = Client::with_uri_and_options("mongodb://localhost:27017/", options)
    .expect("Failed to initialize client.");

Interacting with MongoDB Collections

let coll = client.db("media").collection("movies");
coll.insert_one(doc!{ "title": "Back to the Future" }, None).unwrap();
coll.update_one(doc!{}, doc!{ "director": "Robert Zemeckis" }, None).unwrap();
coll.delete_many(doc!{}, None).unwrap();

let mut cursor = coll.find(None, None).unwrap();
for result in cursor {
    if let Ok(item) = result {
        if let Some(&Bson::String(ref title)) = item.get("title") {
            println!("title: {}", title);
        }
    }
}

The driver provides an intuitive interface for monitoring and responding to runtime information about commands being executed on the server. Arbitrary functions can be used as start and completion hooks, reacting to command results from the server.

fn log_query_duration(client: Client, command_result: &CommandResult) {
    match command_result {
        &CommandResult::Success { duration, .. } => {
            println!("Command took {} nanoseconds.", duration);
        },
        _ => println!("Failed to execute command."),
    }
}

let mut client = Client::connect("localhost", 27017).unwrap();
client.add_completion_hook(log_query_duration).unwrap();

Topology Monitoring

Each server within a MongoDB server set is monitored asynchronously for changes in status, and the driver's view of the current topology is updated in response to this. This allows the driver to be aware of the status of the server set it is communicating with, and to make server selections appropriately with regards to the user-specified ReadPreference and WriteConcern.

Connection Pooling

Each server within a MongoDB server set is maintained by the driver with a separate connection pool. By default, each pool has a maximum of 5 concurrent open connections.

Re-exports

pub use error::Error;

pub use error::ErrorCode;

pub use error::Result;

Modules

coll	Interface for collection-level operations.
common	Library-wide utilities.
compat	Backward compatibility
connstring	Connection string parsing and options.
cursor	Iterable network cursor for MongoDB queries.
db	Interface for database-level operations.
error	MongoDB Errors and Error Codes.
gridfs	Specification for storing and retrieving files that exceed 16MB within MongoDB.
macros
oid	ObjectId
ordered	A BSON document represented as an associative HashMap with insertion ordering.
pool	Connection pooling for a single MongoDB server.
r2d2_mongo
spec	Constants derived from the BSON Specification Version 1.1.
stream
topology	MongoDB server set topology and asynchronous monitoring.
wire_protocol	Low-level client-server communication over the MongoDB wire protocol.

Macros

bson	Construct a bson::BSON value from a literal.
doc	Construct a bson::Document value.

Structs

ClientInner	Interfaces with a MongoDB server or replica set.
ClientOptions	Configuration options for a client.
CommandStarted	Contains the information about a given command that started.
Decoder	Serde Decoder
Encoder	Serde Encoder
TimeStamp	`TimeStamp` representation in struct for serde serialization
UtcDateTime	`DateTime` representation in struct for serde serialization

Enums

Bson	Possible BSON value types.
CommandResult	Contains the information about a given command that completed.
CommandType	Executable command types that can be monitored by the driver.
DecoderError	Possible errors that can arise during decoding.
EncoderError	Possible errors that can arise during encoding.
ValueAccessError	Error to indicate that either a value was empty or it contained an unexpected type, for use with the direct getters.

decode_document	Attempt to decode a `Document` from a byte stream.
decode_document_utf8_lossy	Attempt to decode a `Document` that may contain invalid UTF-8 strings from a byte stream.
encode_document	Attempt to encode a `Document` into a byte stream.
from_bson	Decode a BSON `Value` into a `T` Deserializable.
to_bson	Encode a `T` Serializable into a BSON `Value`.

Type Definitions

Array	Alias for `Vec<Bson>`.
Client
DecoderResult	Alias for `Result<T, DecoderError>`.
Document	Alias for `OrderedDocument`.
EncoderResult	Alias for `Result<T, EncoderError>`.
ValueAccessResult	Result of accessing Bson value