mongodb/mongo-ruby-driver

.. _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
<https://github.com/mongodb/mongo-ruby-driver/releases>`_ for a more
comprehensive list of changes in each version of the driver and the
`releases page in Jira
<https://jira.mongodb.org/projects/RUBY?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=released>`_
for the complete list of changes, including those internal to the driver and
its test suite.


.. _release-notes-2.20:

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.


.. _release-notes-2.19:

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 <https://www.mongodb.com/docs/upcoming/core/queryable-encryption/queryable-encryption/>`_ support is extended.
- Added support for Queryable Encryption Range Indexes.
- A `crypt_shared <https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/shared-library/#download-the-automatic-encryption-shared-library>`_
  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 <https://www.mongodb.com/docs/atlas/atlas-search/>`_ via the
  Ruby driver.

.. _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 <https://www.mongodb.com/docs/upcoming/core/queryable-encryption/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 <schema-map-path>`
  instead of the entire schema map as an object.
- The driver now implements the :ref:`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 :ref:`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.
- :ref:`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.


.. _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 <server-api-parameters>`.
- Support for Zstandard and Snappy :ref:`wire protocol compression <compression>`.
- :ref:`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
  <https://www.mongodb.com/cloud/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
  <modifying-tls-context>` used for TLS connections, for example to exclude
  ciphers.
- Heartbeat succeeded and heartbeat failed :ref:`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.


.. _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 <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 <query-options>` when explaining.
- Mixed case read preference tag names are now supported.
- The driver will perform :ref:`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.


.. _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 <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 :ref:`as hidden <index-options>` when creating it.
- Ability to specify commit quorum when creating indexes.
- ``:wrapping_libraries`` :ref:`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.


.. _release-notes-2.12:

2.12
====

This release adds the following new features:

- :ref:`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.


.. _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 <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.