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

v2.0.0

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0 release of the bson crate. This release is the culmination of several months of work, and it contains a number of new features, API improvements, and bug fixes. This release will be included in v2.0.0 of the driver. It is intended that this release will be very stable and that bson will not have another major release for quite a long time.

Note that the new minimum supported Rust version (MSRV) is now 1.48.0.

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.

Ensure API meets the Rust API Guidelines (RUST-765)

There is a community maintained list of API guidelines that every stable Rust library is recommended to meet. The crate's existing API wasn't conforming to these guidelines exactly, so a number of improvements were made to ensure that it does. Here we highlight a few of the more important changes made in this effort.

Stabilize or eliminate public dependencies on unstable crates (C-STABLE, RUST-739)

bson included types from a number of unstable (pre-1.0) dependencies in its public API, which presented a problem for the stability of the library itself. In an effort to ensure that bson will no longer be subject to the semver breaks of unstable dependencies and can stay on 2.0 for the foreseeable future, the public dependencies on unstable types were removed altogether or gated behind feature flags.

Here are the notable changes made as part of that:

• Bson::DateTime(chrono::DateTime<Utc>) => Bson::DateTime(bson::DateTime), struct Datetime(pub chrono::DateTime) => struct DateTime { /* private fields */ }
  • Instead of directly including a DateTime from chrono (which is currently 0.4) in the Bson enum, the variant now wraps the bson::DateTime newtype defined within bson, and that newtype also no longer wraps a chrono::DateTime. This way the dependency on chrono can be updated to new semver breaking versions without having to update bson's major version.
  • To ease in the construction and usage of the newtype from chrono::DateTime, the chrono-0_4 feature flag can be enabled, which includes a From<chrono::DateTime> implementation for bson::DateTime and a From<bson::DateTime> implementation for chrono::DateTime, as well as some serde helpers.
• Document::get_datetime returns a ValueAccessResult of &bson::DateTime instead of &chrono::DateTime
• Bson::as_datetime returns an Option of &bson::DateTime instead of &chrono::DateTime
• ObjectId::timestamp returns a crate::DateTime instead of chrono::DateTime
• oid::Error no longer wraps hex::FromHexError (the hex crate is 0.4), see below for details.
• The Uuid serde helpers, as well as From<Uuid> implementations for Bson and Binary, are now gated behind the uuid-0_8 feature flag.

Accept impl AsRef<str> in Document methods (C-GENERIC, RUST-765)

The methods on Document that accepted keys previously accepted them as &str. They were updated to accept impl AsRef<str> instead to allow other string-like types to be used for key lookup, such as String.

Use more standard conversion constructors for ObjectId (C-CONV-TRAITS, C-CTOR, RUST-789)

ObjectId previously had three constructors: new, with_bytes, and with_string. The latter two were a bit inconsistent with the functions they performed and with similar constructors for related types in the Rust ecosystem. To remedy this, the constructors were updated to match uuid::Uuid's constructor API:

• ObjectId::with_bytes => const ObjectId::from_bytes
• ObjectId::with_string => ObjectId::parse_str

Error naming improvements (C-WORD-ORDER, C-STABLE)

Some error variants were renamed or restructured to be clearer or more informative. A complete summary of the changes are as follows:

• bson::de::Error:
  • IoError => Io
  • FromUtf8Error => InvalidUtf8String
  • SyntaxError => removed, consolidated into DeserializationError.
  • InvalidTimestamp(i64) => InvalidDateTime { key: String, datetime: i64 }
• bson::ser::Error:
  • IoError => Io
  • InvalidMapKeyType { key: Bson } => InvalidDocumentKey(Bson)
  • UnsupportedUnsignedType => removed
  • UnsignedTypesValueExceededRange => UnsignedIntegerExceededRange(u64)
• oid::Error:
  • ArgumentError => removed
  • FromHexError => removed, replaced by the new InvalidHexStringCharacter and InvalidHexStringLength variants

Other miscellaneous changes

There were some other smaller breaking changes made as part of this as well:

• Ensure public structs are future proof by marking them as non_exhaustive (C-STRUCT-PRIVATE)
• document::DocumentIterator and document::DocumentIntoIterator renamed to document::Iter and document::IntoIter (C-ITER-TY)

Enable the u2i behavior by default (RUST-968)

In the 1.x version of bson, unsigned integers could not be serialized to BSON by default, but the u2i feature flag could be enabled to allow them to be serialized by automatically converting them to signed integers. After some investigation, it was determined that this u2i behavior was more consistent with the behavior of BSON libraries in other languages with unsigned integers, so bson now exhibits it by default, and the u2i feature flag was removed.

Implement Clone on all error types (RUST-738)

