Skip to content

Commit 57ce697

Browse files
rustagirrustagir
authored
Merge pull request #13 from rustagir/DOCSP-13828-connection-guide
DOCSP 13828: connection guide
2 parents ee58058 + 79551cb commit 57ce697

File tree

6 files changed

+270
-10
lines changed

6 files changed

+270
-10
lines changed

‎source/fundamentals.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ Fundamentals
88
:titlesonly:
99
:maxdepth: 1
1010

11-
/fundamentals/auth
12-
13-
11+
/fundamentals/connection
12+
/fundamentals/auth
13+
14+
1415
..
15-
/fundamentals/connection
1616
/fundamentals/enterprise-auth
1717
/fundamentals/databases-collections
1818
/fundamentals/data-formats

‎source/fundamentals/connection.txt

Lines changed: 201 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,211 @@ Connection Guide
44

55
.. default-domain:: mongodb
66

7-
.. toctree::
8-
9-
/fundamentals/connection/tls
10-
/fundamentals/connection/jndi
11-
127
.. contents:: On this page
138
:local:
149
:backlinks: none
1510
:depth: 2
1611
:class: singlecol
1712

1813
This guide shows you how to connect to a MongoDB instance or replica set
19-
deployment using the driver.
14+
deployment using the Go Driver.
15+
16+
--------------
17+
Connection URI
18+
--------------
19+
20+
The **connection URI** provides a set of instructions that the driver uses to
21+
connect to a MongoDB deployment. It instructs the driver on how it should
22+
connect to MongoDB and how it should behave while connected. The following
23+
example explains each part of a sample connection URI:
24+
25+
.. figure:: /includes/figures/connection_uri_parts.png
26+
:alt: Each part of the connection string
27+
28+
In this example, we use ``mongodb`` for the protocol, which specifies the
29+
:manual:`Standard Connection String Format
30+
</reference/connection-string/#std-label-connections-standard-connection-string-format>`.
31+
You can also use the :manual:`DNS Seed List Connection Format
32+
</reference/connection-string/#dns-seed-list-connection-format>` if you
33+
want more flexibility of deployment and the ability to change the
34+
servers in rotation without reconfiguring clients.
35+
36+
.. note::
37+
38+
If your deployment is on MongoDB Atlas, see the
39+
:atlas:`Atlas driver connection guide </driver-connection>`
40+
and select Go from the language dropdown to retrieve your connection string.
41+
42+
The next part of the connection string contains your username and, if
43+
you are using password-based authentication, your password. Replace the value of
44+
``user`` with your username and ``pass`` with your password. If you are using an
45+
authentication mechanism that does not require a username and password, omit
46+
this part of the connection URI.
47+
48+
The next part of the connection string specifies the hostname or IP address and
49+
port of your MongoDB instance. In the preceding example, we use ``sample.host``
50+
as the hostname and ``27017`` as the port. Replace these values to point to
51+
your MongoDB instance.
52+
53+
The last part of the connection string specifies connection and authentication
54+
options. In the example, we set two connection options:
55+
``maxPoolSize=20`` and ``w=majority``. For more information on connection
56+
options, read the :ref:`connection-options` section of this guide.
57+
58+
The following code shows how you can use the sample connection URI in a client to
59+
connect to MongoDB.
60+
61+
.. literalinclude:: /includes/fundamentals/code-snippets/srv.go
62+
:language: go
63+
64+
.. note::
65+
66+
For information about connecting to Atlas Serverless, see the
67+
`Serverless Instance Limitations page
68+
<https://docs.atlas.mongodb.com/reference/serverless-instance-limitations/#minimum-driver-versions-for-serverless-instances>`__
69+
to identify the minimum driver version you need.
70+
71+
Connect to a MongoDB Server on Your Local Machine
72+
+++++++++++++++++++++++++++++++++++++++++++++++++
73+
74+
.. include:: /includes/localhost-connection.rst
75+
76+
To test whether you can connect to your server, replace the connection
77+
string with your localhost connection string in the preceding code example.
78+
79+
------------------------
80+
Connect to a Replica Set
81+
------------------------
82+
83+
A MongoDB replica set deployment is a group of connected instances that
84+
store the same set of data. This configuration provides data
85+
redundancy and high data availability.
86+
87+
To connect to a replica set deployment, specify the hostname and port numbers
88+
of each instance, separated by commas, and the replica set name as the value
89+
of the ``replicaSet`` parameter in the connection string. In the following
90+
example, the hostnames are ``host1``, ``host2``, and ``host3``, and the
91+
port numbers are all ``27017``. The replica set name is ``myRS``.
92+
93+
.. code-block:: none
94+
95+
mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS
96+
97+
When connecting to a replica set, the driver takes the following actions by default:
98+
99+
- Discovers all replica set members when given the address of any one member.
100+
- Dispatches operations to the appropriate member, such as instructions
101+
to write against the **primary**.
102+
103+
.. tip::
104+
105+
You only need to specify one host to connect to a replica set.
106+
However, to ensure connectivity when the specified host
107+
is unavailable, you should provide the full list of hosts.
108+
109+
Direct Connection
110+
+++++++++++++++++
111+
112+
To force operations on the host designated in the connection URI, specify the ``directConnection`` option. Direct
113+
connections:
114+
115+
- Don't support SRV strings.
116+
- Fail on writes when the specified host is not the **primary**.
117+
- Require you to :manual:`enable secondary reads </reference/method/rs.secondaryOk/>`
118+
when the specified host isn't the **primary**.
119+
120+
.. _connection-options:
121+
122+
------------------
123+
Connection Options
124+
------------------
125+
126+
This section explains several common MongoDB connection and authentication
127+
options. You can pass the connection options as parameters of the connection
128+
URI to specify the behavior of the client.
129+
130+
.. list-table::
131+
:header-rows: 1
132+
:widths: 25 10 15 40
133+
134+
* - Option Name
135+
- Type
136+
- Default Value
137+
- Description
138+
139+
* - **connectTimeoutMS**
140+
- integer
141+
- ``30000``
142+
- Specifies the number of milliseconds to wait before timeout on a TCP
143+
connection.
144+
145+
* - **maxPoolSize**
146+
- integer
147+
- ``100``
148+
- Specifies the maximum number of connections that a connection pool may
149+
have at a given time.
150+
151+
* - **replicaSet**
152+
- string
153+
- ``null``
154+
- Specifies the replica set name for the cluster. All nodes in the
155+
replica set must have the same replica set name, or the Client will not
156+
consider them as part of the set.
157+
158+
* - **maxIdleTimeMS**
159+
- integer
160+
- ``0``
161+
- Specifies the maximum amount of time a connection can remain idle
162+
in the connection pool before being removed and closed. The
163+
default is ``0``, meaning a connection can remain unused
164+
indefinitely.
165+
166+
* - **minPoolSize**
167+
- integer
168+
- ``0``
169+
- Specifies the minimum number of connections that the driver maintains
170+
in a single connection pool.
171+
172+
* - **socketTimeoutMS**
173+
- integer
174+
- ``0``
175+
- Specifies the number of milliseconds to wait for a socket read or
176+
write to return before returning a network error. The ``0``
177+
default value indicates that there is no timeout.
178+
179+
* - **serverSelectionTimeoutMS**
180+
- integer
181+
- ``30000``
182+
- Specifies the number of milliseconds to wait to find an available,
183+
suitable server to execute an operation.
184+
185+
* - **heartbeatFrequencyMS**
186+
- integer
187+
- ``10000``
188+
- Specifies the number of milliseconds to wait between periodic
189+
background server checks.
190+
191+
* - **tls**
192+
- boolean
193+
- ``false``
194+
- Specifies whether to establish a Transport Layer Security (TLS)
195+
connection with the instance. This is automatically set to ``true``
196+
when using a DNS seedlist (SRV) in the connection string. You can
197+
override this behavior by setting the value to ``false``.
198+
199+
* - **w**
200+
- string or integer
201+
- ``null``
202+
- Specifies the write concern. For more information on values, see the
203+
server documentation on
204+
:manual:`Write Concern options </reference/write-concern>`.
205+
206+
* - **directConnection**
207+
- boolean
208+
- ``false``
209+
- Specifies whether to force dispatch **all** operations to the host
210+
specified in the connection URI.
211+
212+
For a full list of connection options, see the `ClientOptions API
213+
documentation
214+
<https://pkg.go.dev/go.mongodb.org/[email protected]/mongo/options#ClientOptions>`__.

