diff --git a/source/compatibility.txt b/source/compatibility.txt new file mode 100644 index 00000000..f9ebd4f5 --- /dev/null +++ b/source/compatibility.txt @@ -0,0 +1,123 @@ +.. _ruby-compatibility: + +============= +Compatibility +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: backwards compatibility, versions, upgrade + +MongoDB Compatibility +--------------------- + +The following compatibility table specifies the recommended +version(s) of the {+driver-long+} for use with a specific version of +MongoDB. Except when indicated, the specified driver versions expose or +take advantage of the features added in the corresponding server versions. + +MongoDB server releases are generally backwards compatible. This means a +particular driver version will generally work with newer server versions but might +not utilize the new functionalities in those server versions. + +The first column lists the driver versions. + +.. sharedinclude:: dbx/lifecycle-schedule-callout.rst + +.. include:: /includes/compatibility-table-legend-ruby.rst + +.. include:: /includes/mongodb-compatibility-table-ruby.rst + +The driver does not support older versions of MongoDB. + +Language Compatibility +---------------------- + +The following compatibility table specifies the versions of Ruby supported +by the various versions of the {+driver-long+}. + +The first column lists the driver versions. + +.. include:: /includes/compatibility-table-legend-ruby.rst + +.. include:: /includes/language-compatibility-table-ruby.rst + +The driver does not support older versions of Ruby. + +Rails/ActiveSupport Compatibility +--------------------------------- + +The {+driver-short+} does not depend on ActiveSupport. However, if your +application uses ActiveSupport or Ruby on Rails, you must load the driver's +ActiveSupport compatibility code for behavior such as time serialization to be +correct: + +.. code-block:: ruby + + require 'mongo' + require 'mongo/active_support' + +Applications using Mongoid 7.0.6 or newer do not need to explicitly load +the driver's ActiveSupport code, since Mongoid automatically does so. + +.. _tls-compatibility: + +TLS/SSL Compatibility +---------------------- + +The {+driver-short+} uses the protocols supported by the underlying Ruby +``openssl`` extension. The ``openssl`` extension generally exposes +the functionality available in the operating system's OpenSSL library. + +Industry best practices, and some regulations, require the use of TLS 1.1 +or newer. Some operating systems or versions might not provide an OpenSSL version +that supports these TLS versions. + +If you use macOS older than 10.13 (High Sierra), you need to install Ruby from +`rvm`_, `homebrew`_, `macports`_, or another similar source. See +`Installing Ruby`_ for more options. + +If you use Linux or other non-macOS Unix systems, you can check your OpenSSL version +as follows: + +.. code-block:: sh + + openssl version + +If the version number is less than 1.0.1, support for TLS 1.1 or newer is +not available. Contact your operating system vendor for a solution or upgrade +to a newer distribution. + +You can check your TLS version by running the following command: + +.. code-block:: sh + + ruby -e "require 'net/http'; require 'json'; puts JSON.parse(Net::HTTP.get(URI('https://www.howsmyssl.com/a/check')))['tls_version']" + +After running the command, you must see ``TLS 1.X`` where ``X`` is greater than +or equal to ``1``. + +To learn more about TLS versions and their security implications, see `Transport Layer Security Cheat Sheet +`_. + +.. _rvm: https://rvm.io/ +.. _homebrew: https://brew.sh/ +.. _macports: https://www.macports.org/ +.. _Installing Ruby: https://www.ruby-lang.org/en/documentation/installation + +JRuby and TLS Connections +------------------------- + +Due to JRuby limitations: + +- The driver does not support ECDSA server certificates. +- The driver does not perform OCSP endpoint checking. diff --git a/source/includes/compatibility-table-legend-ruby.rst b/source/includes/compatibility-table-legend-ruby.rst new file mode 100644 index 00000000..e1148189 --- /dev/null +++ b/source/includes/compatibility-table-legend-ruby.rst @@ -0,0 +1,17 @@ +Compatibility Table Legend +++++++++++++++++++++++++++ + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility + + * - Icon + - Explanation + + * - āœ“ + - All features are supported. + * - D + - Support for the Driver version is deprecated. + * - No mark + - The Driver version is not tested with the MongoDB version. \ No newline at end of file diff --git a/source/includes/language-compatibility-table-ruby.rst b/source/includes/language-compatibility-table-ruby.rst new file mode 100644 index 00000000..10a303b2 --- /dev/null +++ b/source/includes/language-compatibility-table-ruby.rst @@ -0,0 +1,138 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large no-padding + + * - Ruby Driver + - Ruby 3.2 + - Ruby 3.1 + - Ruby 3.0 + - Ruby 2.7 + - Ruby 2.6 + - JRuby 9.4 + - JRuby 9.3 + - JRuby 9.2 + - JRuby 9.1 + + * - 2.20 to 2.21 + - |checkmark| + - |checkmark| + - |checkmark| + - D + - + - |checkmark| + - |checkmark| + - D + - + + * - 2.19 + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - D + - + - |checkmark| + - |checkmark| + - + + * - 2.18 + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - + - |checkmark| + - |checkmark| + - + + * - 2.17 + - + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - + - + - |checkmark| + - + + * - 2.16 + - + - + - |checkmark| + - |checkmark| + - |checkmark| + - + - + - |checkmark| + - + + * - 2.15 + - + - + - |checkmark| + - |checkmark| + - |checkmark| + - + - + - |checkmark| + - + + * - 2.14 + - + - + - + - |checkmark| + - |checkmark| + - + - + - |checkmark| + - + + * - 2.11 to 2.13 + - + - + - + - |checkmark| + - |checkmark| + - + - + - |checkmark| + - + + * - 2.10 + - + - + - + - |checkmark| + - |checkmark| + - + - + - |checkmark| + - |checkmark| + + * - 2.9 + - + - + - + - + - |checkmark| + - + - + - |checkmark| + - |checkmark| + + * - 2.6 to 2.8 + - + - + - + - + - |checkmark| + - + - + - |checkmark| + - |checkmark| + +.. include:: /includes/unicode-checkmark.rst \ No newline at end of file diff --git a/source/includes/mongodb-compatibility-table-ruby.rst b/source/includes/mongodb-compatibility-table-ruby.rst new file mode 100644 index 00000000..37a1ef30 --- /dev/null +++ b/source/includes/mongodb-compatibility-table-ruby.rst @@ -0,0 +1,120 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large no-padding + + * - Ruby Driver + - MongoDB 8.0 + - MongoDB 7.0 + - MongoDB 6.0 + - MongoDB 5.0 + - MongoDB 4.4 + - MongoDB 4.2 + - MongoDB 4.0 + + * - 2.21 + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - 2.19 to 2.20 + - + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - 2.18 + - + - + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - 2.17 + - + - + - + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - 2.16 + - + - + - + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - 2.14 to 2.15 + - + - + - + - + - |checkmark| + - |checkmark| + - |checkmark| + + * - 2.13 + - + - + - + - + - |checkmark| [#ocsp]_ + - |checkmark| + - |checkmark| + + * - 2.12 + - + - + - + - + - + - |checkmark| + - |checkmark| + + * - 2.11 + - + - + - + - + - + - |checkmark| [#client-side-encryption]_ + - |checkmark| + + * - 2.10 + - + - + - + - + - + - |checkmark| [#srv-polling]_ [#client-side-encryption]_ + - |checkmark| + + * - 2.6 to 2.9 + - + - + - + - + - + - + - |checkmark| + +.. [#ocsp] OCSP verification is implemented as of driver version 2.14. +.. [#srv-polling] Polling of SRV records in sharded topologies is + implemented as of driver version 2.11. +.. [#client-side-encryption] Client-side encryption is implemented as of + driver version 2.12. + +.. include:: /includes/unicode-checkmark.rst \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index c696db05..02a936f6 100644 --- a/source/index.txt +++ b/source/index.txt @@ -16,6 +16,7 @@ Connect View the Source API Documentation <{+api-root+}> + Compatibility .. TODO: Databases & Collections @@ -29,7 +30,6 @@ Issues & Help What's New Upgrade - Compatibility Introduction ------------ @@ -101,12 +101,12 @@ working with data in the :ref:`ruby-get-started` tutorial. .. Learn what changes you must make to your application to upgrade driver .. versions in the :ref:`ruby-upgrade` section. -.. Compatibility -.. ------------- +Compatibility +------------- -.. To learn about the versions of the {+mdb-server+} and the {+language+} language -.. that are compatible with each version of the {+driver-short+}, see the -.. :ref:`Compatibility ` section. +To learn about the versions of the {+mdb-server+} and the {+language+} language +that are compatible with each version of the {+driver-short+}, see the +:ref:`Compatibility ` section. Developer Hub ------------- diff --git a/source/old-content/reference/driver-compatibility.txt b/source/old-content/reference/driver-compatibility.txt deleted file mode 100644 index 0c43487b..00000000 --- a/source/old-content/reference/driver-compatibility.txt +++ /dev/null @@ -1,730 +0,0 @@ -.. _compatibility: - -******************** -Driver Compatibility -******************** - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - - -.. _mongodb-compatibility: - -MongoDB Compatibility -===================== - -The following compatibility table specifies the recommended -version(s) of the MongoDB Ruby driver for use with a specific version of -MongoDB. Except when indicated, the specified driver versions expose or -take advantage of the features added in the corresponding server versions. - -MongoDB server releases are generally backwards compatible, meaning a -particular version of the driver will generally work with newer versions of -the server but may not take advantage of the functionality released in the -newer version of the server. - -.. important:: - - MongoDB ensures compatibility between the MongoDB Server and the drivers - for three years after the server version's end of life (EOL) date. To learn - more about the MongoDB release and EOL dates, see - `MongoDB Software Lifecycle Schedules `__. - -The first column lists the driver versions.ā€œDā€ in other columns means support -for that MongoDB version is deprecated and will be removed in a future driver -version. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Ruby Driver - - MongoDB 8.0 - - MongoDB 7.0 - - MongoDB 6.0 - - MongoDB 5.0 - - MongoDB 4.4 - - MongoDB 4.2 - - MongoDB 4.0 - - MongoDB 3.6 - - MongoDB 3.4 - - MongoDB 3.2 - - MongoDB 3.0 - - MongoDB 2.6 - - * - 2.21 - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 2.20 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 2.19 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 2.18 - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 2.17 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 2.16 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - D - - D - - * - 2.15 - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.14 - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.13 - - - - - - - - - - |checkmark| [#ocsp]_ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.12 - - - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.11 - - - - - - - - - - - - |checkmark| [#client-side-encryption]_ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.10 - - - - - - - - - - - - |checkmark| [#srv-polling]_ [#client-side-encryption]_ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.9 - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.8 - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.7 - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.6 - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - * - 2.5 - - - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - -.. [#ocsp] OCSP verification is implemented as of driver version 2.14. - -.. [#srv-polling] Polling of SRV records in sharded topologies is - implemented as of driver version 2.11. - -.. [#client-side-encryption] Client-side encryption is implemented as of - driver version 2.12. - -The driver does not support older versions of MongoDB. - - -.. _ruby-compatibility: - -Ruby Compatibility -================== - -The following compatibility table specifies the versions of Ruby supported -by the various versions of the MongoDB Ruby driver. - -The first column lists the driver versions. "D" in a column means support -for that Ruby version is deprecated. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Ruby Driver - - Ruby 3.2 - - Ruby 3.1 - - Ruby 3.0 - - Ruby 2.7 - - Ruby 2.6 - - Ruby 2.5 - - Ruby 2.4 - - Ruby 2.3 - - Ruby 2.2 - - Ruby 2.1 - - Ruby 2.0 - - Ruby 1.9 - - JRuby 9.4 - - JRuby 9.3 - - JRuby 9.2 - - JRuby 9.1 - - * - 2.20 to 2.21 - - |checkmark| - - |checkmark| - - |checkmark| - - D - - - - - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - D - - - - * - 2.19 - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - - - * - 2.18 - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - - - - - |checkmark| - - |checkmark| - - - - * - 2.17 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - - - - - - - |checkmark| - - - - * - 2.16 - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - - - - - - - - - - - - - - - |checkmark| - - - - * - 2.15 - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - - - - - - - - - - - - - |checkmark| - - - - * - 2.14 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - - - - - - - - - - - - - |checkmark| - - - - * - 2.13 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - - - |checkmark| - - - - * - 2.12 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - - - |checkmark| - - - - * - 2.11 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - - - |checkmark| - - - - * - 2.10 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - D - - D - - - - - - |checkmark| - - |checkmark| - - * - 2.9 - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - D - - D - - - - - - |checkmark| - - |checkmark| - - * - 2.8 - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - |checkmark| - - |checkmark| - - * - 2.7 - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - |checkmark| - - |checkmark| - - * - 2.6 - - - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - |checkmark| - - |checkmark| - -The driver does not support older versions of Ruby. - - -Rails/ActiveSupport Compatibility -================================= - -The Ruby driver does not depend on ActiveSupport. However, when an -application uses ActiveSupport or Ruby on Rails, -it must load the driver's ActiveSupport -compatibility code for behavior like time serialization to be correct: - -.. code-block:: ruby - - require 'mongo' - require 'mongo/active_support' - -Applications using Mongoid 7.0.6 or newer do not need to explicitly load -the driver's ActiveSupport code, since Mongoid automatically does so. - - -.. _tls-compatibility: - -TLS/SSL Compatibility -===================== - -The driver will utilize the protocols supported by the underlying Ruby -``openssl`` extension. In turn, the ``openssl`` extension generally exposes -the functionality that exists in the operating system's OpenSSL library. - -Industry best practices, and some regulations, require the use of TLS 1.1 -or newer. Some operating systems or versions may not provide an OpenSSL version -new enough to support these TLS versions. - -Users of macOS older than 10.13 (High Sierra) will need to install Ruby from -`rvm`_, `homebrew`_, `macports`_, or another similar source. See -`installation information on ruby-lang.org`_ for more options. - -Users of Linux or other non-macOS Unix can check their OpenSSL version -as follows: - -.. code-block:: sh - - openssl version - -If the version number is less than 1.0.1 support for TLS 1.1 or newer is -not available. Contact your operating system vendor for a solution or upgrade -to a newer distribution. - -You can check your Ruby interpreter by executing the following command: - -.. code-block:: sh - - ruby -e "require 'net/http'; require 'json'; puts JSON.parse(Net::HTTP.get(URI('https://www.howsmyssl.com/a/check')))['tls_version']" - -You should see "TLS 1.X" where X is >= 1. - -You can read more about TLS versions and their security implications `here -`_. - -.. _rvm: https://rvm.io/ -.. _homebrew: https://brew.sh/ -.. _macports: https://www.macports.org/ -.. _installation information on ruby-lang.org: https://www.ruby-lang.org/en/documentation/installation - - -Atlas Compatibility -=================== - -`Driver version 2.6.1 `_ -or higher is recommended when using MongoDB Atlas, as this version has -significant performance improvements when TLS connections are used, and all -Atlas connections use TLS. - -When running on JRuby and connecting to Atlas Free Tier, -`driver version 2.6.4 `_ -or higher and Java 8 or higher are required. - - -``mongo_kerberos`` Compatibility -================================ - -The following compatibility table specifies the version(s) of the -:ref:`mongo_kerberos library ` to use with a specific version of -the driver. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Ruby Driver - - mongo_kerberos |nbsp| 2.1 - - * - 2.7 - 2.19 - - |checkmark| - - -JRuby and Kerberos Authentication -================================= - -If the ``mongo_kerberos`` gem is used for Kerberos authentication with JRuby, the the JVM system -property "sun.security.jgss.native" to will be set to "true" in order to facilitate the use of -the system cache of TGTs (e.g. TGTs obtained with ``kinit``). Any other use of the JGSS library -will also be affected by this setting, meaning any TGTs in the system cache will be available for -obtaining Kerberos credentials as well. - -.. include:: /includes/unicode-checkmark.rst -.. include:: /includes/unicode-nbsp.rst - - -JRuby and TLS Connections -========================= - -Due to JRuby limitations: - -- ECDSA server certificates are not supported. -- OCSP endpoint checking is not performed.