Skip to content

Commit 8cac163

Browse files
stephmarie17stephmarie17
authored
DOCSP-49621 Customize cluster settings (#522)
1 parent 0c05c2c commit 8cac163

File tree

7 files changed

+263
-8
lines changed

7 files changed

+263
-8
lines changed

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

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
.. _golang-cluster-settings:
2+
3+
==========================
4+
Customize Cluster Settings
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code example, connection string, connection options
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how the {+driver-short+} manages clusters and how
24+
to customize the cluster settings.
25+
26+
Specify Settings
27+
----------------
28+
29+
You can specify settings for your clusters by using either a connection string
30+
or a ``ClientOptions`` struct when creating a new ``Client``
31+
instance. Select the :guilabel:`Connection String` or :guilabel:`ClientOptions` tab to see the
32+
available options.
33+
34+
.. tabs::
35+
36+
.. tab:: Connection String
37+
:tabid: uri
38+
39+
The following table describes the parameters you can use in your connection
40+
string to modify the driver's behavior when interacting with your MongoDB
41+
cluster:
42+
43+
.. list-table::
44+
:header-rows: 1
45+
:stub-columns: 1
46+
:widths: 40 60
47+
48+
* - Parameter
49+
- Description
50+
51+
* - ``serverSelectionTimeoutMS``
52+
- Specifies the maximum amount of time the driver will wait for a server to
53+
be available before throwing an error.
54+
55+
*Default:* 30 seconds
56+
57+
* - ``localThresholdMS``
58+
- Specifies the maximum latency in milliseconds for selecting a server.
59+
60+
*Default:* 15 milliseconds
61+
62+
* - ``replicaSet``
63+
- Specifies the name of the replica set to connect to.
64+
65+
* - ``directConnection``
66+
- Specifies whether to connect directly to a single server, bypassing the
67+
replica set or sharded cluster.
68+
69+
*Default:* ``false``
70+
71+
* - ``loadBalanced``
72+
- Specifies whether the driver is connecting to MongoDB using a
73+
load balancer.
74+
75+
*Default:* ``false``
76+
77+
* - ``srvServiceName``
78+
- Specifies the service name of the `SRV resource records
79+
<https://www.rfc-editor.org/rfc/rfc2782>`__ the driver retrieves to
80+
construct your :manual:`seed list
81+
</reference/glossary/#std-term-seed-list>`. You must use the
82+
:manual:`DNS Seed List Connection Format
83+
</reference/connection-string/#srv-connection-format>` in
84+
your connection string to use this option.
85+
86+
.. tab:: ClientOptions
87+
:tabid: options
88+
89+
The following table describes several methods you can chain to your
90+
``ClientOptions`` struct to modify the driver's behavior:
91+
92+
.. list-table::
93+
:header-rows: 1
94+
:stub-columns: 1
95+
:widths: 40 60
96+
97+
* - Method
98+
- Description
99+
100+
* - ``SetServerSelectionTimeout()``
101+
- Specifies the maximum amount of time the driver will wait for a server to
102+
be available before throwing an error.
103+
104+
*Default:* 30 seconds
105+
106+
* - ``SetLocalThreshold()``
107+
- Specifies the maximum latency in milliseconds for selecting a server.
108+
109+
*Default:* 15 milliseconds
110+
111+
* - ``SetReplicaSet()``
112+
- Specifies the name of the replica set to connect to.
113+
114+
* - ``SetDirect()``
115+
- Specifies whether to connect directly to a single server, bypassing the
116+
replica set or sharded cluster.
117+
118+
*Default:* ``false``
119+
120+
* - ``SetLoadBalanced()``
121+
- Specifies whether the driver is connecting to MongoDB using a
122+
load balancer.
123+
124+
*Default:* ``false``
125+
126+
* - ``SetSRVServiceName()``
127+
- Specifies a custom service name of the `SRV resource records
128+
<https://www.rfc-editor.org/rfc/rfc2782>`__ the driver retrieves to
129+
construct your :manual:`seed list
130+
</reference/glossary/#std-term-seed-list>`. To use a custom SRV
131+
service name in SRV discovery, you must call this function before you
132+
call ``ApplyURI()``.
133+
134+
To learn more about the available methods, see the :ref:`golang-cluster-settings-resources` section.
135+
136+
Example
137+
~~~~~~~
138+
139+
Select the :guilabel:`Connection String` or :guilabel:`ClientOptions` tab to
140+
see the corresponding example:
141+
142+
.. tabs::
143+
144+
.. tab:: Connection String
145+
:tabid: uriExample
146+
147+
The following code uses the connection string to configure the maximum
148+
server selection timeout to 10 seconds and the local threshold to 20
149+
milliseconds:
150+
151+
.. literalinclude:: /includes/connect/cluster-settings-uri.go
152+
:language: go
153+
:start-after: start-uri-variable
154+
:end-before: end-uri-variable
155+
:dedent:
156+
157+
The following code creates a client and passes the connection string to the
158+
``ApplyURI()`` method:
159+
160+
.. literalinclude:: /includes/connect/cluster-settings-uri.go
161+
:language: go
162+
:start-after: start-apply-uri
163+
:end-before: end-apply-uri
164+
:dedent:
165+
166+
.. tab:: ClientOptions
167+
:tabid: optionsExample
168+
169+
The following code creates a client and sets the cluster options with a
170+
maximum server selection timeout of 10 seconds and a local threshold of
171+
20 milliseconds:
172+
173+
.. literalinclude:: /includes/connect/cluster-settings-client-options.go
174+
:language: go
175+
:start-after: start-client-options
176+
:end-before: end-client-options
177+
:dedent:
178+
179+
.. _golang-cluster-settings-resources:
180+
181+
API Documentation
182+
-----------------
183+
184+
To learn more about the methods and types in this guide, see the following API documentation:
185+
186+
- `Client <{+api+}/mongo#Client>`__
187+
- `ClientOptions <{+api+}/mongo/options#ClientOptions>`__
188+
- `ApplyURI() <{+api+}/mongo/options#ClientOptions.ApplyURI>`__

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Configure a Connection Pool
6060
You can specify settings for your connection pool either by using a connection
6161
string or by using the ``options.Client`` methods.
6262

63-
Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
63+
Select the :guilabel:`Connection String` or :guilabel:`ClientOptions` tab to
6464
see the corresponding syntax:
6565

6666
.. tabs::
@@ -159,7 +159,7 @@ see the corresponding syntax:
159159
Example
160160
~~~~~~~
161161

162-
Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
162+
Select the :guilabel:`Connection String` or :guilabel:`ClientOptions` tab to
163163
see the corresponding example:
164164

165165
.. tabs::

‎source/connect/connection-options/server-selection.txt‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎source/connect/specify-connection-options.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Specify Connection Options
2323

2424
Specify Connection Options <connect/connection-options/specify-connection-options>
2525
Compress Network Traffic <connect/connection-options/network-compression>
26-
Customize Server Selection <connect/connection-options/server-selection>
26+
Customize Cluster Settings <connect/connection-options/cluster-settings>
2727
Stable API <connect/connection-options/stable-api>
2828
Limit Server Execution Time <connect/connection-options/csot>
2929
Connection Pools <connect/connection-options/connection-pools>

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"log"
6+
"os"
7+
"time"
8+
9+
"go.mongodb.org/mongo-driver/v2/mongo"
10+
"go.mongodb.org/mongo-driver/v2/mongo/options"
11+
)
12+
13+
func main() {
14+
uri := os.Getenv("MONGODB_URI")
15+
if uri == "" {
16+
log.Fatal("Set your 'MONGODB_URI' environment variable.")
17+
}
18+
19+
// Sets client options with cluster settings
20+
// start-client-options
21+
clientOptions := options.Client().
22+
ApplyURI(uri).
23+
SetServerSelectionTimeout(10 * time.Second).
24+
SetLocalThreshold(20 * time.Millisecond)
25+
26+
client, err := mongo.Connect(clientOptions)
27+
if err != nil {
28+
log.Fatal(err)
29+
}
30+
// end-client-options
31+
32+
defer func() {
33+
if err = client.Disconnect(context.TODO()); err != nil {
34+
log.Fatal(err)
35+
}
36+
}()
37+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"fmt"
6+
"log"
7+
8+
"go.mongodb.org/mongo-driver/v2/mongo"
9+
"go.mongodb.org/mongo-driver/v2/mongo/options"
10+
)
11+
12+
// Connection string with cluster settings options
13+
// start-uri-variable
14+
const uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=20"
15+
16+
// end-uri-variable
17+
18+
func main() {
19+
// Creates a new client and connects to the server
20+
// start-apply-uri
21+
client, err := mongo.Connect(options.Client().ApplyURI(uri))
22+
if err != nil {
23+
log.Fatal(err)
24+
}
25+
// end-apply-uri
26+
27+
fmt.Println("Connected to MongoDB with cluster settings options")
28+
defer func() {
29+
if err = client.Disconnect(context.TODO()); err != nil {
30+
log.Fatal(err)
31+
}
32+
}()
33+
}

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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,12 @@ import (
1010

1111
// start-uri-variable
1212
// Connection string with connection pool options
13-
const (
14-
uri = "mongodb://localhost:27017/?maxPoolSize=50&minPoolSize=10&maxIdleTimeMS=30000"
15-
)
13+
const uri = "mongodb://localhost:27017/?maxPoolSize=50&minPoolSize=10&maxIdleTimeMS=30000"
1614

1715
// end-uri-variable
1816
func main() {
1917
// start-apply-uri
20-
// Creates a new client and connect to the server
18+
// Creates a new client and connects to the server
2119
client, err := mongo.Connect(options.Client().ApplyURI(uri))
2220
if err != nil {
2321
log.Fatal(err)

0 commit comments

Comments
 (0)