Skip to content

Commit f2ecc5f

Browse files
mcmorisimcmorisi
authored
Merge branch 'standardization' into DOCSP-45187-update
2 parents 1cc4598 + bffd7d5 commit f2ecc5f

16 files changed

+838
-749
lines changed

‎source/compatibility.txt

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _ruby-compatibility:
2+
3+
=============
4+
Compatibility
5+
=============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: backwards compatibility, versions, upgrade
19+
20+
MongoDB Compatibility
21+
---------------------
22+
23+
The following compatibility table specifies the recommended
24+
version(s) of the {+driver-long+} for use with a specific version of
25+
MongoDB. Except when indicated, the specified driver versions expose or
26+
take advantage of the features added in the corresponding server versions.
27+
28+
MongoDB server releases are generally backwards compatible. This means a
29+
particular driver version will generally work with newer server versions but might
30+
not utilize the new functionalities in those server versions.
31+
32+
The first column lists the driver versions.
33+
34+
.. sharedinclude:: dbx/lifecycle-schedule-callout.rst
35+
36+
.. include:: /includes/compatibility-table-legend-ruby.rst
37+
38+
.. include:: /includes/mongodb-compatibility-table-ruby.rst
39+
40+
The driver does not support older versions of MongoDB.
41+
42+
Language Compatibility
43+
----------------------
44+
45+
The following compatibility table specifies the versions of Ruby supported
46+
by the various versions of the {+driver-long+}.
47+
48+
The first column lists the driver versions.
49+
50+
.. include:: /includes/compatibility-table-legend-ruby.rst
51+
52+
.. include:: /includes/language-compatibility-table-ruby.rst
53+
54+
The driver does not support older versions of Ruby.
55+
56+
Rails/ActiveSupport Compatibility
57+
---------------------------------
58+
59+
The {+driver-short+} does not depend on ActiveSupport. However, if your
60+
application uses ActiveSupport or Ruby on Rails, you must load the driver's
61+
ActiveSupport compatibility code for behavior such as time serialization to be
62+
correct:
63+
64+
.. code-block:: ruby
65+
66+
require 'mongo'
67+
require 'mongo/active_support'
68+
69+
Applications using Mongoid 7.0.6 or newer do not need to explicitly load
70+
the driver's ActiveSupport code, since Mongoid automatically does so.
71+
72+
.. _tls-compatibility:
73+
74+
TLS/SSL Compatibility
75+
----------------------
76+
77+
The {+driver-short+} uses the protocols supported by the underlying Ruby
78+
``openssl`` extension. The ``openssl`` extension generally exposes
79+
the functionality available in the operating system's OpenSSL library.
80+
81+
Industry best practices, and some regulations, require the use of TLS 1.1
82+
or newer. Some operating systems or versions might not provide an OpenSSL version
83+
that supports these TLS versions.
84+
85+
If you use macOS older than 10.13 (High Sierra), you need to install Ruby from
86+
`rvm`_, `homebrew`_, `macports`_, or another similar source. See
87+
`Installing Ruby`_ for more options.
88+
89+
If you use Linux or other non-macOS Unix systems, you can check your OpenSSL version
90+
as follows:
91+
92+
.. code-block:: sh
93+
94+
openssl version
95+
96+
If the version number is less than 1.0.1, support for TLS 1.1 or newer is
97+
not available. Contact your operating system vendor for a solution or upgrade
98+
to a newer distribution.
99+
100+
You can check your TLS version by running the following command:
101+
102+
.. code-block:: sh
103+
104+
ruby -e "require 'net/http'; require 'json'; puts JSON.parse(Net::HTTP.get(URI('https://www.howsmyssl.com/a/check')))['tls_version']"
105+
106+
After running the command, you must see ``TLS 1.X`` where ``X`` is greater than
107+
or equal to ``1``.
108+
109+
To learn more about TLS versions and their security implications, see `Transport Layer Security Cheat Sheet
110+
<https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Security_Cheat_Sheet.html>`_.
111+
112+
.. _rvm: https://rvm.io/
113+
.. _homebrew: https://brew.sh/
114+
.. _macports: https://www.macports.org/
115+
.. _Installing Ruby: https://www.ruby-lang.org/en/documentation/installation
116+
117+
JRuby and TLS Connections
118+
-------------------------
119+
120+
Due to JRuby limitations:
121+
122+
- The driver does not support ECDSA server certificates.
123+
- The driver does not perform OCSP endpoint checking.

‎source/get-started.txt

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,6 @@ Get Started with the Ruby Driver
2323
Download & Install </get-started/download-and-install/>
2424
Create a Deployment </get-started/create-a-deployment>
2525
Create a Connection String </get-started/create-a-connection-string>
26-
27-
.. TODO:
2826
Connect to MongoDB </get-started/connect-to-mongodb>
2927
Next Steps </get-started/next-steps>
3028

