-
Notifications
You must be signed in to change notification settings - Fork 33
/
Copy pathconnection-guide.txt
187 lines (135 loc) · 6.63 KB
/
connection-guide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
.. _golang-connection-guide:
================
Connection Guide
================
.. facet::
:name: genre
:values: tutorial
.. meta::
:description: Learn how to use the MongoDB Go Driver to connect to MongoDB.
:keywords: connection string, client options, replica set
.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol
Overview
--------
In this guide, you can learn how to connect to a MongoDB instance or
replica set deployment by using the {+driver-short+}.
You can use the {+driver-short+} to connect to deployments hosted in the
following environments:
.. include:: /includes/fact-environments.rst
.. _golang-connection-uri:
--------------
Connection URI
--------------
A **connection URI**, also known as a connection string, tells the
driver how to connect to MongoDB and how to behave while connected.
Parts of a Connection URI
~~~~~~~~~~~~~~~~~~~~~~~~~
The following example explains each part of a sample connection URI:
.. figure:: /includes/figures/connection_uri_parts.png
:alt: Each part of the connection string
In this example, we use ``mongodb`` for the protocol, which specifies the
:manual:`Standard Connection String Format
</reference/connection-string/#std-label-connections-standard-connection-string-format>`.
You can also use the :manual:`DNS Seed List Connection Format
</reference/connection-string/#dns-seed-list-connection-format>` if you
want more flexibility of deployment and the ability to change the
servers in rotation without reconfiguring clients.
The next part of the connection string contains your database username and, if
you are using password-based authentication, your password. Replace the value of
``user`` with your database username and ``pass`` with your password. If you are using an
authentication mechanism that does not require a username and password, omit
this part of the connection URI.
The next part of the connection string specifies the hostname or IP address and
port of your MongoDB instance. In the preceding example, we use ``sample.host``
as the hostname and ``27017`` as the port. Replace these values to point to
your MongoDB instance.
The last part of the connection string specifies connection and authentication
options. In the example, we set two connection options:
``maxPoolSize=20`` and ``w=majority``. To learn more about connection
options, see the :ref:`golang-connection-options` guide.
Connection Example
~~~~~~~~~~~~~~~~~~
To connect to MongoDB, you must create a client. A client manages your
connections and runs database commands.
.. tip:: Reuse Your Client
We recommend that you reuse your client across sessions and operations.
You can use the same ``Client`` instance to perform multiple tasks, instead of
creating a new one each time. The ``Client`` type is safe for
concurrent use by multiple `goroutines
<https://www.golang-book.com/books/intro/10>`__. To learn more about
how connection pools work in the driver, see the :ref:`FAQ page <golang-faq-connection-pool>`.
You can create a client that uses your connection string and other
client options by passing a ``ClientOptions`` object to the ``Connect()``
method.
To specify your connection URI, pass it to the ``ApplyURI()``
method, which returns a new ``ClientOptions`` instance. To set any other
options, call the relevant helper method from the ``options`` package.
To learn more about connection options, see the
:ref:`Connection Options section <golang-connection-options>`. To learn
more about creating a client, see the API documentation for `Client
<{+api+}/mongo#Client>`__ and `Connect() <{+api+}/mongo#Connect>`__.
You can set the {+stable-api+} version as an option to avoid
breaking changes when you upgrade to a new server version. To
learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page
<golang-stable-api>`.
The following code shows how you can create a client that uses an Atlas
connection string and the {+stable-api+} version, connect to MongoDB, and
verify that the connection is successful:
.. _go-connection-example-code:
.. literalinclude:: /includes/fundamentals/code-snippets/srv.go
:language: go
.. tip::
Follow the :ref:`Quick Start guide <golang-connect-to-your-cluster>`
to retrieve your Atlas connection string.
.. note::
To learn about connecting to Atlas Serverless, see the
:ref:`Serverless Instance Limitations page
<atlas-serverless-drivers>` to identify the minimum driver version
required.
--------------------------------
Other Ways to Connect to MongoDB
--------------------------------
If you are connecting to a single MongoDB server instance or replica set
that is not hosted on Atlas, see the following sections to find out how to
connect.
Connect to a MongoDB Server on Your Local Machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/localhost-connection.rst
To test whether you can connect to your server, replace the connection
string with your localhost connection string in the preceding code example.
Connect to a Replica Set
~~~~~~~~~~~~~~~~~~~~~~~~
A MongoDB replica set deployment is a group of connected instances that
store the same set of data. This configuration provides data
redundancy and high data availability.
To connect to a replica set deployment, specify the hostname and port numbers
of each instance, separated by commas, and the replica set name as the value
of the ``replicaSet`` parameter in the connection string. In the following
example, the hostnames are ``host1``, ``host2``, and ``host3``, and the
port numbers are all ``27017``. The replica set name is ``myRS``.
.. code-block:: none
mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS
When connecting to a replica set, the driver takes the following actions by default:
- Discovers all replica set members when given the address of any one member.
- Dispatches operations to the appropriate member, such as instructions
to write against the **primary**.
.. tip::
You can specify just one host to connect to a replica set.
However, to ensure connectivity when the specified host
is unavailable, you should provide the full list of hosts.
Direct Connection
`````````````````
To force operations on the host designated in the connection URI,
specify the ``directConnection`` option. Direct connections exhibit the
following behavior:
- They don't support SRV strings.
- They fail on writes when the specified host is not the **primary**.
- They require you to specify a :manual:`secondary read preference
</core/read-preference/#mongodb-readmode-secondary>` when the
specified host isn't the **primary** node.
.. note:: Replica Set in Docker
.. sharedinclude:: dbx/docker-replica-set.rst