Skip to content

DOCSP-49973 Create a MongoClient #507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: comp-cov
Choose a base branch
from
Open

DOCSP-49973 Create a MongoClient #507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e48b2bf
add page content and link to manual
stephmarie17 Jun 4, 2025
57089bd
update connect landing
stephmarie17 Jun 5, 2025
40f0048
edits
stephmarie17 Jun 5, 2025
f8c386e
edits
stephmarie17 Jun 6, 2025
61acd47
formatting
stephmarie17 Jun 6, 2025
056cac8
shift content for info flow
stephmarie17 Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 8 additions & 164 deletions source/connect.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,169 +32,13 @@ Connection Guide
Overview
--------

In this guide, you can learn how to connect to a MongoDB instance or
replica set deployment by using the {+driver-short+}.
Learn how to set up a connection and specify connection behavior from your
application to a MongoDB deployment using the {+driver-short+} in the following
sections:

You can use the {+driver-short+} to connect to deployments hosted in the
following environments:
- :ref:`golang-mongoclient`
- :ref:`golang-connection-options`
- :ref:`golang-connection-troubleshooting`

.. 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 image 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:`SRV Connection Format
</reference/connection-string/#srv-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>`__.

.. TODO, Add back this line when Connection Pools page is made: To learn more about
how connection pools work in the driver, see the :ref:`Connection Pools guide <golang-connection-pools>`.

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, 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
For more information about authenticating with a MongoDB instance, see the
:ref:`golang-authentication` section.
191 changes: 190 additions & 1 deletion source/connect/mongoclient.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,194 @@ Create a MongoClient
:depth: 2
:class: singlecol

.. facet::
:name: genre
:values: reference

.. meta::
:keywords: connection string, URI, Atlas, code example

.. TODO
Overview
--------

In this guide, you can learn how to connect to a `MongoDB Atlas deployment
<https://www.mongodb.com/docs/atlas>`__, a MongoDB instance, or a replica set
using the {+driver-short+}.

To connect to a MongoDB deployment, you need the following two things:

- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+}
which MongoDB deployment to connect to.

- **MongoClient** object, which creates the connection to and performs operations
on the MongoDB deployment.

You can use ``options.Client()`` to customize the way the {+driver-short+}
behaves while connected to MongoDB.

Connection URI
--------------

A standard connection string includes the following components:

.. list-table::
:widths: 20 80
:header-rows: 1

* - Component
- Description

* - ``mongodb://``

- Required. A prefix that identifies this as a string in the
standard connection format.

* - ``username:password``

- Optional. Authentication credentials. If you include these, the client
authenticates the user against the database specified in ``authSource``.
For more information about the ``authSource`` connection option,
see :ref:`golang-connection-troubleshooting` in the Connection Troubleshooting guide.

* - ``host[:port]``

- Required. The host and optional port number where MongoDB is running. If you don't
include the port number, the driver uses the default port, ``27017``.

* - ``/defaultauthdb``

- Optional. The authentication database to use if the
connection string includes ``username:password@``
authentication credentials but not the ``authSource`` option.
When you call ``client.db()`` with no argument, this is the database that is used. If you don't include
this component, the client authenticates the user against the ``admin`` database.

* - ``?<options>``

- Optional. A query string that specifies connection-specific
options as ``<name>=<value>`` pairs. See
:ref:`golang-connection-options` for a full description of
these options.

For more information about creating a connection string, see :manual:`Connection
Strings </reference/connection-string>` in the MongoDB Server documentation.

Create a Client to Connect to MongoDB Atlas
-------------------------------------------

To connect to MongoDB, you must create a client. A client manages your
connections and runs database commands.

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.

.. 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://go.dev/tour/concurrency/1>`__. To learn more
about how connection pools work in the driver, see the
:ref:`golang-connection-pools` guide.

To learn more about connection options, see the :ref:`Connection Options
<golang-connection-options>` section. 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>`.

.. _go-connection-example-code:

Example
~~~~~~~

The following code shows how you can create a client that uses an Atlas
connection string and the {+stable-api+} version, connects to MongoDB, and verifies
that the connection is successful:

.. literalinclude:: /includes/fundamentals/code-snippets/srv.go
:language: go
:copyable:
:dedent:

.. tip::

Follow the :ref:`Quick Start guide <golang-connect-to-your-cluster>`
to learn how 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 learn 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 <go-connection-example-code>`.

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 must provide the full list of hosts.

To learn more about replication in MongoDB, see the :manual:`Replication </replication>` section of Server manual.

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
Loading
Loading