#mongodb #database #bson #nosql #odm

wither

An ODM for MongoDB built upon the mongo rust driver

15 releases (8 breaking)

0.9.0-alpha.1 Jun 12, 2020
0.8.0 Dec 30, 2018
0.7.0 Nov 25, 2018
0.5.2 Apr 12, 2018
0.5.0 Nov 27, 2017

#45 in Database interfaces

Download history 111/week @ 2020-04-14 52/week @ 2020-04-21 103/week @ 2020-04-28 20/week @ 2020-05-05 166/week @ 2020-05-12 81/week @ 2020-05-19 111/week @ 2020-05-26 63/week @ 2020-06-02 67/week @ 2020-06-09 93/week @ 2020-06-16 23/week @ 2020-06-23 149/week @ 2020-06-30 182/week @ 2020-07-07 123/week @ 2020-07-14 52/week @ 2020-07-21 56/week @ 2020-07-28

459 downloads per month

Apache-2.0

48KB
624 lines

wither

An ODM for MongoDB built on the official MongoDB Rust driver. Please ⭐ on github!

Build Status Crates.io docs.rs License Crates.io


The primary goal of this project is to provide a simple, sane & predictable interface into MongoDB based on data models. If at any point this system might get in your way, you have direct access to the underlying driver. This project is tested against MongoDB 3.6, 4.0 & 4.2.

GREAT NEWS! Wither is now based on the official MongoDB Rust driver. Thanks to advancements in the driver, Wither is now fully asynchronous. Simply mirroring the features of the underlying MongoDB driver, Wither supports the following runtimes:

Due to updates in the underlying driver, there is a fair number of breaking changes in the Model trait, as well as the Model derive macro. Details can be found in the changelog and the documentation. Furthermore, everything is now async by default. The sync interface has been completely disabled, and is pending removal from the repo. Head over to wither#52 and let me know if you still need sync support.

items of interest

getting started

To get started, simply derive Model on your struct along with a few other serde derivations. Let's step through a full example.

use futures::stream::StreamExt;
use serde::{Serialize, Deserialize};
use wither::{prelude::*, Result};
use wither::bson::{doc, oid::ObjectId};
use wither::mongodb::Client;

// Define a model. Simple as deriving a few traits.
#[derive(Debug, Model, Serialize, Deserialize)]
#[model(index(keys=r#"doc!{"email": 1}"#, options=r#"doc!{"unique": true}"#))]
struct User {
    /// The ID of the model.
    #[serde(rename="_id", skip_serializing_if="Option::is_none")]
    pub id: Option<ObjectId>,
    /// The user's email address.
    pub email: String,
}

#[tokio::main]
async fn main() -> Result<()> {
    // Connect & sync indexes.
    let db = Client::with_uri_str("mongodb://localhost:27017/").await?.database("mydb");
    User::sync(db.clone()).await?;

    // Create a user.
    let mut me = User{id: None, email: String::from("my.email@example.com")};
    me.save(db.clone(), None).await?;

    // Update user's email address.
    me.update(db.clone(), None, doc!{"$set": doc!{"email": "new.email@example.com"}}, None).await?;

    // Fetch all users.
    let mut cursor = User::find(db.clone(), None, None).await?;
    while let Some(user) = cursor.next().await {
        println!("{:?}", user);
    }
    Ok(())
}

PLEASE NOTE: as of the 0.9.0-alpha.0 release, corresponding to the mongodb 1.0 release, index management has not yet been implemented in the mongodb driver, and thus the index syncing features of Model::sync have been temporarily disabled. The hope is that the mongodb team will be able to land their index management code in the driver soon, at which point we will re-enable the Model::sync functionality.

If this is important to you, please head over to wither#51 and let us know!

next steps

And that's all there is to it. Now you are ready to tackle some of the other important parts of the model lifecycle. Some additional items to look into:

  • deriving model - learn more about automatically deriving the Model trait on your structs.
  • model usage - check out some of the other methods available to you from your models.
  • syncing indexes - learn how to synchronize a model's indexes with the database.
  • logging - learn how to hook into this crate's logging mechanisms.
  • migrations - learn about defining migrations to be run against your model's collection.

Good luck on the path.

Dependencies

~8.5MB
~188K SLoC