.. _release-notes: ************* Release Notes ************* .. default-domain:: mongodb 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. .. _release-notes-2.18: 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 :ref:`path to a schema map file ` instead of the entire schema map as an object. - The driver now implements the :ref:`feature flag ` 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 :ref:`inserting documents with dollar-prefixed and dotted keys `. - 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. - :ref:`ActiveJob 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. .. _release-notes-2.17: 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 .. _release-notes-2.16: 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. .. _release-notes-2.15: 2.15 ==== This release adds the following new features: - Ruby 3.0 support. - Ability to specify the :ref:`server API parameters `. - Support for Zstandard and Snappy :ref:`wire protocol compression `. - :ref:`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 :ref:`modify the TLS context ` used for TLS connections, for example to exclude ciphers. - Heartbeat succeeded and heartbeat failed :ref:`server monitoring events ` 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. .. _release-notes-2.14: 2.14 ==== This release adds the following new features: - Queries against Atlas Data Lake are now supported. - The :ref:`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 :ref:`be specified ` when explaining. - Mixed case read preference tag names are now supported. - The driver will perform :ref:`OCSP endpoint 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. .. _release-notes-2.13: 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 :ref:`MONGODB-AWS authentication mechanism `. - 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 :ref:`as hidden ` when creating it. - Ability to specify commit quorum when creating indexes. - ``:wrapping_libraries`` :ref:`client option `, 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. .. _release-notes-2.12: 2.12 ==== This release adds the following new features: - :ref:`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. .. _release-notes-2.11: 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 :ref:`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. .. _release-notes-2.10: 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. .. _release-notes-2.9: 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.