Skip to content

Commit ebfdafe

Browse files
lindseymoorelindseymoore
authored
DOCSP-41121 Connect to Mongo Client (mongodb#34)
* DOCSP-41121 Connect to MongoDB * reword * fix markdown errors * fix * change title * review comments * fix * fix pt 2 * add api doc section * fix connection string link * new option for connecting * revision * connection string link * fix toc * fix toc
1 parent 7f97934 commit ebfdafe

File tree

5 files changed

+215
-3
lines changed

5 files changed

+215
-3
lines changed

‎source/connect.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,11 @@ Connect to MongoDB
2222
:titlesonly:
2323
:maxdepth: 1
2424

25-
/connect/stable-api
25+
/connect/mongoclient
2626
/connect/connection-targets
27+
/connect/connection-options
28+
/connect/stable-api
2729

28-
.. /connect/mongoclient
29-
.. /connect/connection-options
3030
.. /connect/tls
3131
.. /connect/network-compression
3232
.. /connect/server-selection

‎source/connect/connection-options.txt

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _kotlin-sync-connection-options:
2+
3+
==========================
4+
Specify Connection Options
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: connection string, URI, server, Atlas, settings, configure
19+
20+
Overview
21+
--------

‎source/connect/mongoclient.txt

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _kotlin-sync-mongoclient:
2+
3+
====================
4+
Create a MongoClient
5+
====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, Atlas, 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+
To connect to a MongoDB deployment, you need two things:
24+
25+
- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+}
26+
which MongoDB deployment to connect to.
27+
- A **MongoClient** object, which creates the connection to and performs
28+
operations on the MongoDB deployment.
29+
30+
You can also use ``MongoClientSettings`` to customize the way the {+driver-short+} behaves
31+
while connected to MongoDB.
32+
33+
This guide shows you how to create a connection string and use a ``MongoClient`` object
34+
to connect to MongoDB.
35+
36+
.. _kotlin-sync-connection-uri:
37+
38+
Connection URI
39+
--------------
40+
41+
A standard connection string includes the following components:
42+
43+
.. TODO, add this as last sentence for ``username:password`` description once a kotlin auth page is made:
44+
.. For more information about the ``authSource`` connection option, see :ref:`kotlin-sync-auth`.
45+
46+
.. list-table::
47+
:widths: 20 80
48+
:header-rows: 1
49+
50+
* - Component
51+
- Description
52+
53+
* - ``mongodb://``
54+
55+
- Required. A prefix that identifies this as a string in the
56+
standard connection format.
57+
58+
* - ``username:password``
59+
60+
- Optional. Authentication credentials. If you include these, the client
61+
authenticates the user against the database specified in ``authSource``.
62+
63+
* - ``host[:port]``
64+
65+
- Required. The host and optional port number where MongoDB is running. If you don't
66+
include the port number, the driver uses the default port, ``27017``.
67+
68+
* - ``/defaultauthdb``
69+
70+
- Optional. The authentication database to use if the
71+
connection string includes ``username:password@``
72+
authentication credentials but not the ``authSource`` option. If you don't include
73+
this component, the client authenticates the user against the ``admin`` database.
74+
75+
* - ``?<options>``
76+
77+
- Optional. A query string that specifies connection-specific
78+
options as ``<name>=<value>`` pairs. See
79+
:ref:`kotlin-sync-connection-options` for a full description of
80+
these options.
81+
82+
For more information about creating a connection string, see
83+
:manual:`Connection Strings </reference/connection-string>` in the
84+
MongoDB Server documentation.
85+
86+
Atlas Connection Example
87+
------------------------
88+
89+
To connect to a MongoDB deployment on Atlas, you must first create a client.
90+
91+
You can pass a connection URI as a string to the ``MongoClient.create()`` method
92+
to connect to a MongoDB instance:
93+
94+
.. literalinclude:: /includes/connect/mongoclient2.kt
95+
:start-after: start-connect-to-atlas-w-uri
96+
:end-before: end-connect-to-atlas-w-uri
97+
:language: kotlin
98+
:copyable:
99+
:dedent:
100+
101+
You can also create a client with your desired configurations by passing a
102+
``MongoClientSettings`` object to the ``MongoClient.create()`` method.
103+
104+
To instantiate a ``MongoClientSettings`` object, use the builder method to
105+
specify your connection string, using the ``applyConnectionString()`` method,
106+
and any other client options. Once you have your desired configuration,
107+
call the ``build()`` method.
108+
109+
You can set the Stable API version client option to avoid breaking changes when
110+
you upgrade to a new server version. To learn more about the Stable API feature,
111+
see the :ref:`Stable API page <kotlin-sync-stable-api>`.
112+
113+
The following code shows how you can specify the connection string and the
114+
Stable API client option when connecting to a MongoDB deployment on Atlas
115+
and verify that the connection is successful:
116+
117+
.. literalinclude:: /includes/connect/mongoclient.kt
118+
:start-after: start-connect-to-atlas
119+
:end-before: end-connect-to-atlas
120+
:language: kotlin
121+
:copyable:
122+
:dedent:
123+
124+
API Documentation
125+
-----------------
126+
127+
For more information about creating a ``MongoClient`` object with the
128+
{+driver-short+}, see the following API documentation:
129+
130+
- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__
131+
- `MongoClientSettings <{+core-api+}com/mongodb/MongoClientSettings.html>`__

