DOCSP-49621 Customize cluster settings

source/connect/connection-options/cluster-settings.txt

@@ -0,0 +1,188 @@
+.. _golang-cluster-settings:
+
+==========================
+Customize Cluster Settings
+==========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, connection string, connection options
+
+Overview
+--------
+
+In this guide, you can learn how the {+driver-short+} manages clusters and how
+to customize the cluster settings.
+
+Specify Settings
+----------------
+
+You can specify settings for your clusters by using either a connection string
+or a ``ClientOptions`` struct when creating a new ``Client``
+instance. Select the :guilabel:`Connection String` or :guilabel:`ClientOptions` tab to see the
+available options.
+
+.. tabs::
+
+  .. tab:: Connection String
+    :tabid: uri
+
+    The following table describes the parameters you can use in your connection
+    string to modify the driver's behavior when interacting with your MongoDB
+    cluster:
+
+    .. list-table::
+       :header-rows: 1
+       :stub-columns: 1
+       :widths: 40 60
+
+       * - Parameter
+         - Description 
+
+       * - ``serverSelectionTimeoutMS``
+         - Specifies the maximum amount of time the driver will wait for a server to
+           be available before throwing an error.
+
+           *Default:* 30 seconds
+
+       * - ``localThresholdMS``
+         - Specifies the maximum latency in milliseconds for selecting a server.
+
+           *Default:* 15 milliseconds
+
+       * - ``replicaSet``
+         - Specifies the name of the replica set to connect to.
+
+       * - ``directConnection``
+         - Specifies whether to connect directly to a single server, bypassing the
+           replica set or sharded cluster.
+
+           *Default:* ``false``
+
+       * - ``loadBalanced``
+         - Specifies whether the driver is connecting to MongoDB using a
+           load balancer.
+
+           *Default:* ``false``
+
+       * - ``srvServiceName``
+         - Specifies the service name of the `SRV resource records
+           <https://www.rfc-editor.org/rfc/rfc2782>`__ the driver retrieves to
+           construct your :manual:`seed list
+           </reference/glossary/#std-term-seed-list>`. You must use the
+           :manual:`DNS Seed List Connection Format
+           </reference/connection-string/#srv-connection-format>` in
+           your connection string to use this option.
+
+  .. tab:: ClientOptions
+    :tabid: options
+
+    The following table describes several methods you can chain to your
+    ``ClientOptions`` struct to modify the driver's behavior:
+
+    .. list-table::
+       :header-rows: 1
+       :stub-columns: 1
+       :widths: 40 60
+
+       * - Method
+         - Description 
+
+       * - ``SetServerSelectionTimeout()``
+         - Specifies the maximum amount of time the driver will wait for a server to
+           be available before throwing an error.
+
+           *Default:* 30 seconds
+
+       * - ``SetLocalThreshold()``
+         - Specifies the maximum latency in milliseconds for selecting a server.
+
+           *Default:* 15 milliseconds
+
+       * - ``SetReplicaSet()``
+         - Specifies the name of the replica set to connect to.
+
+       * - ``SetDirect()``
+         - Specifies whether to connect directly to a single server, bypassing the
+           replica set or sharded cluster.
+
+           *Default:* ``false``
+
+       * - ``SetLoadBalanced()``
+         - Specifies whether the driver is connecting to MongoDB using a
+           load balancer.
+
+           *Default:* ``false``
+
+       * - ``SetSRVServiceName()``
+         - Specifies a custom service name of the `SRV resource records
+           <https://www.rfc-editor.org/rfc/rfc2782>`__ the driver retrieves to
+           construct your :manual:`seed list
+           </reference/glossary/#std-term-seed-list>`. To use a custom SRV
+           service name in SRV discovery, you must call this function before you
+           call ``ApplyURI()``.
+
+    To learn more about the available methods, see the :ref:`golang-cluster-settings-resources` section.
+
+Example
+~~~~~~~
+
+Select the :guilabel:`Connection String` or :guilabel:`ClientOptions`  tab to
+see the corresponding example:
+
+.. tabs::
+
+    .. tab:: Connection String
+      :tabid: uriExample
+
+      The following code uses the connection string to configure the maximum
+      server selection timeout to 10 seconds and the local threshold to 20
+      milliseconds:
+
+      .. literalinclude:: /includes/connect/cluster-settings-uri.go
+        :language: go
+        :start-after: start-uri-variable
+        :end-before: end-uri-variable
+        :dedent:
+
+      The following code creates a client and passes the connection string to the
+      ``ApplyURI()`` method:
+
+      .. literalinclude:: /includes/connect/cluster-settings-uri.go
+        :language: go
+        :start-after: start-apply-uri
+        :end-before: end-apply-uri
+        :dedent:
+
+    .. tab:: ClientOptions
+      :tabid: optionsExample
+
+      The following code creates a client and sets the cluster options with a
+      maximum server selection timeout of 10 seconds and a local threshold of
+      20 milliseconds:
+
+      .. literalinclude:: /includes/connect/cluster-settings-client-options.go
+        :language: go
+        :start-after: start-client-options
+        :end-before: end-client-options
+        :dedent:
+
+.. _golang-cluster-settings-resources:
+
+API Documentation
+-----------------
+
+To learn more about the methods and types in this guide, see the following API documentation:
+
+- `Client <{+api+}/mongo#Client>`__
+- `ClientOptions <{+api+}/mongo/options#ClientOptions>`__
+- `ApplyURI() <{+api+}/mongo/options#ClientOptions.ApplyURI>`__

