v2.1.0

Description

The MongoDB Rust driver team is pleased to announce the v2.1.0 release of the bson crate.

Highlighted changes

The following sections detail some of the more important changes included in this release. For a full list of changes, see the Full Release Notes section below.

Better Uuid ergonomics (RUST-819, RUST-465, RUST-1024)

Working with UUIDs in BSON is a bit of a pain point, since the widely used Uuid type from the uuid crate doesn't serialize to or from BSON UUIDs (i.e. Binary with subtype 4) out of the box. To address this, we introduced a bson::Uuid type, which serializes as a BSON UUID when using bson::to_bson or bson::to_slice and uses uuid::Uuid's Serialize implementation for other formats.

Additionally, we implemented the UUID driver specification, which enables easy conversion between Binary and bson::Uuid. It also adds support for handling BSON UUIDs that may have been serialized using the legacy format from one of the other MongoDB drivers (Python, Java, or C#).

Lastly, we introduced support for using the serde_with crate to serialize uuid::Uuids to BSON. This requires the usage of the serde_with and uuid-0_8 feature flags. See the next section for more details.

serde_with integration (RUST-1024)

As mentioned in the previous section, we've added optional support for the serde_with crate via the serde_with feature flag. Right now, this allows for serialization of chrono::DateTime as bson::DateTime (with the chrono-0_4 feature flag) and uuid::Uuid as bson::Uuid (with the uuid-0_8 feature flag). The main improvement of serde_with annotations over the existing serde helpers is that they also work when the Uuid or DateTime type is nested, such as in an Option.

#[serde_with::serde_as]
#[derive(Serialize, Deserialize, Debug)]
struct MyData {
    #[serde_as(as = "Option<bson::Uuid>")]
    uuid: Option<uuid::Uuid>,

    #[serde_as(as = "Option<bson::DateTime>")]
    dt: Option<chrono::DateTime<chrono::Utc>>,
}

let val = MyData {
    uuid: Some(uuid::Uuid::new_v4()),
    dt: chrono::Utc::now().into(),
};

// prints { "uuid": Binary(0x4, mMKbFkXEQMeLnfSNY+/NMg==), "dt": DateTime("2021-11-12 21:14:15.385 UTC") }
println!("{}", bson::to_bson(&val)?);

Support configuring Serializer and Deserializer to be not human-readable (RUST-1022)

Serializer and Deserializer, which are used in bson::(to|from)_(bson|document), have never implemented the is_human_readable requirement from their respective serde traits, meaning they default to true. The raw serializer and deserializer, which are used in bson::to_vec and bson::from_slice, do report as non-human readable though. The unfortunate result of this inconsistency is that types that change their serialized format depending on whether the (de)serializer is human readable or not may produce different BSON depending on whether to_bson or to_vec are used. To help address this issue, this release includes support for configuring Serializer and Deserializer to report themselves as not human readable.

#[derive(Debug, Deserialize, Serialize)]
struct MyData {
    a: String,
}

let data = MyData { a: "ok".to_string() };
let options = SerializerOptions::builder().human_readable(false).build();
let bson = bson::to_bson_with_options(&data, options)?;

let options = DeserializerOptions::builder().human_readable(false).build();
let rt_data: MyData = bson::from_bson_with_options(bson, options)?;

Full Release Notes

New Features

• RUST-465 Create a UUID wrapper type for serialization to / deserialization from BSON binary (#314)
• RUST-977 Support parsing bson::DateTime from RFC 3339 formatting string even without chrono feature flag (#317)
• RUST-1022 Introduce way to serialize to / deserialize from Bson with is_human_readable = false (#321)
• RUST-1024 Add serde_with integration for composable serde helpers (#323)
• RUST-787 Implement Display for all BSON types (#305)
• RUST-966 Add BSON Binary subtype 7 (#315)

Improvements

• Remove time transitive dependency and clock feature flag from chrono (#316)
  • Thanks @roccodev!

Bugfixes

• RUST-1107 Fix array relaxed extended JSON (#325) (thanks @pacifistes!)