ameobea / bson-rs

Encoding and decoding support for BSON in Rust

bson-rs

Encoding and decoding support for BSON in Rust

Useful links

• API Documentation
• Serde

Installation

This crate works with Cargo and can be found on crates.io with a Cargo.toml like:

[dependencies]
bson = "0.11"

Usage

Link the library in main.rs:

#[macro_use(bson, doc)]
extern crate bson;

Prepare your struct for Serde serialization:

#[derive(Serialize, Deserialize, Debug)]
pub struct Person {
    #[serde(rename = "_id")]  // Use MongoDB's special primary key field name when serializing 
    pub id: String,
    pub name: String,
    pub age: i32
}

Serialize the struct:

use bson;

let person = Person {
    id: "12345",
    name: "Emma",
    age: 3
};

let serialized_person = bson::to_bson(&person)?;  // Serialize

if let bson::Bson::Document(document) = serialized_person {
    mongoCollection.insert_one(document, None)?;  // Insert into a MongoDB collection
} else {
    println!("Error converting the BSON object into a MongoDB document");
}

Deserialize the struct:

// Read the document from a MongoDB collection
let person_document = mongoCollection.find_one(Some(doc! { "_id": "12345" }), None)?
    .expect("Document not found");

// Deserialize the document into a Person instance
let person = bson::from_bson(bson::Bson::Document(person_document))?

Breaking Changes

In the BSON specification, unsigned integer types are unsupported; for example, u32. In the older version of this crate (< v0.8.0), if you uses serde to serialize unsigned integer types into BSON, it will store them with Bson::FloatingPoint type. From v0.8.0, we removed this behavior and simply returned an error when you want to serialize unsigned integer types to BSON. #72

For backward compatibility, we've provided a mod bson::compat::u2f to explicitly serialize unsigned integer types into BSON's floating point value as follows:

#[test]
fn test_compat_u2f() {
    #[derive(Serialize, Deserialize, Eq, PartialEq, Debug)]
    struct Foo {
        #[serde(with = "bson::compat::u2f")]
        x: u32
    }

    let foo = Foo { x: 20 };
    let b = bson::to_bson(&foo).unwrap();
    assert_eq!(b, Bson::Document(doc! { "x": Bson::FloatingPoint(20.0) }));

    let de_foo = bson::from_bson::<Foo>(b).unwrap();
    assert_eq!(de_foo, foo);
}

In this example, we added an attribute #[serde(with = "bson::compat::u2f")] on field x, which will tell serde to use the bson::compat::u2f::serialize and bson::compat::u2f::deserialize methods to process this field.