|
| 1 | +.. _release-notes: |
| 2 | + |
| 3 | +************* |
| 4 | +Release Notes |
| 5 | +************* |
| 6 | + |
| 7 | +.. default-domain:: mongodb |
| 8 | + |
| 9 | +This page documents significant changes in driver releases. |
| 10 | + |
| 11 | +It is not an exhaustive list of changes and generally does not enumerate |
| 12 | +bug fixes; please consult the `releases page on GitHub |
| 13 | +<https://github.com/mongodb/mongo-ruby-driver/releases>`_ for a more |
| 14 | +comprehensive list of changes in each version of the driver and the |
| 15 | +`releases page in Jira |
| 16 | +<https://jira.mongodb.org/projects/RUBY?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=released>`_ |
| 17 | +for the complete list of changes, including those internal to the driver and |
| 18 | +its test suite. |
| 19 | + |
| 20 | + |
| 21 | +2.15 |
| 22 | +==== |
| 23 | + |
| 24 | +This release adds the following new features: |
| 25 | + |
| 26 | +- Ability to specify the :ref:`server API parameters <server-api-parameters>`. |
| 27 | +- Support for Zstandard and Snappy :ref:`wire protocol compression <compression>`. |
| 28 | +- :ref:`Query cache middleware <query-cache-middleware>` was moved to the |
| 29 | + driver from Mongoid and is now usable in applications that do not use Mongoid. |
| 30 | + |
| 31 | +The following smaller improvements have been made: |
| 32 | + |
| 33 | +- The ``OperationFailure`` exception message now contains the server error code |
| 34 | + name, if provided by the server. The layout of the message was changed to |
| 35 | + accommodate the error code name. |
| 36 | +- The generic SSL messaging has been removed from ``SocketError`` messages |
| 37 | + when TLS is used. TLS connections to MongoDB are now the norm, with Atlas |
| 38 | + requiring TLS, and it is more likely that a connection fails due to failed |
| 39 | + certificate verification than due to the server not having TLS enabled. |
| 40 | +- A hook was added to permit applications to :ref:`modify the TLS context |
| 41 | + <modifying-tls-context>` used for TLS connections, for example to exclude |
| 42 | + ciphers. |
| 43 | +- Heartbeat succeeded and heartbeat failed :ref:`server monitoring events |
| 44 | + <server-heartbeats>` are now linked to the respective heartbeat started |
| 45 | + event, to improve usability. |
| 46 | +- When the driver closes network sockets it now enforces the socket timeout. |
| 47 | +- ``estimated_document_count`` collection method now uses the ``$collStats`` |
| 48 | + aggregation pipeline stage instead of the count command on 5.0 and newer |
| 49 | + servers. |
| 50 | +- The platform metadata sent by the driver to the server in the handshake |
| 51 | + now includes the purpose of the connection being established, permitting |
| 52 | + administrators to distinguish monitoring connections from application |
| 53 | + connections. |
| 54 | + |
| 55 | + |
| 56 | +2.14 |
| 57 | +==== |
| 58 | + |
| 59 | +This release adds the following new features: |
| 60 | + |
| 61 | +- Queries against Atlas Data Lake are now supported. |
| 62 | +- The :ref:`query cache <query-cache>` has been moved from Mongoid into the |
| 63 | + driver. Mongoid will use the driver's query cache as of driver 2.14. |
| 64 | + As part of the move, several issues with the query cache have been fixed |
| 65 | + and its functionality was extended to cover aggregation pipeline queries |
| 66 | + and to support result sets of any size. |
| 67 | +- Explain verbosity can now :ref:`be specified <query-options>` when explaining. |
| 68 | +- Mixed case read preference tag names are now supported. |
| 69 | +- The driver will perform :ref:`OCSP endpoint verification <ocsp-verification>` |
| 70 | + by default when TLS is enabled. Due to lack of support in Ruby's ``openssl`` |
| 71 | + extension, OCSP stapling is not yet implemented. |
| 72 | + |
| 73 | +The following smaller improvements have been made: |
| 74 | + |
| 75 | +- Default logger level for ``Client`` objects is now info (up from debug). |
| 76 | + This reduces the amount of log output produced by the driver by default. |
| 77 | +- Database and collection write methods support specifying write concern for |
| 78 | + the individual operations. |
| 79 | +- ``Client#summary`` method now shows the monitoring state of each server. |
| 80 | +- When objects other than hashes are attempted to be inserted (which is not |
| 81 | + allowed), the driver now provides better diagnostics. |
| 82 | +- DNS queries for SRV URIs are now subject to configured socket timeouts. |
| 83 | +- When the ``Client`` object is reconnected, session pools are now cleared. |
| 84 | + |
| 85 | +Support for Ruby versions 2.3 and 2.4 has been deprecated as of this release. |
| 86 | + |
| 87 | + |
| 88 | +2.13 |
| 89 | +==== |
| 90 | + |
| 91 | +This release implements the necessary client-side functionality to use the |
| 92 | +features added in MongoDB 4.4. Specifically, the following new driver |
| 93 | +functionality has been added: |
| 94 | + |
| 95 | +- Support for the ``directConnection`` URI option to provide a consistent |
| 96 | + cross-driver mechanims to discover deployment topology or force direct |
| 97 | + connection. |
| 98 | +- Support for :ref:`MONGODB-AWS authentication mechanism <aws-auth>`. |
| 99 | +- When SCRAM authentication is used with 4.4 and newer servers, the driver will |
| 100 | + complete authentication with fewer network roundtrips. |
| 101 | +- The driver creates an additional monitoring connection for 4.4 and newer |
| 102 | + servers, permitting the server to notify the driver when its state changes. |
| 103 | + This reduces the time for the driver to discover the new primary during |
| 104 | + failover events. |
| 105 | +- ``Client`` constructor can be given a block, in which case the client object |
| 106 | + will be yielded to the block and automatically closed when the block ends. |
| 107 | +- ``start_session`` can be given a block, in which case the session object will |
| 108 | + be yielded to the block and automatically ended when the block ends. |
| 109 | +- Write options can now be specified for individual CRUD operations. |
| 110 | +- The ``:allow_disk_use`` option was added to find operations. |
| 111 | +- The ``:authorized_databases`` option was added to ``list_databases`` |
| 112 | + method. |
| 113 | +- The ``list_collections`` method now passes through all options. |
| 114 | +- Ability to set an index :ref:`as hidden <index-options>` when creating it. |
| 115 | +- Ability to specify commit quorum when creating indexes. |
| 116 | +- ``:wrapping_libraries`` :ref:`client option <client-options>`, to be used |
| 117 | + by libraries like Mongoid which wrap the driver to report their version to |
| 118 | + the server for troubleshooting/statistics aggregation purposes. |
| 119 | + |
| 120 | +The following smaller improvements have been made: |
| 121 | + |
| 122 | +- ``count_documents`` can now be invoked with no arguments. |
| 123 | +- The default TCP keep-alive time has been reduced to make the driver |
| 124 | + correctly detect dropped connections on Microsoft Azure. |
| 125 | +- ``CursorNotFound`` is now a resumable change stream error. |
| 126 | +- The number of backtrace lines in exceptions handled by background threads |
| 127 | + can now be configured. |
| 128 | + |
| 129 | + |
| 130 | +2.12 |
| 131 | +==== |
| 132 | + |
| 133 | +This release adds the following new features: |
| 134 | + |
| 135 | +- :ref:`Client-side encryption <client-side-encryption>`. |
| 136 | +- ``list_collections`` method now accepts the ``:filter`` option. |
| 137 | + |
| 138 | +The following smaller improvements have been made: |
| 139 | + |
| 140 | +- Authentication exceptions now include server information to aid in |
| 141 | + troubleshooting. |
| 142 | + |
| 143 | + |
| 144 | +2.11 |
| 145 | +==== |
| 146 | + |
| 147 | +This release adds the following new features: |
| 148 | + |
| 149 | +- If a minimum connection pool size is specified, the pool for each server |
| 150 | + will create a background thread to eagerly establish connections up to |
| 151 | + the specified minimum pool size. |
| 152 | +- If the driver connects to the deployment using a SRV URI and the deployment |
| 153 | + is a sharded cluster, the driver will poll the SRV DNS records to |
| 154 | + automatically discover new and removed mongos servers and adjust the |
| 155 | + set of known servers accordingly. |
| 156 | + |
| 157 | +The following smaller improvements have been made: |
| 158 | + |
| 159 | +- The driver now permits unencoded subdelimiters in usernames and passwords in |
| 160 | + MongoDB URIs. |
| 161 | +- User management helpers now accept the write concern option. |
| 162 | +- The :ref:`command monitoring <command-monitoring>` logger provided with the |
| 163 | + driver will now log connection ids used for each command. |
| 164 | +- When legacy read retries are used, retry on the same set of server errors |
| 165 | + that the modern retries would have retried on. |
| 166 | +- The ``distinct(nil)`` call is prohibited because it is rejected by MongoDB |
| 167 | + 4.4 and newer servers. |
| 168 | + |
| 169 | +This release of the Ruby driver increases the minimum required Ruby version |
| 170 | +to 2.3, as well as minimum supported JRuby version to 9.2. |
| 171 | + |
| 172 | + |
| 173 | +2.10 |
| 174 | +==== |
| 175 | + |
| 176 | +This release implements the necessary client-side functionality to use the |
| 177 | +features added in MongoDB 4.2. Specifically, the following new driver |
| 178 | +functionality has been added: |
| 179 | + |
| 180 | +- Support for sharded transactions. |
| 181 | +- Applications can set the ``:max_time_ms`` option in ``commit_transaction`` |
| 182 | + method. |
| 183 | +- Support for database-level aggregation. |
| 184 | +- Support for ``$merge`` aggregation pipeline stage. |
| 185 | +- The update operations now accept an aggregation pipeline as an array. |
| 186 | +- TLS regenotiation is now disabled when possible. |
| 187 | +- Change streams now handle post-batch resume tokens provided by the server. |
| 188 | + |
| 189 | +The following smaller improvements have been made: |
| 190 | + |
| 191 | +- All methods now accept ``:write_concern`` option for the write concern, |
| 192 | + including those that previously accepted the ``:write`` option. |
| 193 | +- The query string in a MongoDB URI can now start with ``&``. |
| 194 | + |
| 195 | +Support for Ruby versions less than 2.3 is deprecated in this release. |
| 196 | + |
| 197 | + |
| 198 | +2.9 |
| 199 | +=== |
| 200 | + |
| 201 | +This release adds the following new features: |
| 202 | + |
| 203 | +- A rewrite of the connection pool code with improved monitoring, |
| 204 | + compliant with the CMAP specification |
| 205 | +- A modern retryable reads implementation compliant with the cross-driver |
| 206 | + retryable reads specification, enabled by default. |
| 207 | +- Modern retryable writes are now enabled by default. |
| 208 | +- Legacy retryable writes can be disabled in most cases. |
| 209 | +- The driver now supports certificate chains being provided as client |
| 210 | + certificates for TLS connections. |
| 211 | +- Ability to specify multiple CA certificates when creating a ``Client``. |
| 212 | +- Ability to pass the private key and certificate via URI options. |
| 213 | + |
| 214 | +The following smaller improvements have been made: |
| 215 | + |
| 216 | +- Support for the ``startAfter`` option in the ``$changeStream`` |
| 217 | + aggregation pipeline stage. |
| 218 | +- Field order of BSON documents sent to the server changed for better logging. |
| 219 | +- Certificate paths with unescaped slashes can now be specified in |
| 220 | + MongoDB URIs. |
| 221 | + |
| 222 | +This release deprecates support for Ruby versions less than 2.3. |
0 commit comments