Skip to content

Commit 3263b08

Browse files
rustagirrustagir
authored
DOCSP-38219: connect to mongodb (#10)
* DOCSP-38219: connect to mongodb * fix warnings * MW PR fixes 1
1 parent 6b64f58 commit 3263b08

File tree

4 files changed

+287
-2
lines changed

4 files changed

+287
-2
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
88
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
99

1010
toc_landing_pages = [
11-
"/bson"
11+
"/bson",
12+
"/tutorials/connect"
1213
]
1314

1415
[constants]

‎source/index.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
/installation/
1616
/get-started/
17+
/tutorials/
1718
/bson/
1819
View the Source <https://github.com/mongodb/mongo-java-driver>
1920
API Documentation <{+api+}/index.html>
@@ -31,7 +32,7 @@ runnable project by following one of the tutorials.
3132

3233
- :ref:`scala-get-started`
3334

34-
.. - :ref:`scala-tutorials`
35+
- :ref:`scala-tutorials`
3536

3637
.. - :ref:`scala-reference`
3738

‎source/tutorials.txt

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. _scala-tutorials:
2+
3+
=========
4+
Tutorials
5+
=========
6+
7+
.. toctree::
8+
9+
/tutorials/connect/
10+
11+
..
12+
/tutorials/db-coll/
13+
/tutorials/indexes/
14+
/tutorials/read-ops/
15+
/tutorials/encrypt/
16+
/tutorials/write-ops/
17+
/tutorials/aggregation/
18+
/tutorials/change-stream/
19+
/tutorials/text-search/
20+
/tutorials/geo/
21+
/tutorials/gridfs/
22+
/tutorials/command/
23+
24+
- :ref:`scala-connect`
25+
26+
..
27+
- :ref:`javars-db-coll`
28+
- :ref:`javars-indexes`
29+
- :ref:`javars-read-operations`
30+
- :ref:`javars-encrypt`
31+
- :ref:`javars-write-ops`
32+
- :ref:`javars-aggregation`
33+
- :ref:`javars-changestream`
34+
- :ref:`javars-text-search`
35+
- :ref:`javars-geo`
36+
- :ref:`javars-gridfs`
37+
- :ref:`javars-run-command`

‎source/tutorials/connect.txt

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
.. _scala-connect:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, modify connection
13+
14+
.. TODO .. toctree::
15+
..
16+
.. /tutorials/connect/tls/
17+
.. /tutorials/connect/auth/
18+
.. /tutorials/connect/compression/
19+
20+
.. contents:: On this page
21+
:local:
22+
:backlinks: none
23+
:depth: 1
24+
:class: singlecol
25+
26+
This guide describes how to use the {+driver-short+} to connect to
27+
MongoDB.
28+
29+
Use the ``MongoClient()`` method to make a connection to a
30+
running MongoDB deployment.
31+
32+
.. important::
33+
34+
The following examples do not provide an exhaustive list of
35+
ways to instantiate a ``MongoClient``. For a complete list of the
36+
``MongoClient`` companion methods, see the `MongoClient API
37+
documentation <{+api+}/org/mongodb/scala/MongoClient.html>`__.
38+
39+
.. note::
40+
41+
We *strongly recommended* that system keep-alive settings should
42+
be configured with shorter timeouts.
43+
44+
See the :manual:`Does TCP keepalive time affect MongoDB Deployments?
45+
</faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments->`
46+
question and answer in the Server manual FAQ for more information.
47+
48+
Prerequisites
49+
-------------
50+
51+
You must set up the following components to run the code examples in
52+
this guide:
53+
54+
- A running MongoDB deployment to connect to. For example, to
55+
connect to a standalone deployment, you must have access to a running
56+
standalone deployment.
57+
58+
- Driver dependency installed in your project. To learn how to install
59+
the driver, see :ref:`scala-install`.
60+
61+
- The following import statements:
62+
63+
.. code-block:: scala
64+
65+
import org.mongodb.scala._
66+
import scala.collection.JavaConverters._
67+
68+
MongoClient
69+
-----------
70+
71+
A ``MongoClient`` instance represents a pool of connections to the
72+
database. You need only one instance of ``MongoClient`` even
73+
when running multiple concurrent operations.
74+
75+
.. important::
76+
77+
Typically, you create only one ``MongoClient`` instance for a given
78+
MongoDB deployment, such as a standalone deployment, replica set, or a sharded
79+
cluster, and use the client across your application. However, if you do create
80+
multiple instances, keep the following in mind:
81+
82+
- All resource-usage limits (for example, max connections) apply to
83+
each ``MongoClient`` instance.
84+
- To dispose of an instance, call the ``MongoClient.close()`` method
85+
to clean up resources.
86+
87+
Connect to a Standalone MongoDB Deployment
88+
------------------------------------------
89+
90+
The following example shows several ways to connect to a single
91+
MongoDB deployment.
92+
93+
You can connect to a single MongoDB deployment in the following ways:
94+
95+
- Instantiate a ``MongoClient`` object without any parameters to
96+
connect to a MongoDB server running on localhost on port ``27017``:
97+
98+
.. code-block:: scala
99+
100+
val mongoClient = MongoClient()
101+
102+
- Explicitly specify the ``hostname`` to connect to a MongoDB
103+
instance running on the specified host on port ``27017``:
104+
105+
.. code-block:: scala
106+
107+
val mongoClient = MongoClient("mongodb://host1")
108+
109+
- Explicitly specify the ``hostname`` and the ``port``:
110+
111+
.. code-block:: scala
112+
113+
val mongoClient = MongoClient("mongodb://host1:27017")
114+
115+
Connect to a Replica Set
116+
------------------------
117+
118+
To connect to a replica set, you must specify one or more
119+
members to the ``MongoClient`` apply method. To learn more about
120+
replica sets, see :manual:`Replication </replication/>` in the Server
121+
manual.
122+
123+
.. note::
124+
125+
MongoDB auto-discovers the primary and secondary nodes in a replica
126+
set.
127+
128+
You can connect to a MongoDB replica set by specifying the members in
129+
a ``ConnectionString``.
130+
131+
The following example shows how to specify three members of the
132+
replica set:
133+
134+
.. code-block:: scala
135+
136+
val mongoClient = MongoClient("mongodb://host1:27017,host2:27017,host3:27017")
137+
138+
The following example shows how to specify members of the
139+
replica set and the ``replicaSet`` option with the replica set
140+
name:
141+
142+
.. code-block:: scala
143+
144+
val mongoClient = MongoClient("mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet")
145+
146+
The following example shows how to specify a list of
147+
``ServerAddress`` instances corresponding to all of the replica
148+
set members:
149+
150+
.. code-block:: scala
151+
152+
val mongoClient = MongoClient(
153+
MongoClientSettings.builder()
154+
.applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(
155+
new ServerAddress("host1", 27017),
156+
new ServerAddress("host2", 27017),
157+
new ServerAddress("host3", 27017)).asJava))
158+
.build())
159+
160+
Connect to a Sharded Cluster
161+
----------------------------
162+
163+
To connect to a sharded cluster, specify the ``mongos`` instance or
164+
instances to the ``MongoClient`` apply method. To learn more about
165+
sharded clusters, see :manual:`Sharding </sharding/>` in the Server
166+
manual.
167+
168+
You can connect to a single ``mongos`` instance in the following ways:
169+
170+
- Specify the hostname and the port in a ``ConnectionString``:
171+
172+
.. code-block:: scala
173+
174+
val mongoClient = MongoClient( "mongodb://localhost:27017" )
175+
176+
- Exclude connection string if the ``mongos`` is running on
177+
``localhost:27017``:
178+
179+
.. code-block:: scala
180+
181+
val mongoClient = MongoClient()
182+
183+
You can connect to multiple ``mongos`` instances in the following ways:
184+
185+
- Specify the ``ConnectionString`` to contain their hostnames and ports:
186+
187+
.. code-block:: scala
188+
189+
val mongoClient = MongoClient("mongodb://host1:27017,host2:27017")
190+
191+
- Specify a list of the ``ServerAddress`` objects corresponding to
192+
each instance:
193+
194+
.. code-block:: scala
195+
196+
val mongoClient = MongoClient(
197+
MongoClientSettings.builder()
198+
.applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(
199+
new ServerAddress("host1", 27017),
200+
new ServerAddress("host2", 27017)).asJava))
201+
.build())
202+
203+
Connection Options
204+
------------------
205+
206+
You can specify connection settings by using either the
207+
``ConnectionString`` or ``MongoClientSettings`` types, or both.
208+
209+
For example, you can specify TLS/SSL and authentication settings in the
210+
connection string:
211+
212+
.. code-block:: scala
213+
214+
val mongoClient = MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&ssl=true")
215+
216+
You can also use a ``MongoClientSettings`` instance to specify TLS/SSL
217+
and the ``MongoCredential`` type to store the authentication information:
218+
219+
.. code-block:: scala
220+
221+
val user: String = // the user name
222+
val source: String = // the source where the user is defined
223+
val password: Array[Char] = // the password as a character array
224+
// ...
225+
val credential = MongoCredential.createCredential(user, source, password)
226+
227+
val mongoClient: MongoClient = MongoClient(
228+
MongoClientSettings.builder()
229+
.applyToSslSettings((builder: SslSettings.Builder) => builder.enabled(true))
230+
.applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
231+
.credential(credential)
232+
.build())
233+
234+
In some cases, you might need to combine a connection string
235+
with programmatic configuration:
236+
237+
.. code-block:: scala
238+
239+
val connectionString = ConnectionString("mongodb://host1:27107,host2:27017/?ssl=true")
240+
val myCommandListener: CommandListener = ???
241+
242+
val mongoClient = MongoClient(
243+
MongoClientSettings.builder()
244+
.addCommandListener(myCommandListener)
245+
.applyConnectionString(connectionString)
246+
.build())

0 commit comments

Comments
 (0)