Skip to content

Commit 89f8076

Browse files
mcmorisimcmorisi
authored
DOCSP-41122: Choose a Connection Target (mongodb#33)
1 parent 88f71b9 commit 89f8076

File tree

3 files changed

+178
-5
lines changed

3 files changed

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

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
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+
// Defines Stable API version
12+
val serverApi = ServerApi.builder()
13+
.version(ServerApiVersion.V1)
14+
.build()
15+
16+
// Uses MongoClientSettings to apply connection string and specify the Stable API version
17+
val settings = MongoClientSettings.builder()
18+
.applyConnectionString("<connection string URI>")
19+
.serverApi(serverApi)
20+
.build()
21+
22+
val mongoClient = MongoClient.create(settings)
23+
// end-connect
24+
25+
// start-connect-local
26+
val settings = MongoClientSettings.builder()
27+
.applyConnectionString("mongodb://localhost:27017")
28+
.build()
29+
30+
val mongoClient = MongoClient.create(settings)
31+
// end-connect-local
32+
33+
// start-connect-rs-connection-string
34+
val mongoClient = MongoClient.create("mongodb://host1:27017,host2:27017,host3:27017/")
35+
// end-connect-rs-connection-string
36+
37+
// start-connect-rs-settings
38+
val hosts = listOf(
39+
ServerAddress("host1", 27017),
40+
ServerAddress("host2", 27017),
41+
ServerAddress("host3", 27017)
42+
)
43+
44+
val settings = MongoClientSettings.builder()
45+
.applyToClusterSettings { builder ->
46+
builder.hosts(hosts)
47+
}
48+
.build()
49+
50+
val mongoClient = MongoClient.create(settings)
51+
// end-connect-rs-settings
52+
}
53+

0 commit comments

Comments
 (0)