‎source/includes/connect/mongoclient.kt

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import com.mongodb.*
2+
import com.mongodb.kotlin.client.MongoClient
3+
import org.bson.BsonInt64
4+
import org.bson.Document
5+
6+
fun main() {
7+
8+
// start-connect-to-atlas
9+
// start-connect-to-atlas-w-uri
10+
// Replace the placeholder with your Atlas connection string
11+
val uri = "<connection string>"
12+
val mongoClient1 = MongoClient.create(uri)
13+
// end-connect-to-atlas-w-uri
14+
15+
// Construct a ServerApi instance using the ServerApi.builder() method
16+
val serverApi = ServerApi.builder()
17+
.version(ServerApiVersion.V1)
18+
.build()
19+
val settings = MongoClientSettings.builder()
20+
.applyConnectionString(ConnectionString(uri))
21+
.serverApi(serverApi)
22+
.build()
23+
24+
// Create a new client and connect to the server
25+
val mongoClient = MongoClient.create(settings)
26+
val database = mongoClient.getDatabase("sample_mflix")
27+
28+
try {
29+
// Send a ping to confirm a successful connection
30+
val command = Document("ping", BsonInt64(1))
31+
val commandResult = database.runCommand(command)
32+
println("Pinged your deployment. You successfully connected to MongoDB!")
33+
} catch (me: MongoException) {
34+
System.err.println(me)
35+
}
36+
// end-connect-to-atlas
37+
}

‎source/includes/connect/mongoclient2.kt

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import com.mongodb.*
2+
import com.mongodb.kotlin.client.MongoClient
3+
4+
fun main() {
5+
6+
// start-connect-to-atlas-w-uri
7+
// Replace the placeholder with your Atlas connection string
8+
val uri = "<connection string>"
9+
10+
// Create a new client and connect to the server
11+
val mongoClient = MongoClient.create(uri)
12+
val database = mongoClient.getDatabase("sample_mflix")
13+
// end-connect-to-atlas-w-uri
14+
15+
try {
16+
// Send a ping to confirm a successful connection
17+
val command = Document("ping", BsonInt64(1))
18+
val commandResult = database.runCommand(command)
19+
println("Pinged your deployment. You successfully connected to MongoDB!")
20+
} catch (me: MongoException) {
21+
System.err.println(me)
22+
}
23+
}

0 commit comments

Comments
 (0)