DOCSP-45178 Choose a Connection Target

source/connect.txt

@@ -22,5 +22,6 @@ Connect to MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /connect/mongoclient
-   /connect/stable-api
+   Create a Client </connect/mongoclient>
+   Stable API </connect/stable-api>
+   Choose a Connection Target </connect/connection-targets>

source/connect/connection-targets.txt

@@ -0,0 +1,131 @@
+.. _ruby-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 ``Mongo::Client`` 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 ``Mongo::Client`` constructor.
+
+.. tip::
+
+   Follow the :atlas:`Atlas driver connection guide </driver-connection>`
+   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:`<ruby-stable-api>`
+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.rb
+   :language: ruby
+   :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 and the database to connect
+to. If no port is specified, the default port is ``27017``. If no database name 
+is specified, the client will use the ``admin`` database:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-local-connection
+   :end-before: end-local-connection
+   :dedent:
+
+You can also specify the host, port, and database to connect to using a  
+connection string:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :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 default port, ``27017``:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-localhost
+   :end-before: end-localhost
+   :dedent:
+
+Replica Sets
+------------
+
+To connect to a replica set, it is recommended to specify all nodes that are 
+part of the replica set. In the event that one or more nodes becomes unavailable,
+specifying all nodes allows the driver to still connect to the replica set, 
+as long as 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 have 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 specify three members of the replica set:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-replica-set
+   :end-before: end-replica-set
+   :dedent:
+
+The following example shows how to connect to the replica set using a connection
+string:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-replica-set-uri
+   :end-before: end-replica-set-uri
+   :dedent:
+
+The following example shows how to verify the replica set name upon connection
+by using the ``replica_set`` option or the ``replicaSet`` connection string option:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-replica-set-option
+   :end-before: end-replica-set-option
+   :dedent:
+
+API Documentation
+-----------------
+
+To learn more about creating a ``Mongo::Client`` object with the {+driver-short+},
+see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .

source/includes/connect/connection-targets.rb

@@ -0,0 +1,49 @@
+# start-connection-target-atlas
+require 'mongo'
+
+# Replace the placeholders with your credentials
+uri = "<connection string>"
+
+# Sets the server_api field of the options object to Stable API version 1
+options = { server_api: { version: '1' } }
+# Creates a new client and connect to the server
+client = Mongo::Client.new(uri, options)
+# Sends a ping to confirm a successful connection
+begin
+  admin_client = client.use('admin')
+  result = admin_client.database.command(ping: 1).documents.first
+  puts "Pinged your deployment. You successfully connected to MongoDB!"
+rescue Mongo::Error::OperationFailure => ex
+  puts ex
+ensure
+  client.close
+end
+# end-connection-target-atlas
+
+# start-local-connection
+Mongo::Client.new([ 'host1:27017' ], database: 'mydb')
+# end-local-connection
+
+# start-local-connection-uri
+Mongo::Client.new("mongodb://host1:27017/mydb")
+# end-local-connection-uri
+
+# start-localhost
+client = Mongo::Client.new(["localhost"])
+# end-localhost
+
+# start-replica-set
+Mongo::Client.new([ 'host1:27017', 'host2:27018', `host3:21019` ], database: 'mydb')
+# end-replica-set
+
+# start-replica-set-uri
+Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb")
+# end-replica-set-uri
+
+# start-replica-set-option
+Mongo::Client.new([ 'host1:27017', 'host2:27018', 'host3:27019' ],
+  database: 'mydb', replica_set: 'myapp')
+
+# Or by using a connection string:
+Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb?replicaSet=myapp")
+# end-replica-set-option