Avocado

The Strongly-Typed MongoDB Driver

Avocado is a client library for using MongoDB in Rust with Domain-Driven Design in mind. It is built around the excellent mongodb crate.

Avocado is not your average, Node.JS-style "dump a heap of arbitrary JSON into the DB and hope for the best" Mongo driver. Instead, more in line with the spirit of Rust, it encourages:

• working directly with domain model objects,
• the use of homogeneous collections, and
• extensive static type checking

in order to reduce the possibility of errors.

Quick Start Guide

As usual, the online documentation is hosted on docs.rs. This includes a tutorial-style introduction to the usage of Avocado.

"Batteries included" examples can be found in the Git repository.

Avocado is easy to install because it is hosted on crates.io. Just add this to your Cargo.toml:

Why Avocado?

There are other MongoDB abstractions for Rust providing static type checking. The most notable one is Wither. However, Avocado takes a different approach to API design, which, I would like to believe, has more advantages.

More type-safe and more flexible

• Avocado supports query-like operations of which the result is not a full document. For example, it is possible to retrieve only the name of a person (in a type-safe manner, of course) without the need to go through a Document. This includes aggregation pipelines, too.
• Avocado uses a parametric Uid type instead of a raw ObjectId, so incorrect code like user.id == department.id doesn't compile.
• The underlying raw type of UIDs can be changed to anything that implements Eq and is (de)serializable; there's built-in support for ObjectId (of course) and Uuid.
• The prelude provides useful literal types for lesser dynamic typing and more expressive code when creating raw BSON literals (e.g. Order and IndexType.)

Incremental API

• If all you want is to insert some entities and executie simple queries on them, it's possible to use raw BSON Documents. Methods on Collection don't even take an "options" argument because sensible defaults are provided, so you don't have to write None or Default::default() all the time for what is basically a dummy argument.
• If, however, you want to perform more complex manipulations or change the default reading/writing options, then the Query, Pipeline, Update, etc. traits can be implemented and customized manually, in great detail.

Designed with performance in mind

Avocado supports Cursors, obviating the need for collecting all results in a Vec. Useful for incremental retrieval of large result sets.

Great derive macro

The index syntax in #[derive(Doc)] is more convenient and more natural for:

• Compound indices
• Embedded document fields

Encourages clean code

• Documents are grouped into collections, closely mirroring the MongoDB model. You don't have to pass the entire DB handle around (and clone it every time). This aids interface segregation and the principle of least privilege, as it's possible to create "repositories" based on individual types: they only depend on some collections, and they don't need to have access to the entire database.
• Collections are the only "active" part. Documents are treated as naive value types for all purposes, so we're not trying to mimic the "active record pattern" — since that is basically impossible to do 100% correctly.

How does it work?

Avocado's data model is based closely on MongoDB's collections and documents, but with types. The Doc trait is the central element in this: it defines an interface for a type to be considered a top-level entity. Entity types have to be serializable using Serde, and anything serializable can go into them. Most notably, this includes enum types, which are usually a second-class citizen in the world of ORMs. A #[derive] proc-macro aids users in quickly and painlessly implementing this trait with sensible defaults for their own domain model types.

A Collection is generic over its document type. It has methods for inserting, retrieving, modifying and deleting one or more entities, as well as purging the collection or (re-)creating its indices.

Some programmers praise MongoDB and NOSQL in general for its schemaless nature, because it's more convenient to extend and adapt databases that way. If you are one of these programmers, Avocado is probably not for you. In fact, Avocado includes support for run-time schema validation, via the Magnet crate. As this can be slow if you are performing many insertions, the decision of whether or not to actually apply it is left to the user: collections can be created in either of two ways, one of them includes JSON schema validation, the other one does not.

Reaching Out

• Tweet to me @H2CO3_iOS
• Look at the issues on GitHub