Skip to content

Commit 6b4b1f8

Browse files
stephmarie17stephmarie17
committed
create guide and code examples
1 parent a1e8e81 commit 6b4b1f8

File tree

5 files changed

+261
-4
lines changed

5 files changed

+261
-4
lines changed

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

‎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+
// start-client-options
19+
// Sets client options with cluster settings
20+
clientOptions := options.Client().
21+
ApplyURI(uri).
22+
SetServerSelectionTimeout(10 * time.Second).
23+
SetLocalThreshold(15 * time.Millisecond)
24+
25+
// Creates a new client and connects to the server
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: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
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+
// start-uri-variable
13+
// Connection string with cluster settings options
14+
const (
15+
uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=10000&localThresholdMS=15"
16+
)
17+
18+
// end-uri-variable
19+
20+
func main() {
21+
// start-apply-uri
22+
// Creates a new client and connects to the server
23+
client, err := mongo.Connect(options.Client().ApplyURI(uri))
24+
if err != nil {
25+
log.Fatal(err)
26+
}
27+
// end-apply-uri
28+
29+
fmt.Println("Connected to MongoDB with cluster settings options")
30+
defer func() {
31+
if err = client.Disconnect(context.TODO()); err != nil {
32+
log.Fatal(err)
33+
}
34+
}()
35+
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ const (
1717
// end-uri-variable
1818
func main() {
1919
// start-apply-uri
20-
// Creates a new client and connect to the server
20+
// Creates a new client and connects to the server
2121
client, err := mongo.Connect(options.Client().ApplyURI(uri))
2222
if err != nil {
2323
log.Fatal(err)

0 commit comments

Comments
 (0)