diff --git a/source/connect.txt b/source/connect.txt index f3b875c7..dce14c10 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -22,5 +22,6 @@ Connect to MongoDB :titlesonly: :maxdepth: 1 - /connect/mongoclient - /connect/stable-api \ No newline at end of file + Create a Client + Stable API + Choose a Connection Target diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..29fd1119 --- /dev/null +++ b/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 ` + 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 ``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>`__ . diff --git a/source/includes/connect/connection-targets.rb b/source/includes/connect/connection-targets.rb new file mode 100644 index 00000000..93623047 --- /dev/null +++ b/source/includes/connect/connection-targets.rb @@ -0,0 +1,49 @@ +# start-connection-target-atlas +require 'mongo' + +# Replace the placeholders with your credentials +uri = "" + +# 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