Docs Menu

Docs HomeRuby MongoDB Driver

Driver Compatibility

On this page

  • MongoDB Compatibility
  • Ruby Compatibility
  • Rails/ActiveSupport Compatibility
  • TLS/SSL Compatibility
  • Atlas Compatibility
  • mongo_kerberos Compatibility
  • JRuby and Kerberos Authentication
  • JRuby and TLS Connections

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.

Ruby Driver
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.19
2.18
2.17
2.16
D
D
D
D
2.15
2.14
2.13
[1]
2.12
2.11
[3]
2.10
[2] [3]
2.9
2.8
2.7
2.6
2.5
[1] OCSP verification is implemented as of driver version 2.14.
[2] Polling of SRV records in sharded topologies is implemented as of driver version 2.11.
[3](1, 2) Client-side encryption is implemented as of driver version 2.12.

The driver does not support older versions of MongoDB.

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.

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.3
JRuby 9.2
JRuby 9.1
2.19
D
D
2.18
2.17
2.16
D
2.15
D
D
2.14
D
D
2.13
2.12
2.11
2.10
D
D
D
D
2.9
D
D
D
D
2.8
2.7
2.6

The driver does not support older versions of Ruby.

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:

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.

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:

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:

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.

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.

The following compatibility table specifies the version(s) of the mongo_kerberos library to use with a specific version of the driver.

Ruby Driver
mongo_kerberos   2.1
2.7 - 2.19

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.

Due to JRuby limitations:

  • ECDSA server certificates are not supported.

  • OCSP endpoint checking is not performed.

←  InstallationSupport →