NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #2014 most downloaded on crates.io
Encoding and decoding support for BSON in Rust
Latest stable
3.1.0
Last release 1 years ago
20 Nov 2025
Ships fairly regularly
a new release about every 3 months
Most releases are documented
notes for 43 of the last 60 stable releases
2 versions withdrawn
withdrawn after publishing
11 years old
72 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
The MongoDB Rust driver team is pleased to announce the v3.1.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v3.1.0 release of the bson crate.
See this GitHub query for a full list of changes.
For detailed information on breaking changes and code examples, please see the migration guide.
The MongoDB Rust driver team is pleased to announce the v3.0.0 release of the bson crate.
3.0 updates several APIs in backwards-incompatible ways; in most cases these changes should require only minor updates in application code.
Most notably:
bson::error::Error type, with fields for values common across errors like message or associated key and a kind enum that provides granular root cause information.&CStr: The bson crate now provides types that directly model the BSON spec "cstring" type, removing a potential source of panic!s and allowing validation at either run-time or compile-time for constant strings.serde: Integration with serde is now an optional feature; in support of this, the API has been updated to clarify where methods are for encoding (directly converting Rust BSON values into BSON bytes) or for serialization (converting arbitrary Rust structs to BSON values or bytes via the serde crate).For detailed information on breaking changes and code examples, please see the migration guide.
Impactful changes are listed below; for a full list of changes see this GitHub query.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
The MongoDB Rust driver team is pleased to announce the v2.15.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.15.0 release of the bson crate.
This release adds a contributed uncapped_max_size feature; when enabled, this increases the maximum size of a document from 16 MB to 2 GB.
uncapped_max_size feature to allow increasing max BSON size (#528) (thanks @Trevader24135!)The MongoDB Rust driver team is pleased to announce the v2.14.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.14.0 release of the bson crate.
This release adds:
bson::binary::Vector type, providing efficient support for including
densely packed arrays of numeric values in BSON documents,DateTime to add milliseconds and Duration,Index impls for Bson and Document, allowing convenient shorthand element lookup.This release also updates the MSRV to 1.81.
The MongoDB Rust driver team is pleased to announce the v2.13.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.13.0 release of the bson crate.
This release introduces a utility type for deserializing from UTF-8 lossy BSON bytes.
The MongoDB Rust driver team is pleased to announce the v2.12.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.12.0 release of the bson crate.
This release was largely driven by external contributions!
Hash and Eq for the Bson family of typesObjectId::from_parts, allowing direct construction of an ObjectId from its component valuesOption<chrono::DateTime<_>> as Option<bson::DateTime>Decimal128We've also added optional (off by default) integration with the serde_path_to_error crate, which
provides paths to the precise point of failure for deserialization of nested data structures.
Option<chrono::DateTime<_>> as Option<bson::DateTime> (thanks @lazureykis!)This release introduces the HumanReadable helper type; this provides more flexible control than the human_readable option, which is now deprecated.
The MongoDB Rust driver team is pleased to announce the v2.11.0 release of the bson crate.
This release introduces the HumanReadable helper type; this provides more flexible control than the human_readable option, which is now deprecated.
The MongoDB Rust driver team is pleased to announce the v2.10.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.10.0 release of the bson crate.
This release adds several bugfixes and the RawDocumentBuf::append_ref method, providing a method equivalent to append for borrowed data. This can be useful for avoiding the need for intermediate buffers when the source data is borrowed.
The MongoDB Rust driver team is pleased to announce the v2.9.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.9.0 release of the bson crate.
This release adds several externally contributed improvements!
RawIter type that iterates over elements in a document without deserializing them,doc and bson macros (and their raw counterparts) that allows using types that implement Into<Bson> or Into<RawBson>,From<&mut T> for Bson for types that implement Into<Bson>,serde_with 3.x support for the Uuid type.The MongoDB Rust driver team is pleased to announce the v2.8.1 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.8.1 release of the bson crate.
This release fixes compilation for the wasm32-wasi target, which broke in the 2.8.0 release.
The MongoDB Rust driver team is pleased to announce the v2.8.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.8.0 release of the bson crate.
This release adds optimizations to the serde integration that show up to 50% deserialization speed improvement in our benchmarks, as well as a variety of user-submitted fixes.
Cargo.lock.msrv (#436) (thanks @stIncMale!)The MongoDB Rust driver team is pleased to announce the v2.7.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.7.0 release of the bson crate.
This release adds optional integration with serde_with 3.x, duration_since methods to DateTime, and updates some dependencies.
The MongoDB Rust driver team is pleased to announce the v2.6.1 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.6.1 release of the bson crate.
This release updates the documentation for the Decimal128 type to demonstrate conversion to and from human-readable strings.
The MongoDB Rust driver team is pleased to announce the v2.6.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.6.0 release of the bson crate.
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.
The MongoDB Rust driver team is pleased to announce the v2.5.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.5.0 release of the bson crate.
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.The MongoDB Rust driver team is pleased to announce the v2.4.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.4.0 release of the bson crate.
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.
uuid crateThe 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.
DateTime valuesThe DateTime type now provides a builder that allows convenient construction from a given year, month, day, and optionally, an hour, minute, second and millisecond.
clippy version to 1.62.0The 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
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.
chrono dependency with time (#352)The MongoDB Rust driver team is pleased to announce the v2.2.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.2.0 release of the bson crate.
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.
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!
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 th
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.
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.
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!
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.
The MongoDB Rust driver team is pleased to announce the v2.2.0-beta release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.2.0-beta release of the bson crate.
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.
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!
The MongoDB Rust driver team is pleased to announce the v2.1.0 release of the bson crate.
The MongoDB Rust driver team is pleased to announce the v2.1.0 release of the bson crate.
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.
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)?);
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)?;
serde_with integration for composable serde helpers (#323)Display for all BSON types (#305)time transitive dependency and clock feature flag from chrono (#316)
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 releas
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.
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.
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)?);
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)?;
serde_with integration for composable serde helpers (#323)Display for all BSON types (#305)time transitive dependency and clock feature flag from chrono (#316)
Nothing published for this version
There were some other smaller breaking changes made as part of this as well:
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.
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.
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.
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 */ }
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.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::DateTimeBson::as_datetime returns an Option of &bson::DateTime instead of &chrono::DateTimeObjectId::timestamp returns a crate::DateTime instead of chrono::DateTimeoid::Error no longer wraps hex::FromHexError (the hex crate is 0.4), see below for details.Uuid serde helpers, as well as From<Uuid> implementations for Bson and Binary, are now gated behind the uuid-0_8 feature flag.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.
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_bytesObjectId::with_string => ObjectId::parse_strSome 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 => IoFromUtf8Error => InvalidUtf8StringSyntaxError => removed, consolidated into DeserializationError.InvalidTimestamp(i64) => InvalidDateTime { key: String, datetime: i64 }bson::ser::Error:
IoError => IoInvalidMapKeyType { key: Bson } => InvalidDocumentKey(Bson)UnsupportedUnsignedType => removedUnsignedTypesValueExceededRange => UnsignedIntegerExceededRange(u64)oid::Error:
ArgumentError => removedFromHexError => removed, replaced by the new InvalidHexStringCharacter and InvalidHexStringLength variantsThere were some other smaller breaking changes made as part of this as well:
non_exhaustive (C-STRUCT-PRIVATE)document::DocumentIterator and document::DocumentIntoIterator renamed to document::Iter and document::IntoIter (C-ITER-TY)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.
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.
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!
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.
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.
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.
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.
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.
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!
Debug implementation to BSON types (RUST-282)BSON related types now support being pretty-printed via the {:#?} format specifier.
e.g.
let doc = doc! {
"oid": ObjectId::new(),
"arr": Bson::Array(vec! [
Bson::Null,
Bson::Timestamp(Timestamp { time: 1, increment: 1 }),
]),
"doc": doc! { "a": 1, "b": "data"},
};
println!("{:#?}", doc);
Prints the following:
Document({
"oid": ObjectId(
"60d60c360026a43f00e47007",
),
"arr": Array([
Null,
Timestamp {
time: 1,
increment: 1,
},
]),
"doc": Document({
"a": Int32(
1,
),
"b": String(
"data",
),
}),
})
From<Option<T>> for Bson where T: Into<Bson> (RUST-806)A blanket From<Option<T>> implementation was added for T that implement Into<Bson>. If the value is Some(T), the T is converted into Bson using T's Into implementation, and if it's None, it will be converted into Bson::Null.
A nice benefit of this is that Option<T> can now be used in the bson! and doc! macros directly:
let some: Option<i32> = Some(5);
let none: Option<i32> = None;
let doc = doc! {
"some": some,
"none": none,
};
println!("{}", doc);
Prints:
{ "some": 5, "none": null }
Copy for ObjectId (breaking)ObjectId (thanks @moka491!)Clone on BSON error types (breaking)From<Option<T>> for Bson where T: Into<Bson>ObjectId::bytes as constserialize_object_id_as_hex_string serde helperDebug implementation to BSON typeslinked-hash-map with indexmap (breaking)imports_granularity=Crate in rustfmt configcompat::u2f with serde helpers (breaking)ObjectId conversion constructors (breaking)impl AsRef<str> instead of &str in Document methods (breaking)ObjectId from raw bytes (#287)
decimal128 feature flag and functionality (breaking)From<u64> impl for Bson (#280) (breaking)bson::DateTime ergonomic improvements (breaking)chrono::DateTime to millisecond precision when converting to bson::DateTime (breaking) (thanks @vkill!)self in ObjectId::to_hex (breaking)BinarySubtype case for user-defined valuesbson::DateTime::now() performance (thanks @pymongo!)Display and Debug implementations for BsonObjectId from non self-describing formats (thanks for reporting @univerz!)Document's Display implementationrand dependency to 0.8 (thanks @seanpianka!)DateTimes between the year 10,000 and 99,999As 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 issue…
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.
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.
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.
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.
DateTimes between the year 10,000 and 99,999ObjectId from raw bytes (#287)
decimal128 feature flag and functionality (breaking)From<u64> impl for Bson (#280) (breaking)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 issue…
The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.2 release of the bson crate. This is the third beta release in preparation for the 2.0.0 stable release, and it contains a few minor improvements and bug fixes that were not included in the first or second betas. This release will be included in v2.0.0-beta.2 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.
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.
Debug implementation to BSON types (RUST-282)BSON related types now support being pretty-printed via the {:#?} format specifier.
e.g.
let doc = doc! {
"oid": ObjectId::new(),
"arr": Bson::Array(vec! [
Bson::Null,
Bson::Timestamp(Timestamp { time: 1, increment: 1 }),
]),
"doc": doc! { "a": 1, "b": "data"},
};
println!("{:#?}", doc);
Prints the following:
Document({
"oid": ObjectId(
"60d60c360026a43f00e47007",
),
"arr": Array([
Null,
Timestamp {
time: 1,
increment: 1,
},
]),
"doc": Document({
"a": Int32(
1,
),
"b": String(
"data",
),
}),
})
From<Option<T>> for Bson where T: Into<Bson> (RUST-806)A blanket From<Option<T>> implementation was added for T that implement Into<Bson>. If the value is Some(T), the T is converted into Bson using T's Into implementation, and if it's None, it will be converted into Bson::Null.
A nice benefit of this is that Option<T> can now be used in the bson! and doc! macros directly:
let some: Option<i32> = Some(5);
let none: Option<i32> = None;
let doc = doc! {
"some": some,
"none": none,
};
println!("{}", doc);
Prints:
{ "some": 5, "none": null }
From<Option<T>> for Bson where T: Into<Bson>ObjectId::bytes as constserialize_object_id_as_hex_string serde helperDebug implementation to BSON typesBinarySubtype case for user-defined valuesbson::DateTime::now() performance (thanks @pymongo!)Display and Debug implementations for BsonObjectId from non self-describing formats (thanks for reporting @univerz!)Document::extendThis 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 t…
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.
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::nowDateTime::from_millisDateTime::from_system_timeDateTime::to_system_timeIn 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.
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 flagFor 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.
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!
bson::DateTime ergonomic improvements (breaking)chrono::DateTime to millisecond precision when converting to bson::DateTime (breaking) (thanks @vkill!)self in ObjectId::to_hex (breaking)This release contains a number of breaking changes, API improvements, new features, and bug fixes, and it will be included in v2.0.0-beta of the drive…
The MongoDB Rust driver team is pleased to announce the v2.0.0-beta release of the bson crate in preparation for the 2.0.0 stable release. This release contains a number of breaking changes, API improvements, new features, and bug fixes, and it will be included in v2.0.0-beta of the driver. It was not included in the previous driver alpha releases, however.
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.
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.
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 stabilized such that they will always be present.
Here are the notable changes made as part of that:
Bson::DateTime(chrono::DateTime<Utc>) => Bson::DateTime(bson::DateTime)
DateTime from chrono (which is currently 0.4), the variant now wraps the bson::DateTime newtype defined within bson. This way the dependency on chrono can be updated to new semver breaking versions without having to update its major version.From<chrono_0_4::DateTime> is implemented for bson::DateTime, and From<bson::DateTime> is implemented for chrono_0_4::DateTime. As new semver breaking versions of chrono are released, these From implementations will continue to exist, and in new minor versions of bson, new From implementations for the new versions of chrono will be added while continuing to maintain the old ones. This is achieved by having bson depend on multiple semver-incompatible versions of chrono. This way, users of chrono 0.4 will not have their code broken when updating bson versions, but users of chrono 0.5+ will also be able to easily work with bson::DateTime.struct Datetime(pub chrono::DateTime) => struct DateTime { /* private fields */ }
Document::get_datetime returns a ValueAccessResult of &bson::DateTime instead of &chrono::DateTimeBson::as_datetime returns an Option of &bson::DateTime instead of &chrono::DateTimeObjectId::timestamp returns a crate::DateTime instead of chrono::DateTimeoid::Error no longer wraps hex::FromHexError (the hex crate is 0.4), see below for details.serde_helpers that interface with unstable dependencies are versioned
chrono_datetime_as_bson_datetime => chrono_0_4_datetime_as_bson_datetimeimpl 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.
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_bytesObjectId::with_string => ObjectId::parse_strSome 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 => IoFromUtf8Error => InvalidUtf8StringSyntaxError => removed, consolidated into DeserializationError.InvalidTimestamp(i64) => InvalidDateTime { key: String, datetime: i64 }bson::ser::Error:
IoError => IoInvalidMapKeyType { key: Bson } => InvalidDocumentKey(Bson)UnsupportedUnsignedType => UnsupportedUnsignedInteger(u64)UnsignedTypesValueExceededRange => UnsignedIntegerExceededRange(u64)oid::Error:
ArgumentError => removedFromHexError => removed, replaced by the new InvalidHexStringCharacter and InvalidHexStringLength variantsThere were some other smaller breaking changes made as part of this as well:
non_exhaustive (C-STRUCT-PRIVATE)document::DocumentIterator and document::DocumentIntoIterator renamed to document::Iter and document::IntoIter (C-ITER-TY)Decimal128 conversion constructors removed (C-CONV)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.
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!
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.
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.
Copy for ObjectId (breaking)ObjectId (thanks @moka491!)Clone on BSON error types (breaking)decimal dependency to 2.1.0linked-hash-map with indexmap (breaking)imports_granularity=Crate in rustfmt configcompat::u2f with serde helpers (breaking)ObjectId conversion constructors (breaking)impl AsRef<str> instead of &str in Document methods (breaking)Nothing published for this version
Because of this, it is not recommended for use and has been deprecated, and the flag will be removed altogether in 2.0.0. See #282 for more details.
The MongoDB Rust driver team is pleased to announce the 1.2.3 release of the bson crate. This release includes a number of important bug fixes.
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.
decimal128 feature flag (RUST-960, #286)It was determined that the BSON serialization format that is used when the experimental decimal128 feature flag is enabled does not match the format expected by the database or other MongoDB tools and drivers. Because of this, it is not recommended for use and has been deprecated, and the flag will be removed altogether in 2.0.0. See #282 for more details.
If you are relying on this feature flag or are just interested in a complete decimal128 implementation, please let us know on #53.
Document that contains decimal128 (#285)From unsigned integer impls for Bson (#281)ObjectIds (#286)decimal128 feature flag (#288)The MongoDB Rust Driver team is pleased to announce the v1.2.2 release of the BSON library.
The MongoDB Rust Driver team is pleased to announce the v1.2.2 release of the BSON library.
This release updates the base64 dependency to 0.13.0 (RUST-686). Thanks to @bugadani for contributing this fix!
The MongoDB Rust Driver team is pleased to announce the v1.2.1 release of the BSON library.
The MongoDB Rust Driver team is pleased to announce the v1.2.1 release of the BSON library.
This release contains a fix for a crash that could occur in Document::from_reader when passed certain types of malformed input. Thank you to @5225225 for reporting the issue and @gperinazzo for fixing it! (RUST-713)
The MongoDB Rust Driver team is pleased to announce the v1.2.0 release of the BSON library.
The MongoDB Rust Driver team is pleased to announce the v1.2.0 release of the BSON library.
This release contains several improvements to the library's integration with Serde.
serde_helpers.rs which contains severals functions and modules to assist in customizing serialization and deserialization of user data types. These functions and modules are compatible with the Serde serialize_with and Serde with field attributes, respectively.ObjectId type from a hexadecimal string.The MongoDB Rust Driver team is pleased to announce the v1.1.0 release of the BSON library.
The MongoDB Rust Driver team is pleased to announce the v1.1.0 release of the BSON library.
In addition to the changes listed for the v1.1.0-beta, the following change was made since v1.0.0:
The MongoDB Rust Driver team is pleased to announce the v1.1.0-beta release of the BSON library.
The MongoDB Rust Driver team is pleased to announce the v1.1.0-beta release of the BSON library.
linked-hash-map due to fix unsoundness…library, v1.0.0. Per semver requirements, no breaking changes will be made in future 1.x releases of this library.
The MongoDB Rust Driver team is pleased to announce the first stable release of the BSON library, v1.0.0. Per semver requirements, no breaking changes will be made in future 1.x releases of this library.
See the release notes for v0.15.0 for details on the recent breaking changes in the BSON library.
In preparation of stabilizing the API of the BSON library, we made a number of breaking changes. The individual changes are listed below in the releas…
The MongoDB Rust Driver team is pleased to announce the first beta of the BSON library, v0.15.0.
In preparation of stabilizing the API of the BSON library, we made a number of breaking changes. The individual changes are listed below in the release notes, each with a short description of why we made the change.
encode_document and decode_document were defined as free-floating functions
for parity with serde_json. However, unlike serde_json::from_reader and
serde_json::to_writer, our functions are not generic, so it makes more sense to derfine them
as methods on the Document type.serde_json, we updated instances of the
terms decode and encode to either use serialize and deserialize or to use terminology
like reader or writer as appropriate.Document type was originally changed to preserve the order of elements,
Document was defined as an alias of the OrderedDocument type. Since the indirection can
cause things like compiler error messages to be a little confusing, we've removed the alias and
changed OrderedDocument to just be called Document.non_exhaustive.decode_document_utf8_lossy was originally provided for parity with the standard library's
String::from_utf8_lossy, but the BSON specification requires that all strings are encoded in
UTF-8, so this method isn't particularly usefulRemove ObjectId::with_timestamp about the brittleness of relying
on the underlying format of an ObjectId.i32 and bool that are Copy don't have a strong need for functionality that
returns mutable references to them. Users who wish to modify the underlying value of a &mut Bson can still do so without introspecting the value by simply replacing what the reference
points to.Document::insert is already generic over values that implement Into<String> and
Into<Bson>, which includes String and Bson themselves, so it can be used in any
circumstance where Document::insert_bson was used.Bson type have been deprecated for over three years,
so we've removed them in preparation of stabilizing the API.doc! macro was written before Rust allowed macros to use
the : character. Instead, the syntax => was used for key-value pairs. Rust lifted this
restriction a few years ago, and the doc! macro was updated to allow the : to be used. In
preparation of stabilizing the API, we've removed the old syntax, which isn't necessary anymore
and likely has not been used for new code for a while.Error::description in BSON libraryThe MongoDB Rust driver team is pleased to announce a new bugfix release of the BSON library, v0.14.1.
The MongoDB Rust driver team is pleased to announce a new bugfix release of the BSON library, v0.14.1.
Thanks to @jcdyer for the pull requests!
Uses dyn keyword for Trait objects.
Language features updates:
dyn keyword for Trait objects.New features:
decimal crate, could be enabled by feature decimal128
Extend<(String, Bson)> for OrderedDocumentprocess_id and machine_id (for WASM supports)as_*_mut())std::convert::TryFrom instead of try_from crateBug fixed:
Nothing published for this version
[BUG-FIXED] #103 Proper implementation of Newtype serialization in serde. Maybe a breaking change.
[BREAKING] (MAYBE) Implements From for DateTime instead of Into for UtcDateTime.
to_owned()/clone()/to_string() allocations.From<UtcDateTime> for DateTime<Utc> instead of Into<DateTime<Utc> for UtcDateTime.* #99 - Implement TimeStamp serde serialisation * #98 - Fixed incorrect endianness for TimeStamp * #95 - Add i2u feature to allow auto converting betw
TimeStamp serde serialisationTimeStampi2u feature to allow auto converting between signed and unsigned integers.* #64 Won't panic if timestamp is nagative (which is impossible in real life).
* #89 Implemented special serialization/deserialization rules for bytes array in serde. * #64 Won't crash if the length of UTF-8 string is invalid. *
* #88 Add TimeStamp facilities for de/serialize Timestamp value.
TimeStamp facilities for de/serialize Timestamp value.Adds decode_document_utf8_lossy.
decode_document_utf8_lossy.Improve macro syntax support #83
* #82 Implemented Default for Bson, Document
Default for Bson, DocumentNothing published for this version
Won't serialize unsigned types to Bson::FloatingPoint
Bson::FloatingPointNothing published for this version
Nothing published for this version
Fixed bug, add missing convertion for f64 in Value
f64 in ValueImplement From/Into traits for Value
From/Into traits for ValueNothing published for this version
Nothing published for this version
Fixed bug while converting floating point Value to Bson
Value to Bson* Removed rustc-serialize * Add missing docs
rustc-serializeUses data-encoding for serializing
rustc-serializeserde-json insteaddata-encoding for serializingOne column per quarter.