Previously many of the error types did not implement Clone, partially because many of them wrapped std::io::Error. Not implementing Clone made these errors difficult to work with, since they needed to be wrapped in an Arc or Rc in order to be passed around without transferring ownership. To avoid that requirement, we implemented Clone on all of the error types in bson. For the errors that wrapped std::io::Error, this required wrapping the wrapped std::io::Errors in Arcs.

Implement Copy for ObjectId (RUST-680)

Since ObjectId is just a wrapper around a 12-byte array, it is cheap to copy and therefore ought to implement Copy. As part of this, helpers on Document and Bson were updated to return owned ObjectIds instead of references to them.

Thanks to @jcdyer for contributing this change!

Replace linked-hash-map with indexmap (RUST-283)

The dependency on the now unmaintained linked-hash-map was replaced with the more up-to-date indexmap. While this isn't a breaking change on its own, the Entry API of Document was updated to match both that of std::collections::HashMap and indexmap in a breaking way.

Replace compat::u2f with serde helpers (RUST-756)

The compat::u2f module has long existed to provide a way to serialize unsigned integers as BSON doubles, but it is inconsistent with the API we provide for these kinds of conversions today, namely the serde_helpers functions and modules. In order to present a more consistent API, the compat::u2f module was removed and most of its conversion helpers were rewritten as serde_helpers.

Remove the decimal128 feature flag (RUST-960, #287)

It was determined that the BSON serialization format that was used when the experimental decimal128 feature flag was enabled did not match the format expected by the database or other MongoDB tools and drivers. Because of this, the feature flag has been removed, as there was no way to use it correctly. See #282 for more details.

If you were relying on this feature flag or are just interested in a complete decimal128 implementation, please let us know on #53.

Support for serialization to and deserialization from BSON bytes (RUST-870, RUST-871, #276, #279)

This release adds support for direct serialization to and deserialization from BSON bytes via bson::to_vec and bson::from_slice / bson::from_reader, eliminating the need to go through Document when converting between Rust data types and BSON bytes. This can enable significant performance improvements in certain circumstances; most notably, this will greatly improve the performance of the MongoDB driver, which in 2.0.0 will begin leveraging this functionality.

Properly produce and ingest RFC 3339 (ISO 8601) datetimes in serde helpers (RUST-825)

The iso_string_as_bson_datetime and bson_datetime_as_iso_string serde helpers were not producing or only accepting valid ISO 8601 strings. This has been fixed, and the helpers have been renamed to rfc3339_string_as_bson_datetime and bson_datetime_as_rfc3339_string to more accurately reflect the standard they conform to.

Introduce serde helpers for legacy UUID formats (RUST-687)

The Python, Java, and C# drivers all used to serialize UUIDs with different legacy formats, none of which were supported by the existing UUID serde helper. To add support for serializing and deserializing these UUIDs, new serde helpers were introduced for each of the legacy formats. These helpers are also gated behind the "uuid-0_8" feature flag.
...

v2.0.0-beta.3

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.3 release of the bson crate. This is the fourth beta release in preparation for the 2.0.0 stable release, and it contains a few improvements and bug fixes that were not included in the previous betas. This release will be included in v2.0.0-beta.3 of the driver. As with the previous beta releases, we do not intend to make any further breaking changes before v2.0.0, but we may do so in another beta if any issues arise before then.

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.

Remove the decimal128 feature flag (RUST-960, #287)

It was determined that the BSON serialization format that was used when the experimental decimal128 feature flag was enabled did not match the format expected by the database or other MongoDB tools and drivers. Because of this, the feature flag has been removed, as there was no way to use it correctly. See #282 for more details.

If you were relying on this feature flag or are just interested in a complete decimal128 implementation, please let us know on #53.

Support for serialization to and deserialization from BSON bytes (RUST-870, RUST-871, #276, #279)

This release adds support for direct serialization to and deserialization from BSON bytes via bson::to_vec and bson::from_slice / bson::from_reader, eliminating the need to go through Document when converting between Rust data types and BSON bytes. This can enable significant performance improvements in certain circumstances; most notably, this will greatly improve the performance of the MongoDB driver, which in 2.0.0-beta.3 will begin leveraging this functionality.

Full Release Notes

Bugfixes

• RUST-884 Support deserializing DateTimes between the year 10,000 and 99,999
• RUST-942 Generate 5 random bytes instead of 3 for ObjectIds (#284)

New Features

• RUST-688 Support for borrowed deserialization (#276)
• RUST-870 Support deserializing directly from raw BSON (#276)
• RUST-871 Support serializing directly to BSON bytes (#279)

Improvements

• RUST-889 Avoid going through hex string when deserializing ObjectId from raw bytes (#287)
  • Thanks @univerz for the POC for this!
• RUST-960 Remove decimal128 feature flag and functionality (breaking)
• RUST-882 Remove lossy From<u64> impl for Bson (#280) (breaking)