Skip to content

DOCSP-48378 make mongoclient page #1038

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

Merged
merged 7 commits into from
Mar 21, 2025
Merged

DOCSP-48378 make mongoclient page #1038

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
85170a2
make mongoclient page
shuangela Mar 19, 2025
d25e99e
fix link:
shuangela Mar 19, 2025
6496b23
fix link
shuangela Mar 19, 2025
d72679a
add anchor to page to avoid broken link
shuangela Mar 19, 2025
d7888ab
nr feedback
shuangela Mar 20, 2025
8930a12
nb feedback
shuangela Mar 21, 2025
66806d1
monospace
shuangela Mar 21, 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
152 changes: 59 additions & 93 deletions source/connect/mongoclient.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,54 +18,70 @@ Create a MongoClient
:depth: 2
:class: singlecol

This guide shows you how to connect to a
`MongoDB Atlas deployment <https://www.mongodb.com/docs/atlas>`__,
a MongoDB instance, or a replica set using the Node.js driver.
Overview
--------

To connect to a MongoDB deployment, you need 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 also use ``MongoClientOptions`` to customize the way the {+driver-short+} behaves
while connected to MongoDB.

This guide shows you how to create a connection string and use a ``MongoClient`` object
to connect to MongoDB.

.. _node-connection-uri:

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

The **connection URI** is the set of instructions that the driver uses to connect to a
MongoDB deployment. It tells the driver how to connect to MongoDB and how to behave
while connected. The following example shows each part of the connection URI:
A standard connection string includes the following components:

.. figure:: /includes/figures/dns_seedlist_connection_string_parts.png
:alt: Each part of the connection string
.. list-table::
:widths: 20 80
:header-rows: 1

In this example, we connect to an Atlas MongoDB deployment that has a
DNS SRV record. For more details, see the
:manual:`DNS Seed List Connection Format
</reference/connection-string/#dns-seed-list-connection-format>`
documentation. This format offers flexibility in deployment and the
ability to change the servers in rotation without reconfiguring clients.
* - Component
- Description

.. note::
* - ``mongodb://``

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

To learn how to retrieve your connection string in Atlas, see the
:atlas:`Atlas driver connection guide </driver-connection>`.
* - ``username:password``

If you are connecting to an instance or replica set that does not have a
DNS SRV address, you must use ``mongodb`` for the protocol, which specifies
the :manual:`Standard Connection String Format
</reference/connection-string/#std-label-connections-standard-connection-string-format>`.
- 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:`node-troubleshooting-connection-admin` in the Connection Troubleshooting guide.

After the protocol, the next part of the connection string contains credentials
if you are using password-based authentication. Replace the value of ``user``
with your 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.
* - ``host[:port]``

The next part of the connection string specifies the hostname or IP address of
your MongoDB instance, followed by the port number. In the example above, we use
``sample.host`` as the hostname and ``27017`` as the port. Replace these values
to point to your MongoDB instance.
- 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``.

The last part of the connection string contains connection and authentication
options as parameters. In the example above, we set two connection options:
``maxPoolSize=20`` and ``w=majority``. For more information on connection
options, skip to the :ref:`node-connection-options` section.
* - ``/defaultauthdb``

- Optional. The authentication database to use if the
connection string includes ``username:password@``
authentication credentials but not the ``authSource`` option. If you don't include
this component, the client authenticates the user against the ``admin`` database.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe worth mentioning this is the database that is used when calling client.db() with no argument?


* - ``?<options>``

- Optional. A query string that specifies connection-specific
options as ``<name>=<value>`` pairs. See
:ref:`node-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.

.. _connect-sample-node-driver:

Expand All @@ -81,8 +97,8 @@ URI and a ``MongoClientOptions`` object.
As each ``MongoClient`` represents a pool of connections to the
database, most applications only require a single instance of a
``MongoClient``, even across multiple requests. To learn more about
how connection pools work in the driver, see the :ref:`FAQ page
<node-faq-connection-pool>`.
how connection pools work in the driver, see the :ref:`Connection Pools page
<node-connection-pools>`.

Use the ``serverApi`` option in your ``MongoClientOptions`` object to
enable the {+stable-api+} feature, which forces the server to run operations
Expand All @@ -102,63 +118,13 @@ verify that the connection is successful:
Call the ``MongoClient.connect()`` method explicitly if you want to verify that the
connection is successful.

To learn more about the Stable
API feature, see the :ref:`{+stable-api+} page <nodejs-stable-api>`.

.. _node-other-ways-to-connect:

Other Ways to Connect to MongoDB
--------------------------------

If you are connecting to a single {+mdb-server+} instance or replica set
that is not hosted on Atlas, see the following sections to find out how to
connect.

Connect to a {+mdb-server+} on Your Local Machine
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /includes/localhost-connection.rst

To test whether you can connect to your server, replace the connection
string in the :ref:`Connect to MongoDB <connect-sample-node-driver>` code
example and run it.

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 of instances 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 a comma, and the replica set name as the value
of the ``replicaSet`` parameter in the connection string.

.. code-block:: none

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRs

When making a connection, 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 write against the **primary**.

.. tip:: Specify all hosts

To ensure connectivity if one host is unavailable, provide the full
list of hosts when connecting to a replica set.
To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page <nodejs-stable-api>`.

Direct Connection
^^^^^^^^^^^^^^^^^
API Documentation
-----------------

To force your operations to run on the host specified in your connection
URI, you can specify the ``directConnection`` connection option. If you
specify this option, you must use the standard connection URI format. The
driver does not accept the DNS seedlist connection format (SRV) when you
specify this option.
For more information about creating a ``MongoClient`` object with the
{+driver-short+}, see the following API documentation:

When you specify ``directConnection`` and connect to a secondary member of the
replica set, your write operations fail because the client isn't
connected to the primary member. To perform read operations, you must
enable secondary reads. See the :manual:`read preference options </reference/connection-string/#read-preference-options>`
for more information.
- `MongoClient <{+api+}/classes/MongoClient.html>`__
- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__