Skip to content

Commit 8703138

Browse files
mcmorisimcmorisi
committed
DOCSP-41122: Choose a Connection Target
1 parent ad61726 commit 8703138

File tree

3 files changed

+180
-5
lines changed

3 files changed

+180
-5
lines changed

‎source/connect.txt

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@ Connect to MongoDB
1919
:keywords: client, ssl, tls, localhost
2020

2121
.. toctree::
22-
:titlesonly:
23-
:maxdepth: 1
22+
:titlesonly:
23+
:maxdepth: 1
2424

25-
/connect/stable-api
26-
..
25+
/connect/stable-api
26+
/connect/connection-targets
27+
2728
.. /connect/mongoclient
28-
.. /connect/connection-targets
2929
.. /connect/connection-options
3030
.. /connect/tls
3131
.. /connect/network-compression

‎source/connect/connection-targets.txt

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
.. _kotlin-sync-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 ``MongoClient`` 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 ``MongoClient`` constructor.
37+
38+
.. tip::
39+
40+
Follow the :atlas:`Atlas driver connection guide </driver-connection?tck=docs_driver_python>`
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 :ref:`<kotlin-sync-stable-api>`.
46+
47+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
48+
code also uses the ``serverApi()`` method to specify a {+stable-api+} version.
49+
50+
.. literalinclude:: /includes/connect/connection-targets.kt
51+
:language: kotlin
52+
:start-after: start-connect
53+
:end-before: end-connect
54+
:dedent:
55+
56+
Local Deployments
57+
-----------------
58+
59+
To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
60+
default, the ``mongod`` process runs on port 27017, though you can customize this for
61+
your deployment.
62+
63+
The following code shows how to use the {+driver-short+} to connect to a local MongoDB
64+
deployment:
65+
66+
.. literalinclude:: /includes/connect/connection-targets.kt
67+
:language: kotlin
68+
:start-after: start-connect-local
69+
:end-before: end-connect-local
70+
:dedent:
71+
72+
Replica Sets
73+
------------
74+
75+
To connect to a replica set, specify the hostnames (or IP addresses) and
76+
port numbers of the replica-set members.
77+
78+
If you aren't able to provide a full list of hosts in the replica set, you can
79+
specify one or more of the hosts in the replica set and instruct the {+driver-short+} to
80+
perform automatic discovery to find the others. To instruct the driver to perform
81+
automatic discovery, perform one of the following actions:
82+
83+
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
84+
- Specify ``false`` as the value of the ``directConnection`` parameter.
85+
- Specify more than one host in the replica set.
86+
87+
The following examples show how to specify multiple hosts to a ``MongoClient`` instance
88+
using either the ``ConnectionString`` or ``MongoClientSettings`` class. Select the tab
89+
that corresponds to your preferred class.
90+
91+
.. tabs::
92+
93+
.. tab:: ConnectionString
94+
:tabid: connectionstring
95+
96+
.. literalinclude:: /includes/connect/connection-targets.kt
97+
:language: kotlin
98+
:start-after: start-connect-rs-connection-string
99+
:end-before: end-connect-rs-connection-string
100+
:dedent:
101+
102+
.. tab:: MongoClientSettings
103+
:tabid: connectionstring
104+
105+
.. literalinclude:: /includes/connect/connection-targets.kt
106+
:language: kotlin
107+
:start-after: start-connect-rs-settings
108+
:end-before: end-connect-rs-settings
109+
:dedent:
110+
111+
.. note::
112+
113+
The ``MongoClient`` constructor is *non-blocking*.
114+
When you connect to a replica set, the constructor returns immediately while the
115+
client uses background threads to connect to the replica set.
116+
117+
If you construct a ``MongoClient`` and immediately print the string representation
118+
of its ``nodes`` attribute, the list might be empty while the client connects to
119+
the replica-set members.

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

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
package org.example
2+
import com.mongodb.ConnectionString
3+
import com.mongodb.MongoClientSettings
4+
import com.mongodb.ServerAddress
5+
import com.mongodb.ServerApi
6+
import com.mongodb.ServerApiVersion
7+
import com.mongodb.kotlin.client.MongoClient
8+
9+
fun main() {
10+
// start-connect
11+
val connectionString = ConnectionString("<connection string URI>")
12+
13+
val serverApi = ServerApi.builder()
14+
.version(ServerApiVersion.V1)
15+
.build()
16+
17+
val settings = MongoClientSettings.builder()
18+
.applyConnectionString(connectionString)
19+
.serverApi(serverApi)
20+
.build()
21+
22+
val mongoClient = MongoClient.create(settings)
23+
// end-connect
24+
25+
// start-connect-local
26+
val connectionString = ConnectionString("mongodb://localhost:27017")
27+
28+
val settings = MongoClientSettings.builder()
29+
.applyConnectionString(connectionString)
30+
.build()
31+
32+
val mongoClient = MongoClient.create(settings)
33+
// end-connect-local
34+
35+
// start-connect-rs-connection-string
36+
val connectionString = ConnectionString("mongodb://host1:27017,host2:27017,host3:27017/")
37+
val mongoClient = MongoClient.create(connectionString)
38+
// end-connect-rs-connection-string
39+
40+
// start-connect-rs-settings
41+
val hosts = listOf(
42+
ServerAddress("host1", 27017),
43+
ServerAddress("host2", 27017),
44+
ServerAddress("host3", 27017)
45+
)
46+
47+
val settings = MongoClientSettings.builder()
48+
.applyToClusterSettings { builder ->
49+
builder.hosts(hosts)
50+
}
51+
.build()
52+
53+
val mongoClient = MongoClient.create(settings)
54+
// end-connect-rs-settings
55+
}
56+

0 commit comments

Comments
 (0)