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:

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:

avocado = "*"

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

Incremental API

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:

Encourages clean code

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