diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index a0176ab71..ab63a2245 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -18,54 +18,71 @@ Create a MongoClient :depth: 2 :class: singlecol -This guide shows you how to connect to a -`MongoDB Atlas deployment `__, -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 -` -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 `. + * - ``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 -`. + - 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. + 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. + + * - ``?`` + + - Optional. A query string that specifies connection-specific + options as ``=`` 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 ` in the +MongoDB Server documentation. .. _connect-sample-node-driver: @@ -81,8 +98,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 - `. + how connection pools work in the driver, see the :ref:`Connection Pools page + `. Use the ``serverApi`` option in your ``MongoClientOptions`` object to enable the {+stable-api+} feature, which forces the server to run operations @@ -102,63 +119,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 `. - -.. _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 ` 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 `. -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 ` -for more information. +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ \ No newline at end of file