‎source/get-started/connect-to-mongodb.txt

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
.. _ruby-get-started-connect-to-mongodb:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: test connection, runnable, code example
13+
14+
.. procedure::
15+
:style: connected
16+
17+
.. step:: Edit your {+language+} application file
18+
19+
Navigate to your ``quickstart.rb`` file in the ``ruby-quickstart``
20+
directory. Copy and paste the following code below the Bundler
21+
code from the :ref:`ruby-quick-start-download-and-install` step
22+
of this tutorial. This code connects to MongoDB and queries the
23+
``movies`` collection in the ``sample_mflix`` database.
24+
25+
.. literalinclude:: /includes/get-started/quickstart.rb
26+
:language: ruby
27+
:dedent:
28+
:start-after: start-query
29+
:end-before: end-query
30+
31+
.. step:: Assign the connection string
32+
33+
Replace the ``<connection string>`` placeholder with the
34+
connection string that you copied from the :ref:`ruby-get-started-connection-string`
35+
step of this tutorial.
36+
37+
.. step:: Run your {+language+} application
38+
39+
From your ``ruby-quickstart`` directory, run the following shell
40+
command to run the application:
41+
42+
.. code-block:: none
43+
44+
ruby quickstart.rb
45+
46+
The command line output contains details about the retrieved movie
47+
document:
48+
49+
.. code-block:: none
50+
:copyable: false
51+
52+
{"_id"=>BSON::ObjectId('...'), "plot"=>"A young man is accidentally sent
53+
30 years into the past in a time-traveling DeLorean invented by his friend,
54+
Dr. Emmett Brown, and must make sure his high-school-age parents unite
55+
in order to save his own existence.", ...
56+
"title"=>"Back to the Future", ...
57+
58+
If you encounter an error or see no output, ensure that you specified the
59+
correct connection string in the ``quickstart.rb`` file and that you loaded the
60+
sample data.
61+
62+
After you complete these steps, you have a working application that
63+
uses the driver to connect to your MongoDB deployment, runs a query on
64+
the sample data, and prints out the result.
65+
66+
.. include:: /includes/get-started/troubleshoot.rst

‎source/get-started/create-a-connection-string.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,4 +55,4 @@ when applicable, and connection options.
5555
After completing these steps, you have a connection string that
5656
contains your database username and password.
5757

58-
.. include:: /includes/get-started/quickstart-troubleshoot.rst
58+
.. include:: /includes/get-started/troubleshoot.rst

‎source/get-started/create-a-deployment.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,4 @@ After you complete these steps, you have a new free tier MongoDB
2626
deployment on Atlas, database user credentials, and sample data loaded
2727
in your database.
2828

29-
.. include:: /includes/get-started/quickstart-troubleshoot.rst
29+
.. include:: /includes/get-started/troubleshoot.rst

‎source/get-started/download-and-install.txt

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,11 @@ Download and Install
4747

4848
Open the ``quickstart.rb`` file and add the following code:
4949

50-
.. code-block:: ruby
51-
52-
require 'bundler/inline'
53-
54-
gemfile do
55-
source 'https://rubygems.org'
56-
gem 'mongo'
57-
end
50+
.. literalinclude:: /includes/get-started/quickstart.rb
51+
:language: ruby
52+
:dedent:
53+
:start-after: start-bundler
54+
:end-before: end-bundler
5855

5956
This code adds the {+driver-short+} as a dependency by
6057
using the `Bundler <https://bundler.io/>`__ dependency management tool.

‎source/get-started/next-steps.txt

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _ruby-get-started-next-steps:
2+
3+
==========
4+
Next Steps
5+
==========
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: learn more
13+
14+
Congratulations on completing the quick start tutorial!
15+
16+
In this tutorial, you created a {+language+} application that
17+
connects to a MongoDB deployment hosted on MongoDB Atlas
18+
and retrieves a document that matches a query.
19+
20+
.. TODO:
21+
Learn more about {+driver-short+} from the following resources:
22+
- Learn how to perform read operations in the :ref:`<ruby-read>` section.
23+
- Learn how to perform write operations in the :ref:`<ruby-write>` section.

‎source/includes/compatibility-table-legend-ruby.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Compatibility Table Legend
2+
++++++++++++++++++++++++++
3+
4+
.. list-table::
5+
:header-rows: 1
6+
:stub-columns: 1
7+
:class: compatibility
8+
9+
* - Icon
10+
- Explanation
11+
12+
* - ✓
13+
- All features are supported.
14+
* - D
15+
- Support for the Driver version is deprecated.
16+
* - No mark
17+
- The Driver version is not tested with the MongoDB version.

‎source/includes/get-started/quickstart.rb

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# start-bundler
2+
require 'bundler/inline'
3+
4+
gemfile do
5+
source 'https://rubygems.org'
6+
gem 'mongo'
7+
end
8+
# end-bundler
9+
10+
# start-query
11+
uri = '<connection string>'
12+
13+
begin
14+
client = Mongo::Client.new(uri)
15+
16+
database = client.use('sample_mflix')
17+
movies = database[:movies]
18+
19+
# Queries for a movie that has the title 'Back to the Future'
20+
query = { title: 'Back to the Future' }
21+
movie = movies.find(query).first
22+
23+
# Prints the movie document
24+
puts movie
25+
26+
ensure
27+
client&.close
28+
end
29+
# end-query

0 commit comments

Comments
 (0)