Release Notes

This page documents significant changes in driver releases.

It is not an exhaustive list of changes and generally does not enumerate bug fixes; please consult the releases page on GitHub for a more comprehensive list of changes in each version of the driver and the releases page in Jira for the complete list of changes, including those internal to the driver and its test suite.

2.20 [release-notes-2.20]

This release includes the following new features:

• Support for Ruby 2.5 and 2.6 has been discontinued. Support for Ruby 2.7 and JRuby 9.2 has been deprecated, and will be discontinued in the next minor driver version. Support for JRuby 9.4 has been added.
• Support for the newly-released Ruby-BSON version 5.0.
• Connection strings no longer require a slash between the hosts and the options. E.g., "mongodb://example.com?w=1" and "mongodb://example.com/?w=1" are both valid connection strings now.
• Container runtime and orchestration metadata for the client environment are now sent to the server for analytics purposes.
• A warning message is now written to the log when the host is detected to be a CosmosDB (Azure) or DocumentDB (Amazon) instance.
• When attempting a retry of a read or write operation in a sharded topology, the retry will be attempted on a different mongos instance, if possible.

2.19 [release-notes-2.19]

This release of the Ruby driver supports MongoDB version 7.0. The Ruby driver now supports Ruby 3.2. Ruby 2.5 and 2.6 are now deprecated.

This release includes the following new features:

• The driver now limits the number of connections established by a connection pool simultaneously. By default the limit is 2. The limit can be configured with the :max_connecting option of the ::Mongo::Client constructor. The default should be sufficient for most applications. However, if your application is using a large number of threads, you may need to increase the limit.
• Added support for automatic AWS credentials retrieval and authentication with temporary credentials when AWS KMS is used for client side encryption.
• Added support for automatic GCP credentials retrieval when Google Cloud Key Management is used for client side encryption.
• Added support the Azure VM-assigned Managed Identity for Automatic KMS Credentials when Azure Key Vault is used for client side encryption.
• Queryable Encryption support is extended.
• Added support for Queryable Encryption Range Indexes.
• A crypt_shared library can be now used instead of mongocryptd.
• Added support for AWS IAM Roles for service accounts, EKS in particular.
• AWS Credentials are now cached when possible.
• Added support for creating and managing Atlas search indexes via the Ruby driver.

2.18 [release-notes-2.18]

This release of the Ruby driver supports MongoDB version 5.2 and 6.0.

This release includes the following new features:

• Added support for queryable encryption.
• Added support for Azure Key Vault, Google Cloud Key Management, and any KMIP compliant Key Management System to be used as master key storage for client side encryption.
• It is now possible to provide the path to a schema map file <schema-map-path> instead of the entire schema map as an object.
• The driver now implements the feature flag <feature-flags> mechanism for incompatible changes and bug fixes. Changes gated behind feature flags for 2.18 are passing view filter and options to aggregate and validation of correct usage of update vs replace methods, as described below.
• Added the validate_update_replace feature flag which validates the parameters to update and replace operations. If this flag is turned on, an error will be raised on an invalid update or replacement document.
• Added the broken_view_options feature flag which allows the view options to be correctly propagated to the aggregate, count, count_documents, distinct, and estimated_document_count mehods. When this flag is switched on, the view options will be ignored in those methods.
• The driver now permits inserting documents with dollar-prefixed and dotted keys <dots-dollars-in-field-names>.
• CRUD methods, methods for listing databases, collection, and indexes management methods now support a new option :comment. This option enables users to specify an arbitrary comment to help trace the operation through the database profiler, currentOp and logs.
• The estimated_document_count method is now using the count server command instead of $collStats aggregation pipeline stage, to support operation on views. Applications using the Stable API should upgrade to server versions 5.0.8 (if using MongoDB 5.0) or 5.3.2 (if using MongoDB 5.1/5.2/5.3) or newer to use the count command when API strict is enabled, or avoid setting api_strict: true when constructing ::Mongo::Client instances with server versions 5.0.0-5.0.7 and 5.1.0-5.3.1.
• The DBRef class has been moved to bson-ruby. For backwards compatibility, BSON::DBRef is aliased as Mongo::DBRef. The BSON::DBRef class derives from BSON::Document, unlike the legacy Mongo::DBRef which derived from Object. BSON::DBRef retains all attributes passed into its constructor, unlike Mongo::DBRef which only allowed $ref, $id, and $db. BSON::DBRef also reorders the fields if necessary to place $ref, $id, and $db first, in that order, as required by the MongoDB server.
• BulkWrite::Result class now has the acknowledged? attribute.
• Providing an empty array of operations to the bulk write is now an error.
• BSON serialization performance has been improved.
• ActiveJob middleware <query-cache-active-job-middleware> was added to the query cache.
• :authorized_collections options is recognized when listing collections.
• :wildcard_projection option was added to the allowed index specification.
• Added :srv_max_hosts/srvMaxHosts Ruby and URI options to limit how many mongos routers the driver will establish connections to.
• Custom SRV service names are now supported with the :srv_service_name Ruby option and the srvServiceName URI option.
• When 0 is given as the max connection pool size, it is now interpreted to mean no limit.
• The default maximum connection pool size has been increased to 20 from 5.

