v2.6.1

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

Highlighted Changes

This release updates the documentation for the Decimal128 type to demonstrate conversion to and from human-readable strings.

Full Release Notes

Improvements

• RUST-1617 Update documentation for Decimal128 type

v2.6.0

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

Highlighted Changes

This release includes support for conversion between human-readable strings and the Decimal128 BSON type. It also adds tests to verify that the Rust BSON library builds on WASM.

Full Release Notes

New Features

• RUST-1592 Support decimal128 to/from human-readable strings (#404)

Improvements

• minor: improve serde documentation of DateTime and ObjectId (#401)
• RUST-504 Use js timestamps when generating objectids (#406)

Tasks

• RUST-1613 Update feature flags table (#407)

v2.5.0

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

Highlighted Changes

This release sees the addition of a wide variety of helper functions, largely focused on making common type conversions more convenient:

• Binary::from_base64 allows constructing a Binary value from a base64-encoded string without having to use another crate.
• i64_as_bson_datetime provides Serde helpers for representing bson DateTime values as rust i64 fields.
• Binary::as_raw_binary and RawBinaryRef::to_binary allow easy interconversion between the parsed and raw slice reference types for binary data.
• RawBson and RawDocumentBuf now implement TryFrom for their respective parsed types (Bson and Document).
• Document::iter_mut provides an iterator over mutable references to the contained Bson values.

Full Release Notes

New Features

• RUST-1385 Add binary/raw conversions (#370)
• RUST-1480 Add a TryFrom impl for RawBson (#373)
• RUST-1534: implement iter_mut on Document (#382)
• RUST-1540 impl i64_as_datetime (#383)
• RUST-1225 Add base64 string constructor to Binary (#365)
• RUST-1540 Rename i64_as_datetime to i64_as_bson_datetime (#393)

Improvements

• docs(readme): fix broken hyperlink (#375) (thanks satyarohith!)
• RUST-1062 More efficiently serialize array indexes (#384)
• Fix links in the Feature Flags table. (#388) (thanks judy2k!)
• RUST-782 Add hyperlinks for all types in rustdoc (#389)

Tasks

• RUST-1440 bump bson clippy version to 1.63.0 (#372)
• fix for stale issues action
• minor: bump clippy to 1.65 (#387)

v2.4.0

Description

The MongoDB Rust driver team is pleased to announce the v2.4.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.

Support for 1.x of the uuid crate

The bson crate now has a uuid-1 feature that provides an API for interoperation with versions 1.x of the uuid crate, similar to the existing uuid-0_8 feature. Internal usage of uuid now uses 1.x, so downstream crates without a need for 0.8 will no longer transitively depend on both version.

Builder for DateTime values

The DateTime type now provides a builder that allows convenient construction from a given year, month, day, and optionally, an hour, minute, second and millisecond.

Full Release Notes

New Features

• RUST-1305 Add support for version 1.x of the uuid crate to the bson crate
• RUST-1198 Support creating bson::DateTime from a given year/month/date/hour/minute/second/millisecond

Tasks

• RUST-1398 Pin clippy version to 1.62.0
• RUST-1374 Pin all dependencies when checking MSRV compilation

v2.3.0

Description

The MongoDB Rust driver team is pleased to announce the 2.3.0 release of the bson crate. This release increases the crate's MSRV to 1.53 and makes the crate's dependency on chrono optional.

Full Release Notes

Task

• RUST-1263 Bump MSRV to 1.53 (#352)

Improvement

• RUST-1129 Replace chrono dependency with time (#352)

v2.2.0

Description

The MongoDB Rust driver team is pleased to announce the v2.2.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.

Raw BSON (RUST-284, RUST-1045, RUST-1082, RUST-1109, RUST-1111, RUST-1119)

Both of the existing ways of working with BSON values (the BSON type or using Serde) require parsing the values up-front. This can be a performance bottleneck in certain circumstances; to address this, we've introduced the RawBson, RawDocument, and RawArray types.

These types provide an interface similar to the existing BSON types, but are backed by a buffer of BSON bytes rather than a fully parsed enum or hash map. This enables zero-copy reads with minimal parsing and highly memory-efficient manipulation.

In tradeoff, these types do not provide the full set of operations that the standard ones can, and the performance of element access is O(N) rather than then average O(1) of the parsed types.

Thanks to @jcdyer for contributing the initial implementation!

Full Release Notes

New Features

• RUST-284 Incorporate raw BSON code from rawbson = "0.2.1" in mod raw (#229)
• RUST-1045 Support appending to RawDocumentBuf (#326)
• RUST-1109 Implement rawbson! and rawdoc! macros (#329)
• RUST-1119 Add bson::to_raw_document_buf function (#330)
• RUST-1111 Support deserializing RawBson from Bson (#331)
• minor: raw BSON perf and API improvements (#335)

Bugfixes

• RUST-1243 Handle enum keys when deserializing a map from binary (#348) (thanks @George-Miao!)
• RUST-1240 Fix potential underflow in length counting (#349)
• RUST-1195 Add missing trait impls to Uuid (#345)

v2.2.0-beta.1

Description

The MongoDB Rust driver team is pleased to announce the v2.2.0-beta.1 release of the bson crate. This is the second beta release in preparation for the 2.2.0 stable release, and it contains some bug fixes that were not included in the first beta.

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.

Map types with enum keys (RUST-1243)

This release fixes deserialization of map types using enum values as the keys; in the prior beta release this would fail with an "invalid type: string" error.

Thanks to @George-Miao for reporting this bug!

Length underflow in binary deserialization (RUST-1240)

This release fixes a bug that caused parsing to erroneously continue when reading invalid length values. This bug would not have caused unsafe behavior (all binary buffer access is checked) but could have caused runtime panics or garbage parse results.

Full Release Notes

Bugfixes

• RUST-1243 Handle enum keys when deserializing a map from binary (#348)
• RUST-1240 Fix potential underflow in length counting (#349)

v2.2.0-beta

Description

The MongoDB Rust driver team is pleased to announce the v2.2.0-beta 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.

Raw BSON (RUST-284, RUST-1045, RUST-1082, RUST-1109, RUST-1111, RUST-1119)

Both of the existing ways of working with BSON values (the BSON type or using Serde) require parsing the values up-front. This can be a performance bottleneck in certain circumstances; to address this, we've introduced the RawBson, RawDocument, and RawArray types.

These types provide an interface similar to the existing BSON types, but are backed by a buffer of BSON bytes rather than a fully parsed enum or hash map. This enables zero-copy reads with minimal parsing and highly memory-efficient manipulation.

In tradeoff, these types do not provide the full set of operations that the standard ones can, and the performance of element access is O(N) rather than then average O(1) of the parsed types.

Thanks to @jcdyer for contributing the initial implementation!

Full Release Notes

New Features

• RUST-284 Incorporate raw BSON code from rawbson = "0.2.1" in mod raw (#229)
• RUST-1045 Support appending to RawDocumentBuf (#326)
• RUST-1109 Implement rawbson! and rawdoc! macros (#329)
• RUST-1119 Add bson::to_raw_document_buf function (#330)
• RUST-1111 Support deserializing RawBson from Bson (#331)
• minor: raw BSON perf and API improvements (#335)

Bugfixes

• RUST-1195 Add missing trait impls to Uuid (#345)

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!)

v2.1.0-beta

Description

The MongoDB Rust driver team is pleased to announce the v2.1.0-beta release of the bson crate. This release is a preview of the upcoming v2.1.0 release, which will be functionally the same but may contain fixes for any bugs identified in this beta.

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!)