From 46de8bbd07047425581150325d295d951afb6d6f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 10 Jan 2025 18:30:05 -0500 Subject: [PATCH 1/7] DOCSP-45178 Choose a Connection Target --- source/connect.txt | 6 +- source/connect/connection-targets.txt | 129 ++++++++++++++++++ source/includes/connect/connection-targets.rb | 49 +++++++ 3 files changed, 182 insertions(+), 2 deletions(-) create mode 100644 source/connect/connection-targets.txt create mode 100644 source/includes/connect/connection-targets.rb diff --git a/source/connect.txt b/source/connect.txt index f3b875c7..88dde989 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -22,5 +22,7 @@ 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 + \ No newline at end of file diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..f065613e --- /dev/null +++ b/source/connect/connection-targets.txt @@ -0,0 +1,129 @@ +.. _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 using the URI +syntax: + +.. literalinclude:: /includes/connect/connection-targets.rb + :language: ruby + :start-after: start-local-connection-uri + :end-before: end-local-connection-uri + :dedent: + +You can use ``localhost`` to specify your host name, as well. The following +code example connects to ``localhost`` on 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, so in the event that one or more nodes becomes +unavailable, the driver can still connect to the replica set. + +However, it is sufficient to pass the address of any 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 the URI syntax: + +.. 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`` URI 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..db98c830 --- /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 = "mongodb+srv://lindsey:me123@atlascluster.spm1ztf.mongodb.net/?retryWrites=true&w=majority&appName=AtlasCluster" + +# Set the server_api field of the options object to Stable API version 1 +options = { server_api: { version: "1" } } +# Create a new client and connect to the server +client = Mongo::Client.new(uri, options) +# Send 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/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://127.0.0.1:27017,127.0.0.1:27018/mydb") +# end-replica-set-uri + +# start-replica-set-option +Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ], + database: 'mydb', replica_set: 'myapp') + +# Or using the URI syntax: +Mongo::Client.new("mongodb://host1:27017,host2:27018, host3:27019/mydb?replicaSet=myapp") +# end-replica-set-option \ No newline at end of file From 3f9bd766565267acf9b46cfb27a70f2bb9bb964b Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 10 Jan 2025 18:39:32 -0500 Subject: [PATCH 2/7] edits and add page to TOC --- source/connect.txt | 3 +-- source/connect/connection-targets.txt | 13 +++++++------ source/includes/connect/connection-targets.rb | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 88dde989..dce14c10 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -24,5 +24,4 @@ Connect to MongoDB Create a Client Stable API - Choose a Connection Target - \ No newline at end of file + Choose a Connection Target diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index f065613e..84dcd4b9 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -68,8 +68,8 @@ is specified, the client will use the ``admin`` database: :end-before: end-local-connection :dedent: -You can also specify the host, port, and database to connect using the URI -syntax: +You can also specify the host, port, and database to connect to using a +connection string: .. literalinclude:: /includes/connect/connection-targets.rb :language: ruby @@ -77,8 +77,8 @@ syntax: :end-before: end-local-connection-uri :dedent: -You can use ``localhost`` to specify your host name, as well. The following -code example connects to ``localhost`` on port ``27017``: +You can also specify your host as ``localhost``. The following code example +connects to ``localhost`` on port ``27017``: .. literalinclude:: /includes/connect/connection-targets.rb :language: ruby @@ -105,7 +105,8 @@ The following example shows how to specify three members of the replica set: :end-before: end-replica-set :dedent: -The following example shows how to connect to the replica set using the URI syntax: +The following example shows how to connect to the replica set using a connection +string: .. literalinclude:: /includes/connect/connection-targets.rb :language: ruby @@ -114,7 +115,7 @@ The following example shows how to connect to the replica set using the URI synt :dedent: The following example shows how to verify the replica set name upon connection -by using the ``replica_set`` option or the ``replicaSet`` URI option: +by using the ``replica_set`` option or the ``replicaSet`` connection string option: .. literalinclude:: /includes/connect/connection-targets.rb :language: ruby diff --git a/source/includes/connect/connection-targets.rb b/source/includes/connect/connection-targets.rb index db98c830..e1b61fda 100644 --- a/source/includes/connect/connection-targets.rb +++ b/source/includes/connect/connection-targets.rb @@ -46,4 +46,4 @@ # Or using the URI syntax: Mongo::Client.new("mongodb://host1:27017,host2:27018, host3:27019/mydb?replicaSet=myapp") -# end-replica-set-option \ No newline at end of file +# end-replica-set-option From 0eb75f27aba28f6392777a2d7ee06ffb8043687d Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 10 Jan 2025 18:51:22 -0500 Subject: [PATCH 3/7] more small edits --- source/connect/connection-targets.txt | 4 ++-- source/includes/connect/connection-targets.rb | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 84dcd4b9..0681b87a 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -78,7 +78,7 @@ connection string: :dedent: You can also specify your host as ``localhost``. The following code example -connects to ``localhost`` on port ``27017``: +connects to ``localhost`` on the default port, ``27017``: .. literalinclude:: /includes/connect/connection-targets.rb :language: ruby @@ -127,4 +127,4 @@ 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>`__. +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 index e1b61fda..6bd21e69 100644 --- a/source/includes/connect/connection-targets.rb +++ b/source/includes/connect/connection-targets.rb @@ -2,7 +2,7 @@ require 'mongo' # Replace the placeholders with your credentials -uri = "mongodb+srv://lindsey:me123@atlascluster.spm1ztf.mongodb.net/?retryWrites=true&w=majority&appName=AtlasCluster" +uri = "" # Set the server_api field of the options object to Stable API version 1 options = { server_api: { version: "1" } } @@ -37,13 +37,13 @@ # end-replica-set # start-replica-set-uri -Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb") +Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb") # end-replica-set-uri # start-replica-set-option -Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ], +Mongo::Client.new([ 'host1:27017', 'host2:27018', 'host3:27019' ], database: 'mydb', replica_set: 'myapp') # Or using the URI syntax: -Mongo::Client.new("mongodb://host1:27017,host2:27018, host3:27019/mydb?replicaSet=myapp") +Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb?replicaSet=myapp") # end-replica-set-option From c13d56d7f127921baa53fad6e36c1d78aa77449c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 10 Jan 2025 19:02:09 -0500 Subject: [PATCH 4/7] last edits --- source/connect/connection-targets.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 0681b87a..236530c8 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -90,11 +90,12 @@ Replica Sets ------------ To connect to a replica set, it is recommended to specify all nodes that are -part of the replica set, so in the event that one or more nodes becomes -unavailable, the driver can still connect to the replica set. +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 node in the replica set -to the driver. The node does not have to be the primary and it may be a hidden node. +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: From 4fd9bd68c6a70a1a4e54f4ce6aeb218e54c7ce92 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 13 Jan 2025 12:53:39 -0500 Subject: [PATCH 5/7] no hyper linked period --- source/connect/connection-targets.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 236530c8..29fd1119 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -128,4 +128,4 @@ 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>`__. +see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ . From 298b2cee161156762e7df912f848235837df9ce4 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 13 Jan 2025 13:05:38 -0500 Subject: [PATCH 6/7] coe improvements --- source/includes/connect/connection-targets.rb | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/includes/connect/connection-targets.rb b/source/includes/connect/connection-targets.rb index 6bd21e69..c9f59be4 100644 --- a/source/includes/connect/connection-targets.rb +++ b/source/includes/connect/connection-targets.rb @@ -4,11 +4,11 @@ # Replace the placeholders with your credentials uri = "" -# Set the server_api field of the options object to Stable API version 1 +# Sets the server_api field of the options object to Stable API version 1 options = { server_api: { version: "1" } } -# Create a new client and connect to the server +# Creates a new client and connect to the server client = Mongo::Client.new(uri, options) -# Send a ping to confirm a successful connection +# Sends a ping to confirm a successful connection begin admin_client = client.use('admin') result = admin_client.database.command(ping: 1).documents.first @@ -25,7 +25,7 @@ # end-local-connection # start-local-connection-uri -Mongo::Client.new("mongodb://host1/mydb") +Mongo::Client.new("mongodb://host1:27017/mydb") # end-local-connection-uri # start-localhost @@ -44,6 +44,6 @@ Mongo::Client.new([ 'host1:27017', 'host2:27018', 'host3:27019' ], database: 'mydb', replica_set: 'myapp') -# Or using the URI syntax: +# Or by using a connection string: Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb?replicaSet=myapp") # end-replica-set-option From 3f0e7a3f7e5e0d0dc657f4dc4e691f08751471cc Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 10:57:50 -0500 Subject: [PATCH 7/7] stable api single quote --- source/includes/connect/connection-targets.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/connect/connection-targets.rb b/source/includes/connect/connection-targets.rb index c9f59be4..93623047 100644 --- a/source/includes/connect/connection-targets.rb +++ b/source/includes/connect/connection-targets.rb @@ -5,7 +5,7 @@ uri = "" # Sets the server_api field of the options object to Stable API version 1 -options = { server_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