diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index df72aba8a..e4f2ead4d 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -15,4 +15,95 @@ Choose a Connection Target :local: :backlinks: none :depth: 2 - :class: singlecol \ No newline at end of file + :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. + +.. tip:: + + To learn more about how to retrieve your connection string, see + the :atlas:`Connect via Drivers ` guide in + the Atlas documentation. + +Atlas +----- + +To connect to a MongoDB deployment on Atlas, include the following elements +in your connection string: + +- URL of your Atlas cluster +- MongoDB username +- MongoDB password + +Then, pass your connection string to the ``MongoClient`` constructor. + +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 ``server_api`` field to specify a {+stable-api+} version. + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-connection-target-atlas + :end-before: end-connection-target-atlas + :dedent: + +Local Deployments +----------------- + +To connect to a local standalone MongoDB deployment, specify the host of the +server. Optionally, specify the port of the server. If no port is specified, +the default port is ``27017``. + +You can specify the host and port to connect to by using a +connection string, as shown in the following code: + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-local-connection-uri + :end-before: end-local-connection-uri + :dedent: + +You can also specify your host as ``localhost``. The following code example +connects to ``localhost`` on the specified port: + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-localhost + :end-before: end-localhost + :dedent: + +Replica Sets +------------ + +To connect to a replica set, we recommend that you specify all nodes that are +part of the replica set. If one or more nodes becomes unavailable, +specifying all nodes allows the driver to still connect to the replica set +if one node is available. + +However, it is sufficient to pass the address of any one node in the replica set +to the driver. The node does not need to be the primary, and it may be a hidden node. +The driver will then automatically discover the remaining nodes. + +The following example shows how to connect to the replica set by using a connection +string and how to verify the replica set name on connection by using the +``replicaSet`` connection string option: + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-replica-set-option + :end-before: end-replica-set-option + :dedent: + +API Documentation +----------------- + +To learn more about creating a ``MongoClient`` object with the {+driver-short+}, +see the API documentation for `MongoClient <{+api+}/classes/MongoClient.html>`__ . diff --git a/source/includes/connect/connection-targets.js b/source/includes/connect/connection-targets.js new file mode 100644 index 000000000..c71cd9935 --- /dev/null +++ b/source/includes/connect/connection-targets.js @@ -0,0 +1,43 @@ +// start-connection-target-atlas +const { MongoClient, ServerApiVersion } = require("mongodb"); + +// Replace the placeholder with your Atlas connection string +const uri = ""; + +// Creates a MongoClient with a MongoClientOptions object to set the Stable API version +const client = new MongoClient(uri, { + serverApi: { + version: ServerApiVersion.v1, + strict: true, + deprecationErrors: true, + } + } +); + +async function run() { + try { + // Connects the client to the server (optional starting in v4.7) + await client.connect(); + + // Sends a ping to confirm a successful connection + await client.db("admin").command({ ping: 1 }); + console.log("Pinged your deployment. You successfully connected to MongoDB!"); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } +} +run().catch(console.dir); +// end-connection-target-atlas + +// start-local-connection-uri +const client = new MongoClient("mongodb://host1:27017"); +// end-local-connection-uri + +// start-localhost +const client = new MongoClient("mongodb://localhost:27017"); +// end-localhost + +// start-replica-set-option +const client = new MongoClient("mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRs"); +// end-replica-set-option