From e48b2bf81ee242e7508fc0a475f5756d5ecfcf18 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 4 Jun 2025 16:28:22 -0700 Subject: [PATCH 1/6] add page content and link to manual --- source/connect/mongoclient.txt | 188 ++++++++++++++++++++++++++++++++- 1 file changed, 187 insertions(+), 1 deletion(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 226818c7..58100522 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -10,5 +10,191 @@ Create a MongoClient :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, Atlas, code example -.. TODO \ No newline at end of file +Overview +-------- + +In this guide, you can learn how to connect to a `MongoDB Atlas deployment +`__, a MongoDB instance, or a replica set +using the {+driver-short+}. + +To connect to a MongoDB deployment, you need the following two things: + +- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+} + which MongoDB deployment to connect to. + +- **MongoClient** object, which creates the connection to and performs operations + on the MongoDB deployment. + +You can use ``options.Client()`` to customize the way the {+driver-short+} +behaves while connected to MongoDB. + +Connection URI +-------------- + +A standard connection string includes the following components: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Component + - Description + + * - ``mongodb://`` + + - Required. A prefix that identifies this as a string in the + standard connection format. + + * - ``username:password`` + + - Optional. Authentication credentials. If you include these, the client + authenticates the user against the database specified in ``authSource``. + For more information about the ``authSource`` connection option, + see :ref:`golang-connection-troubleshooting` in the Connection Troubleshooting guide. + + * - ``host[:port]`` + + - Required. The host and optional port number where MongoDB is running. If you don't + include the port number, the driver uses the default port, ``27017``. + + * - ``/defaultauthdb`` + + - Optional. The authentication database to use if the + connection string includes ``username:password@`` + authentication credentials but not the ``authSource`` option. + When you call ``client.db()`` with no argument, this is the database that is used. If you don't include + this component, the client authenticates the user against the ``admin`` database. + + * - ``?`` + + - Optional. A query string that specifies connection-specific + options as ``=`` pairs. See + :ref:`golang-connection-options` for a full description of + these options. + +For more information about creating a connection string, see :manual:`Connection +Strings ` in the MongoDB Server documentation. + +Atlas Connection Example +------------------------ + +To connect to MongoDB, you must create a client. A client manages your +connections and runs database commands. + +.. tip:: Reuse Your Client + + We recommend that you reuse your client across sessions and operations. You + can use the same ``Client`` instance to perform multiple tasks, instead of + creating a new one each time. The ``Client`` type is safe for concurrent use + by multiple `goroutines `__. To learn more + about how connection pools work in the driver, see the + :ref:`golang-connection-pools` guide. + +You can create a client that uses your connection string and other client +options by passing a ``ClientOptions`` object to the ``Connect()`` method. + +To specify your connection URI, pass it to the ``ApplyURI()`` method, which +returns a new ``ClientOptions`` instance. To set any other options, call the +relevant helper method from the options package. + +To learn more about connection options, see the :ref:`Connection Options section +`. To learn more about creating a client, see the API +documentation for `Client <{+api+}/mongo#Client>`__ and `Connect() +<{+api+}/mongo#Connect>`__. + +You can set the {+stable-api+} version as an option to avoid breaking changes +when you upgrade to a new server version. To learn more about the {+stable-api+} +feature, see the :ref:`{+stable-api+} page `. + +The following code shows how you can create a client that uses an Atlas +connection string and the {+stable-api+} version, connect to MongoDB, and verify +that the connection is successful: + +.. _go-connection-example-code: + +.. literalinclude:: /includes/fundamentals/code-snippets/srv.go + :language: go + :copyable: + :dedent: + +.. tip:: + + Follow the :ref:`Quick Start guide ` + to learn how to retrieve your Atlas connection string. + +.. note:: + + To learn about connecting to Atlas Serverless, see the + :ref:`Serverless Instance Limitations page + ` to identify the minimum driver version + required. + +Other Ways to Connect to MongoDB +-------------------------------- + +If you are connecting to a single MongoDB server instance or replica set +that is not hosted on Atlas, see the following sections to find out how to +connect. + +Connect to a MongoDB Server on Your Local Machine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/localhost-connection.rst + +To test whether you can connect to your server, replace the connection +string with your localhost connection string in the preceding code example. + +Connect to a Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~ + +A MongoDB replica set deployment is a group of connected instances that +store the same set of data. This configuration provides data +redundancy and high data availability. + +To connect to a replica set deployment, specify the hostname and port numbers +of each instance, separated by commas, and the replica set name as the value +of the ``replicaSet`` parameter in the connection string. In the following +example, the hostnames are ``host1``, ``host2``, and ``host3``, and the +port numbers are all ``27017``. The replica set name is ``myRS``. + +.. code-block:: none + + mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS + +When connecting to a replica set, the driver takes the following actions by default: + +- Discovers all replica set members when given the address of any one member. +- Dispatches operations to the appropriate member, such as instructions + to write against the **primary**. + +.. tip:: + + You can specify just one host to connect to a replica set. + However, to ensure connectivity when the specified host + is unavailable, you should provide the full list of hosts. + +To learn more about replication in MongoDB, see the :manual:`Replication ` section of server manual. + +Direct Connection +````````````````` + +To force operations on the host designated in the connection URI, +specify the ``directConnection`` option. Direct connections exhibit the +following behavior: + +- They don't support SRV strings. +- They fail on writes when the specified host is not the **primary**. +- They require you to specify a :manual:`secondary read preference + ` when the + specified host isn't the **primary** node. + +.. note:: Replica Set in Docker + + .. sharedinclude:: dbx/docker-replica-set.rst \ No newline at end of file From 57089bd8d24576300b280b156d12c2eaacd13569 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 5 Jun 2025 11:52:57 -0700 Subject: [PATCH 2/6] update connect landing --- source/connect.txt | 179 +++------------------------------ source/connect/mongoclient.txt | 2 +- 2 files changed, 14 insertions(+), 167 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 5be7092e..c7bfd6d2 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -32,169 +32,16 @@ Connection Guide Overview -------- -In this guide, you can learn how to connect to a MongoDB instance or -replica set deployment by using the {+driver-short+}. - -You can use the {+driver-short+} to connect to deployments hosted in the -following environments: - -.. include:: /includes/fact-environments.rst - -.. _golang-connection-uri: - --------------- -Connection URI --------------- - -A **connection URI**, also known as a connection string, tells the -driver how to connect to MongoDB and how to behave while connected. - -Parts of a Connection URI -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following image explains each part of a sample connection URI: - -.. figure:: /includes/figures/connection_uri_parts.png - :alt: Each part of the connection string - -In this example, we use ``mongodb`` for the protocol, which specifies the -:manual:`Standard Connection String Format -`. -You can also use the :manual:`SRV Connection Format -` if you -want more flexibility of deployment and the ability to change the -servers in rotation without reconfiguring clients. - -The next part of the connection string contains your database username and, if -you are using password-based authentication, your password. Replace the value of -``user`` with your database username and ``pass`` with your password. If you are using an -authentication mechanism that does not require a username and password, omit -this part of the connection URI. - -The next part of the connection string specifies the hostname or IP address and -port of your MongoDB instance. In the preceding example, we use ``sample.host`` -as the hostname and ``27017`` as the port. Replace these values to point to -your MongoDB instance. - -The last part of the connection string specifies connection and authentication -options. In the example, we set two connection options: -``maxPoolSize=20`` and ``w=majority``. To learn more about connection -options, see the :ref:`golang-connection-options` guide. - -Connection Example -~~~~~~~~~~~~~~~~~~ - -To connect to MongoDB, you must create a client. A client manages your -connections and runs database commands. - -.. tip:: Reuse Your Client - - We recommend that you reuse your client across sessions and operations. - You can use the same ``Client`` instance to perform multiple tasks, instead of - creating a new one each time. The ``Client`` type is safe for - concurrent use by multiple `goroutines - `__. - -.. TODO, Add back this line when Connection Pools page is made: To learn more about - how connection pools work in the driver, see the :ref:`Connection Pools guide `. - -You can create a client that uses your connection string and other -client options by passing a ``ClientOptions`` object to the ``Connect()`` -method. - -To specify your connection URI, pass it to the ``ApplyURI()`` -method, which returns a new ``ClientOptions`` instance. To set any other -options, call the relevant helper method from the ``options`` package. - -To learn more about connection options, see the -:ref:`Connection Options section `. To learn -more about creating a client, see the API documentation for `Client -<{+api+}/mongo#Client>`__ and `Connect() <{+api+}/mongo#Connect>`__. - -You can set the {+stable-api+} version as an option to avoid -breaking changes when you upgrade to a new server version. To -learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page -`. - -The following code shows how you can create a client that uses an Atlas -connection string and the {+stable-api+} version, connect to MongoDB, and -verify that the connection is successful: - -.. _go-connection-example-code: - -.. literalinclude:: /includes/fundamentals/code-snippets/srv.go - :language: go - -.. tip:: - - Follow the :ref:`Quick Start guide ` - to retrieve your Atlas connection string. - -.. note:: - - To learn about connecting to Atlas Serverless, see the - :ref:`Serverless Instance Limitations page - ` to identify the minimum driver version - required. - --------------------------------- -Other Ways to Connect to MongoDB --------------------------------- - -If you are connecting to a single MongoDB server instance or replica set -that is not hosted on Atlas, see the following sections to find out how to -connect. - -Connect to a MongoDB Server on Your Local Machine -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/localhost-connection.rst - -To test whether you can connect to your server, replace the connection -string with your localhost connection string in the preceding code example. - -Connect to a Replica Set -~~~~~~~~~~~~~~~~~~~~~~~~ - -A MongoDB replica set deployment is a group of connected instances that -store the same set of data. This configuration provides data -redundancy and high data availability. - -To connect to a replica set deployment, specify the hostname and port numbers -of each instance, separated by commas, and the replica set name as the value -of the ``replicaSet`` parameter in the connection string. In the following -example, the hostnames are ``host1``, ``host2``, and ``host3``, and the -port numbers are all ``27017``. The replica set name is ``myRS``. - -.. code-block:: none - - mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS - -When connecting to a replica set, the driver takes the following actions by default: - -- Discovers all replica set members when given the address of any one member. -- Dispatches operations to the appropriate member, such as instructions - to write against the **primary**. - -.. tip:: - - You can specify just one host to connect to a replica set. - However, to ensure connectivity when the specified host - is unavailable, provide the full list of hosts. - -Direct Connection -````````````````` - -To force operations on the host designated in the connection URI, -specify the ``directConnection`` option. Direct connections exhibit the -following behavior: - -- They don't support SRV strings. -- They fail on writes when the specified host is not the **primary**. -- They require you to specify a :manual:`secondary read preference - ` when the - specified host isn't the **primary** node. - -.. note:: Replica Set in Docker - - .. sharedinclude:: dbx/docker-replica-set.rst +Learn how to set up a connection and specify connection behavior from your +application to a MongoDB deployment using the {+driver-short+} in the following +sections: + +- :ref:`golang-mongoclient`: Create a MongoClient object + to connect to a MongoDB deployment. +- :ref:`golang-connection-options`: Customize the + connection behavior of the MongoClient object. +- :ref:`golang-connection-troubleshooting`: Explore solutions to common + connection issues. + +For more information about authenticating with a MongoDB instance, see the +:ref:`golang-authentication` section. \ No newline at end of file diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 58100522..31cd9e1f 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -178,7 +178,7 @@ When connecting to a replica set, the driver takes the following actions by defa You can specify just one host to connect to a replica set. However, to ensure connectivity when the specified host - is unavailable, you should provide the full list of hosts. + is unavailable, you must provide the full list of hosts. To learn more about replication in MongoDB, see the :manual:`Replication ` section of server manual. From 40f00486d3c819b9ae2c05525f48e1a2eaae7320 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 5 Jun 2025 15:40:30 -0700 Subject: [PATCH 3/6] edits --- source/connect.txt | 6 +++--- source/connect/mongoclient.txt | 7 +++++-- source/includes/fundamentals/code-snippets/srv.go | 8 +++++--- source/includes/localhost-connection.rst | 5 +++-- 4 files changed, 16 insertions(+), 10 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index c7bfd6d2..46533af6 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -38,10 +38,10 @@ sections: - :ref:`golang-mongoclient`: Create a MongoClient object to connect to a MongoDB deployment. -- :ref:`golang-connection-options`: Customize the - connection behavior of the MongoClient object. +- :ref:`golang-connection-options`: Customize the connection behavior of the + MongoClient object. - :ref:`golang-connection-troubleshooting`: Explore solutions to common - connection issues. + connection issues. For more information about authenticating with a MongoDB instance, see the :ref:`golang-authentication` section. \ No newline at end of file diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 31cd9e1f..a0bc6839 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -82,8 +82,8 @@ A standard connection string includes the following components: For more information about creating a connection string, see :manual:`Connection Strings ` in the MongoDB Server documentation. -Atlas Connection Example ------------------------- +Create a Client to Connect to MongoDB Atlas +------------------------------------------- To connect to MongoDB, you must create a client. A client manages your connections and runs database commands. @@ -113,6 +113,9 @@ You can set the {+stable-api+} version as an option to avoid breaking changes when you upgrade to a new server version. To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page `. +Example +~~~~~~~ + The following code shows how you can create a client that uses an Atlas connection string and the {+stable-api+} version, connect to MongoDB, and verify that the connection is successful: diff --git a/source/includes/fundamentals/code-snippets/srv.go b/source/includes/fundamentals/code-snippets/srv.go index b2df50aa..d59478c6 100644 --- a/source/includes/fundamentals/code-snippets/srv.go +++ b/source/includes/fundamentals/code-snippets/srv.go @@ -18,11 +18,13 @@ func main() { log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/") } - // Use the SetServerAPIOptions() method to set the Stable API version to 1 + // Uses the SetServerAPIOptions() method to set the Stable API version to 1 serverAPI := options.ServerAPI(options.ServerAPIVersion1) + + // Defines the options for the MongoDB client opts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI) - // Create a new client and connect to the server + // Creates a new client and connects to the server client, err := mongo.Connect(opts) if err != nil { @@ -34,7 +36,7 @@ func main() { } }() - // Send a ping to confirm a successful connection + // Sends a ping to confirm a successful connection var result bson.M if err := client.Database("admin").RunCommand(context.TODO(), bson.D{{"ping", 1}}).Decode(&result); err != nil { panic(err) diff --git a/source/includes/localhost-connection.rst b/source/includes/localhost-connection.rst index c18be21a..1190077f 100644 --- a/source/includes/localhost-connection.rst +++ b/source/includes/localhost-connection.rst @@ -22,5 +22,6 @@ If your MongoDB Server is running locally, you can use the connection string ``"mongodb://localhost:"`` where ```` is the port number you configured your server to listen for incoming connections. -If you want to specify a different hostname or IP address, see our Server -Manual entry on :manual:`Connection Strings `. \ No newline at end of file +For more information on how to specify a different hostname or IP address, see +:manual:`Connection Strings ` in the server +manual. \ No newline at end of file From f8c386efb2e7d77692b3f907f0d50597f0daf946 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 6 Jun 2025 10:47:25 -0700 Subject: [PATCH 4/6] edits --- source/connect.txt | 8 ++++---- source/connect/mongoclient.txt | 18 +++++++++--------- source/includes/localhost-connection.rst | 8 ++++---- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 46533af6..6b787d05 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -36,10 +36,10 @@ Learn how to set up a connection and specify connection behavior from your application to a MongoDB deployment using the {+driver-short+} in the following sections: -- :ref:`golang-mongoclient`: Create a MongoClient object - to connect to a MongoDB deployment. -- :ref:`golang-connection-options`: Customize the connection behavior of the - MongoClient object. +- :ref:`golang-mongoclient`: Learn how to create a MongoClient object to connect + to a MongoDB deployment. +- :ref:`golang-connection-options`: Learn how to customize your connection + behavior. - :ref:`golang-connection-troubleshooting`: Explore solutions to common connection issues. diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index a0bc6839..149f3eb7 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -104,15 +104,17 @@ To specify your connection URI, pass it to the ``ApplyURI()`` method, which returns a new ``ClientOptions`` instance. To set any other options, call the relevant helper method from the options package. -To learn more about connection options, see the :ref:`Connection Options section -`. To learn more about creating a client, see the API -documentation for `Client <{+api+}/mongo#Client>`__ and `Connect() +To learn more about connection options, see the :ref:`Connection Options +` section. To learn more about creating a client, see +the API documentation for `Client <{+api+}/mongo#Client>`__ and `Connect() <{+api+}/mongo#Connect>`__. You can set the {+stable-api+} version as an option to avoid breaking changes when you upgrade to a new server version. To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page `. +.. _go-connection-example-code: + Example ~~~~~~~ @@ -120,8 +122,6 @@ The following code shows how you can create a client that uses an Atlas connection string and the {+stable-api+} version, connect to MongoDB, and verify that the connection is successful: -.. _go-connection-example-code: - .. literalinclude:: /includes/fundamentals/code-snippets/srv.go :language: go :copyable: @@ -143,7 +143,7 @@ Other Ways to Connect to MongoDB -------------------------------- If you are connecting to a single MongoDB server instance or replica set -that is not hosted on Atlas, see the following sections to find out how to +that is not hosted on Atlas, see the following sections to learn how to connect. Connect to a MongoDB Server on Your Local Machine @@ -151,8 +151,8 @@ Connect to a MongoDB Server on Your Local Machine .. include:: /includes/localhost-connection.rst -To test whether you can connect to your server, replace the connection -string with your localhost connection string in the preceding code example. +To test whether you can connect to your server, replace the connection string +with your localhost connection string in the preceding `code example `. Connect to a Replica Set ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -183,7 +183,7 @@ When connecting to a replica set, the driver takes the following actions by defa However, to ensure connectivity when the specified host is unavailable, you must provide the full list of hosts. -To learn more about replication in MongoDB, see the :manual:`Replication ` section of server manual. +To learn more about replication in MongoDB, see the :manual:`Replication ` section of Server manual. Direct Connection ````````````````` diff --git a/source/includes/localhost-connection.rst b/source/includes/localhost-connection.rst index 1190077f..1f536403 100644 --- a/source/includes/localhost-connection.rst +++ b/source/includes/localhost-connection.rst @@ -11,9 +11,9 @@ purposes, complete the following steps: .. important:: - Always secure your MongoDB server from malicious attacks. See our - :manual:`Security Checklist ` for a - list of security recommendations. + Always secure your MongoDB server from malicious attacks. See the + :manual:`Security Checklist ` in the + Server manual for a list of security recommendations. After you successfully start your MongoDB server, specify your connection string in your driver connection code. @@ -23,5 +23,5 @@ If your MongoDB Server is running locally, you can use the connection string configured your server to listen for incoming connections. For more information on how to specify a different hostname or IP address, see -:manual:`Connection Strings ` in the server +:manual:`Connection Strings ` in the Server manual. \ No newline at end of file From 61acd4739738d0475c251efe62d69fd67c2979a1 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 6 Jun 2025 12:16:10 -0700 Subject: [PATCH 5/6] formatting --- source/connect.txt | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 6b787d05..81615978 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -36,12 +36,9 @@ Learn how to set up a connection and specify connection behavior from your application to a MongoDB deployment using the {+driver-short+} in the following sections: -- :ref:`golang-mongoclient`: Learn how to create a MongoClient object to connect - to a MongoDB deployment. -- :ref:`golang-connection-options`: Learn how to customize your connection - behavior. -- :ref:`golang-connection-troubleshooting`: Explore solutions to common - connection issues. +- :ref:`golang-mongoclient` +- :ref:`golang-connection-options` +- :ref:`golang-connection-troubleshooting` For more information about authenticating with a MongoDB instance, see the :ref:`golang-authentication` section. \ No newline at end of file From 056cac80164c252f2e4e4cf812c53ded6a1f0523 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 6 Jun 2025 14:40:52 -0700 Subject: [PATCH 6/6] shift content for info flow --- source/connect/mongoclient.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 149f3eb7..f674c3b3 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -88,6 +88,13 @@ Create a Client to Connect to MongoDB Atlas To connect to MongoDB, you must create a client. A client manages your connections and runs database commands. +You can create a client that uses your connection string and other client +options by passing a ``ClientOptions`` object to the ``Connect()`` method. + +To specify your connection URI, pass it to the ``ApplyURI()`` method, which +returns a new ``ClientOptions`` instance. To set any other options, call the +relevant helper method from the options package. + .. tip:: Reuse Your Client We recommend that you reuse your client across sessions and operations. You @@ -97,13 +104,6 @@ connections and runs database commands. about how connection pools work in the driver, see the :ref:`golang-connection-pools` guide. -You can create a client that uses your connection string and other client -options by passing a ``ClientOptions`` object to the ``Connect()`` method. - -To specify your connection URI, pass it to the ``ApplyURI()`` method, which -returns a new ``ClientOptions`` instance. To set any other options, call the -relevant helper method from the options package. - To learn more about connection options, see the :ref:`Connection Options ` section. To learn more about creating a client, see the API documentation for `Client <{+api+}/mongo#Client>`__ and `Connect() @@ -119,7 +119,7 @@ Example ~~~~~~~ The following code shows how you can create a client that uses an Atlas -connection string and the {+stable-api+} version, connect to MongoDB, and verify +connection string and the {+stable-api+} version, connects to MongoDB, and verifies that the connection is successful: .. literalinclude:: /includes/fundamentals/code-snippets/srv.go