‎source/includes/figures/connection_string_parts.png

-9.31 KB
Binary file not shown.

‎source/includes/figures/connection_uri_parts.png

5.92 KB
Loading

‎source/includes/fundamentals/code-snippets/srv.go

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"fmt"
6+
"time"
7+
8+
"go.mongodb.org/mongo-driver/mongo"
9+
"go.mongodb.org/mongo-driver/mongo/options"
10+
"go.mongodb.org/mongo-driver/mongo/readpref"
11+
)
12+
13+
// Connection URI
14+
const uri = "mongodb://user:[email protected]:27017/?maxPoolSize=20&w=majority"
15+
16+
func main() {
17+
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
18+
defer cancel()
19+
20+
// Create a new client and connect to the server
21+
client, err := mongo.Connect(ctx, options.Client().ApplyURI(uri))
22+
23+
if err != nil {
24+
panic(err)
25+
}
26+
defer func() {
27+
if err = client.Disconnect(ctx); err != nil {
28+
panic(err)
29+
}
30+
}()
31+
32+
// Ping the primary
33+
if err := client.Ping(ctx, readpref.Primary()); err != nil {
34+
panic(err)
35+
}
36+
37+
fmt.Println("Successfully connected and pinged.")
38+
}

‎source/includes/localhost-connection.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
If you need to run a MongoDB server on your local machine for development
2+
purposes, you need to complete the following:
3+
4+
1. Download the `Community <https://www.mongodb.com/try/download/community>`__
5+
or `Enterprise <https://www.mongodb.com/try/download/enterprise>`__ version
6+
of MongoDB Server.
7+
8+
#. `Install and configure <https://docs.mongodb.com/manual/installation/>`__
9+
MongoDB Server.
10+
11+
#. Start the server.
12+
13+
.. important::
14+
15+
Always secure your MongoDB server from malicious attacks. See our
16+
:manual:`Security Checklist </administration/security-checklist/>` for a
17+
list of security recommendations.
18+
19+
After you successfully start your MongoDB server, specify your connection
20+
string in your driver connection code.
21+
22+
If your MongoDB Server is running locally, you can use the connection string
23+
``"mongodb://localhost:<port>"`` where ``<port>`` is the port number you
24+
configured your server to listen for incoming connections.
25+
26+
If you need to specify a different hostname or IP address, see our Server
27+
Manual entry on :manual:`Connection Strings </reference/connection-string/>`.

0 commit comments

Comments
 (0)