Create a MongoClient

On this page

Overview

Connection URI
Atlas Connection Example
API Documentation

Overview

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

Connection URI, also known as a connection string, which tells the Node.js driver 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 Node.js driver behaves while connected to MongoDB.

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

Connection URI

A standard connection string includes the following components:

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 Verify the User Is in the Authentication Database 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 Specify Connection Options for a full description of these options.

For more information about creating a connection string, see Connection Strings in the MongoDB Server documentation.

Atlas Connection Example

You must create a client to connect to a MongoDB deployment on Atlas. To create a client, construct an instance of MongoClient, passing in your URI and a MongoClientOptions object.

Tip

Reuse Your Client

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 Connection Pools page.

Use the serverApi option in your MongoClientOptions object to enable the Stable API feature, which forces the server to run operations with behavior compatible with the specified API version.

The following code shows how you can specify the connection string and the Stable API client option when connecting to a MongoDB deployment on Atlas and verify that the connection is successful:

const { MongoClient, ServerApiVersion } = require("mongodb");
// Replace the placeholder with your Atlas connection string
const uri = "<connection string>";
// Create a MongoClient with a MongoClientOptions object to set the Stable API version
const client = new MongoClient(uri,  {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true,
        }
    }
);
async function run() {
  try {
    // Connect the client to the server (optional starting in v4.7)
    await client.connect();
    // Send a ping to confirm a successful connection
    await client.db("admin").command({ ping: 1 });
    console.log("Pinged your deployment. You successfully connected to MongoDB!");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Note

The Node.js driver automatically calls the MongoClient.connect() method when using the client to perform CRUD operations on your MongoDB deployment. 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 Stable API page.

API Documentation

For more information about creating a MongoClient object with the Node.js driver, see the following API documentation:

Back

Connect

Connection Options