Skip to content

Commit 5c616c0

Browse files
lindseymoorelindseymoore
authored
DOCSP-45178 Choose a Connection Target (#125)
* DOCSP-45178 Choose a Connection Target * edits and add page to TOC * more small edits * last edits * no hyper linked period * coe improvements * stable api single quote
1 parent c66b49b commit 5c616c0

File tree

3 files changed

+183
-2
lines changed

3 files changed

+183
-2
lines changed

‎source/connect.txt

+3-2
Original file line numberDiff line numberDiff line change
@@ -22,5 +22,6 @@ Connect to MongoDB
2222
:titlesonly:
2323
:maxdepth: 1
2424

25-
/connect/mongoclient
26-
/connect/stable-api
25+
Create a Client </connect/mongoclient>
26+
Stable API </connect/stable-api>
27+
Choose a Connection Target </connect/connection-targets>

‎source/connect/connection-targets.txt

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _ruby-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use a connection string and a ``Mongo::Client`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
Atlas
27+
-----
28+
29+
To connect to a MongoDB deployment on Atlas, include the following elements
30+
in your connection string:
31+
32+
- The URL of your Atlas cluster
33+
- Your MongoDB username
34+
- Your MongoDB password
35+
36+
Then, pass your connection string to the ``Mongo::Client`` constructor.
37+
38+
.. tip::
39+
40+
Follow the :atlas:`Atlas driver connection guide </driver-connection>`
41+
to retrieve your connection string.
42+
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
44+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
45+
To learn more about the {+stable-api+} feature, see the :ref:`<ruby-stable-api>`
46+
guide.
47+
48+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
49+
code also uses the ``server_api`` field to specify a {+stable-api+} version.
50+
51+
.. literalinclude:: /includes/connect/connection-targets.rb
52+
:language: ruby
53+
:start-after: start-connection-target-atlas
54+
:end-before: end-connection-target-atlas
55+
:dedent:
56+
57+
Local Deployments
58+
-----------------
59+
60+
To connect to a local standalone MongoDB deployment, specify the host of the
61+
server. Optionally, specify the port of the server and the database to connect
62+
to. If no port is specified, the default port is ``27017``. If no database name
63+
is specified, the client will use the ``admin`` database:
64+
65+
.. literalinclude:: /includes/connect/connection-targets.rb
66+
:language: ruby
67+
:start-after: start-local-connection
68+
:end-before: end-local-connection
69+
:dedent:
70+
71+
You can also specify the host, port, and database to connect to using a
72+
connection string:
73+
74+
.. literalinclude:: /includes/connect/connection-targets.rb
75+
:language: ruby
76+
:start-after: start-local-connection-uri
77+
:end-before: end-local-connection-uri
78+
:dedent:
79+
80+
You can also specify your host as ``localhost``. The following code example
81+
connects to ``localhost`` on the default port, ``27017``:
82+
83+
.. literalinclude:: /includes/connect/connection-targets.rb
84+
:language: ruby
85+
:start-after: start-localhost
86+
:end-before: end-localhost
87+
:dedent:
88+
89+
Replica Sets
90+
------------
91+
92+
To connect to a replica set, it is recommended to specify all nodes that are
93+
part of the replica set. In the event that one or more nodes becomes unavailable,
94+
specifying all nodes allows the driver to still connect to the replica set,
95+
as long as one node is available.
96+
97+
However, it is sufficient to pass the address of any one node in the replica set
98+
to the driver. The node does not have to be the primary, and it may be a hidden node.
99+
The driver will then automatically discover the remaining nodes.
100+
101+
The following example shows how to specify three members of the replica set:
102+
103+
.. literalinclude:: /includes/connect/connection-targets.rb
104+
:language: ruby
105+
:start-after: start-replica-set
106+
:end-before: end-replica-set
107+
:dedent:
108+
109+
The following example shows how to connect to the replica set using a connection
110+
string:
111+
112+
.. literalinclude:: /includes/connect/connection-targets.rb
113+
:language: ruby
114+
:start-after: start-replica-set-uri
115+
:end-before: end-replica-set-uri
116+
:dedent:
117+
118+
The following example shows how to verify the replica set name upon connection
119+
by using the ``replica_set`` option or the ``replicaSet`` connection string option:
120+
121+
.. literalinclude:: /includes/connect/connection-targets.rb
122+
:language: ruby
123+
:start-after: start-replica-set-option
124+
:end-before: end-replica-set-option
125+
:dedent:
126+
127+
API Documentation
128+
-----------------
129+
130+
To learn more about creating a ``Mongo::Client`` object with the {+driver-short+},
131+
see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .

‎source/includes/connect/connection-targets.rb

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# start-connection-target-atlas
2+
require 'mongo'
3+
4+
# Replace the placeholders with your credentials
5+
uri = "<connection string>"
6+
7+
# Sets the server_api field of the options object to Stable API version 1
8+
options = { server_api: { version: '1' } }
9+
# Creates a new client and connect to the server
10+
client = Mongo::Client.new(uri, options)
11+
# Sends a ping to confirm a successful connection
12+
begin
13+
admin_client = client.use('admin')
14+
result = admin_client.database.command(ping: 1).documents.first
15+
puts "Pinged your deployment. You successfully connected to MongoDB!"
16+
rescue Mongo::Error::OperationFailure => ex
17+
puts ex
18+
ensure
19+
client.close
20+
end
21+
# end-connection-target-atlas
22+
23+
# start-local-connection
24+
Mongo::Client.new([ 'host1:27017' ], database: 'mydb')
25+
# end-local-connection
26+
27+
# start-local-connection-uri
28+
Mongo::Client.new("mongodb://host1:27017/mydb")
29+
# end-local-connection-uri
30+
31+
# start-localhost
32+
client = Mongo::Client.new(["localhost"])
33+
# end-localhost
34+
35+
# start-replica-set
36+
Mongo::Client.new([ 'host1:27017', 'host2:27018', `host3:21019` ], database: 'mydb')
37+
# end-replica-set
38+
39+
# start-replica-set-uri
40+
Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb")
41+
# end-replica-set-uri
42+
43+
# start-replica-set-option
44+
Mongo::Client.new([ 'host1:27017', 'host2:27018', 'host3:27019' ],
45+
database: 'mydb', replica_set: 'myapp')
46+
47+
# Or by using a connection string:
48+
Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb?replicaSet=myapp")
49+
# end-replica-set-option

0 commit comments

Comments
 (0)