This release adds supports for JRuby 9.3.

2.17 [release-notes-2.17]

This release of the Ruby driver supports MongoDB version 5.1. It also increases the minimum required Ruby version to 2.5, and drops support for MongoDB versions older than 3.6.

This release includes the following new features:

• Added new readConcern level "snapshot" (non-speculative) for read commands outside of transactions, including on secondaries.
• Support \$merge and \$out executing on secondaries.
• Support 'let' option for aggregate and CRUD commands.

The following bugs were fixed:

• Push monitor thread can exit when address resolution fails.

The following non-breaking changes were made:

• mapReduce command is now deprecated.
• Avoid tight looping in push monitor

2.16 [release-notes-2.16]

This release adds the following new feature:

• Load balancer support.

The following minor improvement has been made:

• GridFS file retrieval no longer requires index creation privileges when the indexes already exist, and is thus usable with users that have only read permissions.

This release of the Ruby driver increases the minimum required Ruby version to 2.4 and deprecates support for MongoDB server versions below 3.6.

2.15 [release-notes-2.15]

This release adds the following new features:

• Ruby 3.0 support.
• Ability to specify the server API parameters <server-api-parameters>.
• Support for Zstandard and Snappy wire protocol compression <compression>.
• Query cache middleware <query-cache-middleware> was moved to the driver from Mongoid and is now usable in applications that do not use Mongoid.
• It is now possible to create collections with time-series options.
• Experimental support for MongoDB Atlas Serverless when not using a load balancer.

The following smaller improvements have been made:

• The OperationFailure exception message now contains the server error code name, if provided by the server. The layout of the message was changed to accommodate the error code name.
• The generic SSL messaging has been removed from SocketError messages when TLS is used. TLS connections to MongoDB are now the norm, with Atlas requiring TLS, and it is more likely that a connection fails due to failed certificate verification than due to the server not having TLS enabled.
• A hook was added to permit applications to modify the TLS context <modifying-tls-context> used for TLS connections, for example to exclude ciphers.
• Heartbeat succeeded and heartbeat failed server monitoring events <server-heartbeats> are now linked to the respective heartbeat started event, to improve usability.
• skip and limit options are now prohibited when calling estimated_document_count, because the server command does not accept them.
• The driver will now omit command monitoring reply payloads when they are in response to sensitive commands.
• When the driver closes network sockets it now enforces the socket timeout.
• estimated_document_count collection method now uses the $collStats aggregation pipeline stage instead of the count command on 5.0 and newer servers.
• The platform metadata sent by the driver to the server in the handshake now includes the purpose of the connection being established, permitting administrators to distinguish monitoring connections from application connections.
• The driver now uses monotonic clock for timeouts.
• The driver will no longer mark servers unknown based on errors in writeErrors field in the server response.
• Server selection timeout for mongocryptd has been increased to 10 seconds.

2.14 [release-notes-2.14]

This release adds the following new features:

• Queries against Atlas Data Lake are now supported.
• The query cache <query-cache> has been moved from Mongoid into the driver. Mongoid will use the driver's query cache as of driver 2.14. As part of the move, several issues with the query cache have been fixed and its functionality was extended to cover aggregation pipeline queries and to support result sets of any size.
• Explain verbosity can now be specified <query-options> when explaining.
• Mixed case read preference tag names are now supported.
• The driver will perform OCSP endpoint verification <ocsp-verification> by default when TLS is enabled. Due to lack of support in Ruby's openssl extension, OCSP stapling is not yet implemented.

The following smaller improvements have been made:

• Default logger level for Client objects is now info (up from debug). This reduces the amount of log output produced by the driver by default.
• Database and collection write methods support specifying write concern for the individual operations.
• Client#summary method now shows the monitoring state of each server.
• When objects other than hashes are attempted to be inserted (which is not allowed), the driver now provides better diagnostics.
• DNS queries for SRV URIs are now subject to configured socket timeouts.
• When the Client object is reconnected, session pools are now cleared.

