From 6b4b1f8aabc31c895196e970a35557029675a703 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 18 Jun 2025 11:26:30 -0700 Subject: [PATCH 1/8] create guide and code examples --- .../connection-options/connection-pools.txt | 4 +- .../connection-options/server-selection.txt | 187 +++++++++++++++++- .../cluster-settings-client-options.go | 37 ++++ .../includes/connect/cluster-settings-uri.go | 35 ++++ .../includes/connect/connection-pools-uri.go | 2 +- 5 files changed, 261 insertions(+), 4 deletions(-) create mode 100644 source/includes/connect/cluster-settings-client-options.go create mode 100644 source/includes/connect/cluster-settings-uri.go diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 1da14558..b246d2e6 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/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:: diff --git a/source/connect/connection-options/server-selection.txt b/source/connect/connection-options/server-selection.txt index ac55fa3e..f8a38d81 100644 --- a/source/connect/connection-options/server-selection.txt +++ b/source/connect/connection-options/server-selection.txt @@ -1 +1,186 @@ -.. TODO \ No newline at end of file +.. _golang-server-selection: + +========================== +Customize Cluster Settings +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, read preference, write + +Overview +-------- + +In this guide, you can learn how the {+driver-short+} manages clusters. + +Specify Settings +---------------- + +You can specify settings for your clusters by using either a connection string +or by using the ``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 + + You can use the following parameters 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 + + * - Method + - 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 or not the driver is connecting to MongoDB using a + load balancer. + + *Default:* ``false`` + + * - ``srvServiceName`` + - Specifies the service name of the `SRV resource records + `__ the driver retrieves to + construct your :manual:`seed list + `. You must use the + :manual:`DNS Seed List Connection Format + ` in + your connection string to use this option. + + .. tab:: ClientOptions + :tabid: options + + The following table describes some of the methods you can chain to your settings to + modify the driver's behavior: + + .. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 40 60 + + * - Field + - 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 or not the driver is connecting to MongoDB using a + load balancer. + + *Default:* ``false`` + + * - ``SetSRVServiceName()`` + - Specifies a custom service name of the `SRV resource records + `__ the driver retrieves to + construct your :manual:`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-server-selection-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 15 + 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 + 15 milliseconds: + + .. literalinclude:: /includes/connect/cluster-settings-client-options.go + :language: go + :start-after: start-client-options + :end-before: end-client-options + :dedent: + +.. _golang-server-selection-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>`__ \ No newline at end of file diff --git a/source/includes/connect/cluster-settings-client-options.go b/source/includes/connect/cluster-settings-client-options.go new file mode 100644 index 00000000..69f810e7 --- /dev/null +++ b/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.") + } + // start-client-options + // Sets client options with cluster settings + clientOptions := options.Client(). + ApplyURI(uri). + SetServerSelectionTimeout(10 * time.Second). + SetLocalThreshold(15 * time.Millisecond) + + // Creates a new client and connects to the server + 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) + } + }() +} diff --git a/source/includes/connect/cluster-settings-uri.go b/source/includes/connect/cluster-settings-uri.go new file mode 100644 index 00000000..7d4632d9 --- /dev/null +++ b/source/includes/connect/cluster-settings-uri.go @@ -0,0 +1,35 @@ +package main + +import ( + "context" + "fmt" + "log" + + "go.mongodb.org/mongo-driver/v2/mongo" + "go.mongodb.org/mongo-driver/v2/mongo/options" +) + +// start-uri-variable +// Connection string with cluster settings options +const ( + uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=15" +) + +// end-uri-variable + +func main() { + // start-apply-uri + // Creates a new client and connects to the server + 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) + } + }() +} diff --git a/source/includes/connect/connection-pools-uri.go b/source/includes/connect/connection-pools-uri.go index 7ae0da32..e41cafb4 100644 --- a/source/includes/connect/connection-pools-uri.go +++ b/source/includes/connect/connection-pools-uri.go @@ -17,7 +17,7 @@ const ( // 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) From a8504afb0f330cfabaf42a83dadda2a4d204ea6c Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 23 Jun 2025 09:32:51 -0700 Subject: [PATCH 2/8] update toc and overview --- .../{server-selection.txt => cluster-settings.txt} | 9 +++++---- source/connect/specify-connection-options.txt | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) rename source/connect/connection-options/{server-selection.txt => cluster-settings.txt} (97%) diff --git a/source/connect/connection-options/server-selection.txt b/source/connect/connection-options/cluster-settings.txt similarity index 97% rename from source/connect/connection-options/server-selection.txt rename to source/connect/connection-options/cluster-settings.txt index f8a38d81..7389c89d 100644 --- a/source/connect/connection-options/server-selection.txt +++ b/source/connect/connection-options/cluster-settings.txt @@ -1,4 +1,4 @@ -.. _golang-server-selection: +.. _golang-cluster-settings: ========================== Customize Cluster Settings @@ -20,7 +20,8 @@ Customize Cluster Settings Overview -------- -In this guide, you can learn how the {+driver-short+} manages clusters. +In this guide, you can learn how the {+driver-short+} manages clusters and how +to customize the cluster settings. Specify Settings ---------------- @@ -129,7 +130,7 @@ available options. 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-server-selection-resources` section. + To learn more about the available methods, see the :ref:`golang-cluster-settings-resources` section. Example ~~~~~~~ @@ -174,7 +175,7 @@ see the corresponding example: :end-before: end-client-options :dedent: -.. _golang-server-selection-resources: +.. _golang-cluster-settings-resources: API Documentation ----------------- diff --git a/source/connect/specify-connection-options.txt b/source/connect/specify-connection-options.txt index 06cb5452..f02937a7 100644 --- a/source/connect/specify-connection-options.txt +++ b/source/connect/specify-connection-options.txt @@ -23,7 +23,7 @@ Specify Connection Options Specify Connection Options Compress Network Traffic - Customize Server Selection + Customize Cluster Settings Stable API Limit Server Execution Time Connection Pools From b163e7781a1f264a77b067298968bc4f8d8a237e Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 23 Jun 2025 09:41:19 -0700 Subject: [PATCH 3/8] vale fixes --- source/connect/connection-options/cluster-settings.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-options/cluster-settings.txt b/source/connect/connection-options/cluster-settings.txt index 7389c89d..c1a2abbe 100644 --- a/source/connect/connection-options/cluster-settings.txt +++ b/source/connect/connection-options/cluster-settings.txt @@ -68,7 +68,7 @@ available options. *Default:* ``false`` * - ``loadBalanced`` - - Specifies whether or not the driver is connecting to MongoDB using a + - Specifies whether the driver is connecting to MongoDB using a load balancer. *Default:* ``false`` @@ -85,7 +85,7 @@ available options. .. tab:: ClientOptions :tabid: options - The following table describes some of the methods you can chain to your settings to + The following table describes several methods you can chain to your settings to modify the driver's behavior: .. list-table:: @@ -117,7 +117,7 @@ available options. *Default:* ``false`` * - ``SetLoadBalanced()`` - - Specifies whether or not the driver is connecting to MongoDB using a + - Specifies whether the driver is connecting to MongoDB using a load balancer. *Default:* ``false`` From 2ecbf24677f3921624a52d72e6f8d82ecac3209a Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 23 Jun 2025 09:48:22 -0700 Subject: [PATCH 4/8] edits --- source/connect/connection-options/cluster-settings.txt | 6 +++--- source/includes/connect/cluster-settings-client-options.go | 2 +- source/includes/connect/cluster-settings-uri.go | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connect/connection-options/cluster-settings.txt b/source/connect/connection-options/cluster-settings.txt index c1a2abbe..79b2ebe4 100644 --- a/source/connect/connection-options/cluster-settings.txt +++ b/source/connect/connection-options/cluster-settings.txt @@ -7,7 +7,7 @@ Customize Cluster Settings .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol .. facet:: @@ -144,7 +144,7 @@ see the corresponding example: :tabid: uriExample The following code uses the connection string to configure the maximum - server selection timeout to 10 seconds and the local threshold to 15 + server selection timeout to 10 seconds and the local threshold to 20 milliseconds: .. literalinclude:: /includes/connect/cluster-settings-uri.go @@ -167,7 +167,7 @@ see the corresponding example: 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 - 15 milliseconds: + 20 milliseconds: .. literalinclude:: /includes/connect/cluster-settings-client-options.go :language: go diff --git a/source/includes/connect/cluster-settings-client-options.go b/source/includes/connect/cluster-settings-client-options.go index 69f810e7..6ab25ed2 100644 --- a/source/includes/connect/cluster-settings-client-options.go +++ b/source/includes/connect/cluster-settings-client-options.go @@ -20,7 +20,7 @@ func main() { clientOptions := options.Client(). ApplyURI(uri). SetServerSelectionTimeout(10 * time.Second). - SetLocalThreshold(15 * time.Millisecond) + SetLocalThreshold(20 * time.Millisecond) // Creates a new client and connects to the server client, err := mongo.Connect(clientOptions) diff --git a/source/includes/connect/cluster-settings-uri.go b/source/includes/connect/cluster-settings-uri.go index 7d4632d9..f528c04e 100644 --- a/source/includes/connect/cluster-settings-uri.go +++ b/source/includes/connect/cluster-settings-uri.go @@ -12,7 +12,7 @@ import ( // start-uri-variable // Connection string with cluster settings options const ( - uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=15" + uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=20" ) // end-uri-variable From a8c3163817beefe9394184b44ea2d1d94b4bd081 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 30 Jun 2025 09:42:11 -0700 Subject: [PATCH 5/8] nr feedback --- source/connect/connection-options/cluster-settings.txt | 9 +++++---- .../includes/connect/cluster-settings-client-options.go | 4 ++-- source/includes/connect/cluster-settings-uri.go | 4 ++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/source/connect/connection-options/cluster-settings.txt b/source/connect/connection-options/cluster-settings.txt index 79b2ebe4..d7ae3c91 100644 --- a/source/connect/connection-options/cluster-settings.txt +++ b/source/connect/connection-options/cluster-settings.txt @@ -27,7 +27,7 @@ Specify Settings ---------------- You can specify settings for your clusters by using either a connection string -or by using the ``ClientOptions`` struct when creating a new ``Client`` +or a ``ClientOptions`` struct when creating a new ``Client`` instance. Select the :guilabel:`Connection String` or :guilabel:`ClientOptions` tab to see the available options. @@ -36,8 +36,9 @@ available options. .. tab:: Connection String :tabid: uri - You can use the following parameters in your connection string to modify the - driver's behavior when interacting with your MongoDB cluster: + 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 @@ -79,7 +80,7 @@ available options. construct your :manual:`seed list `. You must use the :manual:`DNS Seed List Connection Format - ` in + ` in your connection string to use this option. .. tab:: ClientOptions diff --git a/source/includes/connect/cluster-settings-client-options.go b/source/includes/connect/cluster-settings-client-options.go index 6ab25ed2..6975db6b 100644 --- a/source/includes/connect/cluster-settings-client-options.go +++ b/source/includes/connect/cluster-settings-client-options.go @@ -15,14 +15,14 @@ func main() { if uri == "" { log.Fatal("Set your 'MONGODB_URI' environment variable.") } - // start-client-options + // Sets client options with cluster settings + // start-client-options clientOptions := options.Client(). ApplyURI(uri). SetServerSelectionTimeout(10 * time.Second). SetLocalThreshold(20 * time.Millisecond) - // Creates a new client and connects to the server client, err := mongo.Connect(clientOptions) if err != nil { log.Fatal(err) diff --git a/source/includes/connect/cluster-settings-uri.go b/source/includes/connect/cluster-settings-uri.go index f528c04e..88a75f4d 100644 --- a/source/includes/connect/cluster-settings-uri.go +++ b/source/includes/connect/cluster-settings-uri.go @@ -9,8 +9,8 @@ import ( "go.mongodb.org/mongo-driver/v2/mongo/options" ) -// start-uri-variable // Connection string with cluster settings options +// start-uri-variable const ( uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=20" ) @@ -18,8 +18,8 @@ const ( // end-uri-variable func main() { - // start-apply-uri // 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) From 9f5ec4713d1abe6accec2e5259b5e9e1275ac1a9 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Mon, 30 Jun 2025 11:04:05 -0700 Subject: [PATCH 6/8] fix url typo --- source/connect/connection-options/cluster-settings.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-options/cluster-settings.txt b/source/connect/connection-options/cluster-settings.txt index d7ae3c91..683dc667 100644 --- a/source/connect/connection-options/cluster-settings.txt +++ b/source/connect/connection-options/cluster-settings.txt @@ -80,7 +80,7 @@ available options. construct your :manual:`seed list `. You must use the :manual:`DNS Seed List Connection Format - ` in + ` in your connection string to use this option. .. tab:: ClientOptions From f86117ed43eebc3a3154026569c1e262c04c3494 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 1 Jul 2025 14:23:54 -0700 Subject: [PATCH 7/8] nr feedback --- source/connect/connection-options/cluster-settings.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connect/connection-options/cluster-settings.txt b/source/connect/connection-options/cluster-settings.txt index 683dc667..611bb21f 100644 --- a/source/connect/connection-options/cluster-settings.txt +++ b/source/connect/connection-options/cluster-settings.txt @@ -15,7 +15,7 @@ Customize Cluster Settings :values: reference .. meta:: - :keywords: code example, read preference, write + :keywords: code example, connection string, connection options Overview -------- @@ -45,7 +45,7 @@ available options. :stub-columns: 1 :widths: 40 60 - * - Method + * - Parameter - Description * - ``serverSelectionTimeoutMS`` @@ -86,15 +86,15 @@ available options. .. tab:: ClientOptions :tabid: options - The following table describes several methods you can chain to your settings to - modify the driver's behavior: + 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 - * - Field + * - Method - Description * - ``SetServerSelectionTimeout()`` From be26ae9b41c2dc3ecbed244271e998d6a50116f5 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 2 Jul 2025 09:49:00 -0700 Subject: [PATCH 8/8] tech feedback --- source/includes/connect/cluster-settings-uri.go | 4 +--- source/includes/connect/connection-pools-uri.go | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/source/includes/connect/cluster-settings-uri.go b/source/includes/connect/cluster-settings-uri.go index 88a75f4d..1081a5b1 100644 --- a/source/includes/connect/cluster-settings-uri.go +++ b/source/includes/connect/cluster-settings-uri.go @@ -11,9 +11,7 @@ import ( // Connection string with cluster settings options // start-uri-variable -const ( - uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=20" -) +const uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=20" // end-uri-variable diff --git a/source/includes/connect/connection-pools-uri.go b/source/includes/connect/connection-pools-uri.go index e41cafb4..8757ddf2 100644 --- a/source/includes/connect/connection-pools-uri.go +++ b/source/includes/connect/connection-pools-uri.go @@ -10,9 +10,7 @@ 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() {