Skip to content

v2.0.0-beta.1

Pre-release
Pre-release
Compare
Choose a tag to compare
@patrickfreed patrickfreed released this 01 Jun 19:04
v2.0.0-beta.1
2e6bb8f

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.1 release of the bson crate. This is the second beta release in preparation for the 2.0.0 stable release, and it contains a few breaking changes, API improvements, and bug fixes that were not included in the first beta. This release will be included in v2.0.0-beta.1 of the driver. As with the previous release, 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 breaking changes included in this release. For a full list of changes, see the Full Release Notes section.

bson::DateTime truncates to millisecond precision (RUST-815)

In the previous beta, we included a change that made it an error to attempt to serialize a chrono::DateTime or bson::DateTime that had nonzero microseconds or nanoseconds, since BSON itself only supports millisecond precision. In practice, this ended up being difficult to deal with and broke users' existing code. To remedy this, serializing a chrono::DateTime via the chrono_datetime_as_bson_datetime serde helper automatically truncates the serialized date to millisecond precision rather than returning an error. Similarly, when converting to a bson::DateTime from a chrono::DateTime, the microseconds and nanoseconds are discarded.

Thanks to @vkill for contributing this change!

bson::DateTime ergonomic improvements (RUST-811)

In the first beta, some changes were made to reduce the public dependency on the unstable chrono crate in the public API. This had the unintended effect of making converting between bson::DateTime and chrono::DateTime cumbersome and difficult to discover. To improve on that situation, the bson::DateTime::from_chrono and bson::DateTime::to_chrono methods were introduced to make conversion easier and more explicit.

Given the now expanded presence of chrono, a pre 1.0 crate, in the public API from these changes, these new methods and the existing From implementations were moved to behind the "chrono-0_4" feature flag. This will enable us to continue to add support for new major versions of chrono without having to worry about polluting the public API surface or having to break it altogether. Once chrono reaches 1.0, such support will be included by default without the need for a feature flag. Note that the serde helpers that involve chrono had their version numbers dropped from their names as part of this.

To enable the bson::DateTime type to be more useful on its own, the following methods were also introduced:

  • DateTime::now
  • DateTime::from_millis
  • DateTime::from_system_time
  • DateTime::to_system_time

Better handling of datetimes that are very far from the Unix epoch (RUST-799)

In BSON, any datetime within the range of a signed 64-bit integer of milliseconds from the Unix epoch is supported. This is not the case for chrono::DateTime, however, which led to deserialization errors or panics when dates outside of the chrono::DateTime's range were encountered. This has been fixed, and now bson::DateTime can represent any datetime that can be represented in BSON.

Note that bson::DateTime::to_chrono will convert the date to chrono::MAX_DATETIME or chrono::MIN_DATETIME if attempting to convert directly would result in an error.

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.

uuid serde helpers were moved behind the "uuid-0_8" feature flag

For consistency with the chrono changes, the uuid serde helpers were moved behind the "uuid-0_8" feature flag. This also will help prevent the public API from being filled with support for outdated versions of the uuid crate as new versions are released. Once uuid reaches 1.0, such support will be included by default without the need for a feature flag. Note that the serde helpers that involve uuid had the version numbers dropped from their names as part of this.

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.

Thanks to @kenkoooo for contributing this change!

Full Release Notes

New Features

Bugfixes

  • RUST-799 Fix errors and panics caused by datetimes with large distance to epoch
  • RUST-825 Update serde helpers to properly conform with RFC 3339 (ISO 8601) (breaking)

Improvements

  • RUST-811 bson::DateTime ergonomic improvements (breaking)
  • RUST-815 Truncate chrono::DateTime to millisecond precision when converting to bson::DateTime (breaking) (thanks @vkill!)
  • RUST-826 Take ownership of self in ObjectId::to_hex (breaking)
Assets 2
Loading