Support for Ruby versions 2.3 and 2.4 has been deprecated as of this release.

2.13 [release-notes-2.13]

This release implements the necessary client-side functionality to use the features added in MongoDB 4.4. Specifically, the following new driver functionality has been added:

• Support for the directConnection URI option to provide a consistent cross-driver mechanims to discover deployment topology or force direct connection.
• Support for MONGODB-AWS authentication mechanism <aws-auth>.
• When SCRAM authentication is used with 4.4 and newer servers, the driver will complete authentication with fewer network roundtrips.
• The driver creates an additional monitoring connection for 4.4 and newer servers, permitting the server to notify the driver when its state changes. This reduces the time for the driver to discover the new primary during failover events.
• Client constructor can be given a block, in which case the client object will be yielded to the block and automatically closed when the block ends.
• start_session can be given a block, in which case the session object will be yielded to the block and automatically ended when the block ends.
• Write options can now be specified for individual CRUD operations.
• The :allow_disk_use option was added to find operations.
• The :authorized_databases option was added to list_databases method.
• The list_collections method now passes through all options.
• Ability to set an index as hidden <index-options> when creating it.
• Ability to specify commit quorum when creating indexes.
• :wrapping_libraries client option <client-options>, to be used by libraries like Mongoid which wrap the driver to report their version to the server for troubleshooting/statistics aggregation purposes.

The following smaller improvements have been made:

• count_documents can now be invoked with no arguments.
• The default TCP keep-alive time has been reduced to make the driver correctly detect dropped connections on Microsoft Azure.
• CursorNotFound is now a resumable change stream error.
• The number of backtrace lines in exceptions handled by background threads can now be configured.

2.12 [release-notes-2.12]

This release adds the following new features:

• Client-side encryption <client-side-encryption>.
• list_collections method now accepts the :filter option.

The following smaller improvements have been made:

• Authentication exceptions now include server information to aid in troubleshooting.

2.11 [release-notes-2.11]

This release adds the following new features:

• If a minimum connection pool size is specified, the pool for each server will create a background thread to eagerly establish connections up to the specified minimum pool size.
• If the driver connects to the deployment using a SRV URI and the deployment is a sharded cluster, the driver will poll the SRV DNS records to automatically discover new and removed mongos servers and adjust the set of known servers accordingly.

The following smaller improvements have been made:

• The driver now permits unencoded subdelimiters in usernames and passwords in MongoDB URIs.
• User management helpers now accept the write concern option.
• The command monitoring <command-monitoring> logger provided with the driver will now log connection ids used for each command.
• When legacy read retries are used, retry on the same set of server errors that the modern retries would have retried on.
• The distinct(nil) call is prohibited because it is rejected by MongoDB 4.4 and newer servers.

This release of the Ruby driver increases the minimum required Ruby version to 2.3, as well as minimum supported JRuby version to 9.2.

2.10 [release-notes-2.10]

This release implements the necessary client-side functionality to use the features added in MongoDB 4.2. Specifically, the following new driver functionality has been added:

• Support for sharded transactions.
• Applications can set the :max_time_ms option in commit_transaction method.
• Support for database-level aggregation.
• Support for $merge aggregation pipeline stage.
• The update operations now accept an aggregation pipeline as an array.
• TLS regenotiation is now disabled when possible.
• Change streams now handle post-batch resume tokens provided by the server.

The following smaller improvements have been made:

• All methods now accept :write_concern option for the write concern, including those that previously accepted the :write option.
• The query string in a MongoDB URI can now start with &.

Support for Ruby versions less than 2.3 is deprecated in this release.

2.9 [release-notes-2.9]

This release adds the following new features:

• A rewrite of the connection pool code with improved monitoring, compliant with the CMAP specification
• A modern retryable reads implementation compliant with the cross-driver retryable reads specification, enabled by default.
• Modern retryable writes are now enabled by default.
• Legacy retryable writes can be disabled in most cases.
• The driver now supports certificate chains being provided as client certificates for TLS connections.
• Ability to specify multiple CA certificates when creating a Client.
• Ability to pass the private key and certificate via URI options.

The following smaller improvements have been made:

• Support for the startAfter option in the $changeStream aggregation pipeline stage.
• Field order of BSON documents sent to the server changed for better logging.
• Certificate paths with unescaped slashes can now be specified in MongoDB URIs.

This release deprecates support for Ruby versions less than 2.3.