diff --git a/source/connect.txt b/source/connect.txt index e1a34974..946eac4e 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -19,13 +19,13 @@ Connect to MongoDB :keywords: client, ssl, tls, localhost .. toctree:: - :titlesonly: - :maxdepth: 1 + :titlesonly: + :maxdepth: 1 - /connect/stable-api -.. + /connect/stable-api + /connect/connection-targets + .. /connect/mongoclient -.. /connect/connection-targets .. /connect/connection-options .. /connect/tls .. /connect/network-compression diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..625e85a2 --- /dev/null +++ b/source/connect/connection-targets.txt @@ -0,0 +1,120 @@ +.. _kotlin-sync-connection-targets: + +========================== +Choose a Connection Target +========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, server, settings, client + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use a connection string and a ``MongoClient`` object +to connect to different types of MongoDB deployments. + +Atlas +----- + +To connect to a MongoDB deployment on Atlas, include the following elements +in your connection string: + +- The URL of your Atlas cluster +- Your MongoDB username +- Your MongoDB password + +Then, pass your connection string to the ``MongoClient`` constructor. + +.. tip:: + + Follow the :atlas:`Atlas driver connection guide ` + to retrieve your connection string. + +When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid +breaking changes when Atlas upgrades to a new version of {+mdb-server+}. +To learn more about the {+stable-api+} feature, see the :ref:`` +guide. + +The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The +code also uses the ``serverApi()`` method to specify a {+stable-api+} version. + +.. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect + :end-before: end-connect + :dedent: + +Local Deployments +----------------- + +To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By +default, the ``mongod`` process runs on port 27017, though you can customize this for +your deployment. + +The following code shows how to use the {+driver-short+} to connect to a local MongoDB +deployment: + +.. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect-local + :end-before: end-connect-local + :dedent: + +Replica Sets +------------ + +To connect to a replica set, specify the hostnames (or IP addresses) and +port numbers of the replica-set members. + +If you aren't able to provide a full list of hosts in the replica set, you can +specify one or more of the hosts in the replica set and instruct the {+driver-short+} to +perform automatic discovery to find the others. To instruct the driver to perform +automatic discovery, perform one of the following actions: + +- Specify the name of the replica set as the value of the ``replicaSet`` parameter. +- Specify ``false`` as the value of the ``directConnection`` parameter. +- Specify more than one host in the replica set. + +The following examples show how to connect to a MongoDB replica set running on port +``27017`` of three different hosts by using either the ``ConnectionString`` or +``MongoClientSettings`` class. Select the tab that corresponds to your preferred class. + +.. tabs:: + + .. tab:: ConnectionString + :tabid: connectionstring + + .. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect-rs-connection-string + :end-before: end-connect-rs-connection-string + :dedent: + + .. tab:: MongoClientSettings + :tabid: mongoclientsettings + + .. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect-rs-settings + :end-before: end-connect-rs-settings + :dedent: + +.. note:: + + The ``MongoClient`` constructor is *non-blocking*. + When you connect to a replica set, the constructor returns immediately while the + client uses background threads to connect to the replica set. + + If you construct a ``MongoClient`` and immediately print the string representation + of its ``nodes`` attribute, the list might be empty while the client connects to + the replica-set members. diff --git a/source/includes/connect/connection-targets.kt b/source/includes/connect/connection-targets.kt new file mode 100644 index 00000000..c9080d9e --- /dev/null +++ b/source/includes/connect/connection-targets.kt @@ -0,0 +1,53 @@ +package org.example +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.ServerAddress +import com.mongodb.ServerApi +import com.mongodb.ServerApiVersion +import com.mongodb.kotlin.client.MongoClient + +fun main() { + // start-connect + // Defines Stable API version + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build() + + // Uses MongoClientSettings to apply connection string and specify the Stable API version + val settings = MongoClientSettings.builder() + .applyConnectionString("") + .serverApi(serverApi) + .build() + + val mongoClient = MongoClient.create(settings) + // end-connect + + // start-connect-local + val settings = MongoClientSettings.builder() + .applyConnectionString("mongodb://localhost:27017") + .build() + + val mongoClient = MongoClient.create(settings) + // end-connect-local + + // start-connect-rs-connection-string + val mongoClient = MongoClient.create("mongodb://host1:27017,host2:27017,host3:27017/") + // end-connect-rs-connection-string + + // start-connect-rs-settings + val hosts = listOf( + ServerAddress("host1", 27017), + ServerAddress("host2", 27017), + ServerAddress("host3", 27017) + ) + + val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(hosts) + } + .build() + + val mongoClient = MongoClient.create(settings) + // end-connect-rs-settings +} +