source/connect/connection-options/connection-pools.txt

@@ -60,7 +60,7 @@ Configure a Connection Pool
 You can specify settings for your connection pool either by using a connection
 string or by using the ``options.Client`` methods.
 
-Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings`  tab to
+Select the :guilabel:`Connection String` or :guilabel:`ClientOptions`  tab to
 see the corresponding syntax:
 
 .. tabs::
@@ -159,7 +159,7 @@ see the corresponding syntax:
 Example
 ~~~~~~~
 
-Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings`  tab to
+Select the :guilabel:`Connection String` or :guilabel:`ClientOptions`  tab to
 see the corresponding example:
 
 .. tabs::

source/connect/specify-connection-options.txt

@@ -23,7 +23,7 @@ Specify Connection Options
 
    Specify Connection Options <connect/connection-options/specify-connection-options>
    Compress Network Traffic <connect/connection-options/network-compression>
-   Customize Server Selection <connect/connection-options/server-selection>
+   Customize Cluster Settings <connect/connection-options/cluster-settings>
    Stable API <connect/connection-options/stable-api>
    Limit Server Execution Time <connect/connection-options/csot>
    Connection Pools <connect/connection-options/connection-pools>

source/includes/connect/cluster-settings-client-options.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+	"time"
+
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func main() {
+	uri := os.Getenv("MONGODB_URI")
+	if uri == "" {
+		log.Fatal("Set your 'MONGODB_URI' environment variable.")
+	}
+
+	// Sets client options with cluster settings
+	// start-client-options
+	clientOptions := options.Client().
+		ApplyURI(uri).
+		SetServerSelectionTimeout(10 * time.Second).
+		SetLocalThreshold(20 * time.Millisecond)
+
+	client, err := mongo.Connect(clientOptions)
+	if err != nil {
+		log.Fatal(err)
+	}
+	// end-client-options
+
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			log.Fatal(err)
+		}
+	}()
+}

source/includes/connect/cluster-settings-uri.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+// Connection string with cluster settings options
+// start-uri-variable
+const uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=20"
+
+// end-uri-variable
+
+func main() {
+	// Creates a new client and connects to the server
+	// start-apply-uri
+	client, err := mongo.Connect(options.Client().ApplyURI(uri))
+	if err != nil {
+		log.Fatal(err)
+	}
+	// end-apply-uri
+
+	fmt.Println("Connected to MongoDB with cluster settings options")
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			log.Fatal(err)
+		}
+	}()
+}

source/includes/connect/connection-pools-uri.go

@@ -10,14 +10,12 @@ import (
 
 // start-uri-variable
 // Connection string with connection pool options
-const (
-	uri = "mongodb://localhost:27017/?maxPoolSize=50&minPoolSize=10&maxIdleTimeMS=30000"
-)
+const uri = "mongodb://localhost:27017/?maxPoolSize=50&minPoolSize=10&maxIdleTimeMS=30000"
 
 // end-uri-variable
 func main() {
 	// start-apply-uri
-	// Creates a new client and connect to the server
+	// Creates a new client and connects to the server
 	client, err := mongo.Connect(options.Client().ApplyURI(uri))
 	if err != nil {
 		log.Fatal(err)