Notable Peru Mariachis

    TypeScript icon, indicating that this package has built-in type declarations

    4.1.2 • Public • Published

    MongoDB NodeJS Driver

    The official MongoDB driver for Node.js.

    Upgrading to version 4? Take a look at our upgrade guide here!

    Quick Links

    what where
    npm package
    upgrade to v4 docs/

    Bugs / Feature Requests

    Think you’ve found a bug? Want to see a new feature in node-mongodb-native? Please open a case in our issue management tool, JIRA:

    • Create an account and login
    • Navigate to the NODE project
    • Click Create Issue - Please provide as much information as possible about the issue type and how to reproduce it.

    Bug reports in JIRA for all driver projects (i.e. NODE, PYTHON, CSHARP, JAVA) and the Core Server (i.e. SERVER) project are public.

    Support / Feedback

    For issues with, questions about, or feedback for the Node.js driver, please look into our support channels. Please do not email any of the driver developers directly with issues or questions - you're more likely to get an answer on the MongoDB Community Forums.

    Change Log

    Change history can be found in


    For version compatibility matrices, please refer to the following links:

    Typescript Version

    We recommend using the latest version of typescript, however we do provide a downleveled version of the type definitions that we test compiling against typescript@4.0.2. Since typescript does not restrict breaking changes to major versions we consider this support best effort. If you run into any unexpected compiler failures please let us know and we will do our best to correct it.


    The recommended way to get started using the Node.js 4.x driver is by using the npm (Node Package Manager) to install the dependency in your project.

    After you've created your own project using npm init, you can run:

    npm install mongodb
    # or ...
    yarn add mongodb

    This will download the MongoDB driver and add a dependency entry in your package.json file.

    If you are a Typescript user, you will need the Node.js type definitions to use the driver's definitions:

    npm install -D @types/node


    The MongoDB driver depends on several other packages. These are:

    Some of these packages include native C++ extensions, consult the trouble shooting guide here if you run into issues.

    Quick Start

    This guide will show you how to set up a simple application using Node.js and MongoDB. Its scope is only how to set up the driver and perform the simple CRUD operations. For more in-depth coverage, see the official documentation.

    Create the package.json file

    First, create a directory where your application will live.

    mkdir myProject
    cd myProject

    Enter the following command and answer the questions to create the initial structure for your new project:

    npm init -y

    Next, install the driver as a dependency.

    npm install mongodb

    Start a MongoDB Server

    For complete MongoDB installation instructions, see the manual.

    1. Download the right MongoDB version from MongoDB
    2. Create a database directory (in this case under /data).
    3. Install and start a mongod process.
    mongod --dbpath=/data

    You should see the mongod process start up and print some status information.

    Connect to MongoDB

    Create a new app.js file and add the following code to try out some basic CRUD operations using the MongoDB driver.

    Add code to connect to the server and the database myProject:

    NOTE: All the examples below use async/await syntax.

    However, all async API calls support an optional callback as the final argument, if a callback is provided a Promise will not be returned.

    const { MongoClient } = require('mongodb');
    // or as an es module:
    // import { MongoClient } from 'mongodb'
    // Connection URL
    const url = 'mongodb://localhost:27017';
    const client = new MongoClient(url);
    // Database Name
    const dbName = 'myProject';
    async function main() {
      // Use connect method to connect to the server
      await client.connect();
      console.log('Connected successfully to server');
      const db = client.db(dbName);
      const collection = db.collection('documents');
      // the following code examples can be pasted here...
      return 'done.';
      .finally(() => client.close());

    Run your app from the command line with:

    node app.js

    The application should print Connected successfully to server to the console.

    Insert a Document

    Add to app.js the following function which uses the insertMany method to add three documents to the documents collection.

    const insertResult = await collection.insertMany([{ a: 1 }, { a: 2 }, { a: 3 }]);
    console.log('Inserted documents =>', insertResult);

    The insertMany command returns an object with information about the insert operations.

    Find All Documents

    Add a query that returns all the documents.

    const findResult = await collection.find({}).toArray();
    console.log('Found documents =>', findResult);

    This query returns all the documents in the documents collection. If you add this below the insertMany example you'll see the document's you've inserted.

    Find Documents with a Query Filter

    Add a query filter to find only documents which meet the query criteria.

    const filteredDocs = await collection.find({ a: 3 }).toArray();
    console.log('Found documents filtered by { a: 3 } =>', filteredDocs);

    Only the documents which match 'a' : 3 should be returned.

    Update a document

    The following operation updates a document in the documents collection.

    const updateResult = await collection.updateOne({ a: 3 }, { $set: { b: 1 } });
    console.log('Updated documents =>', updateResult);

    The method updates the first document where the field a is equal to 3 by adding a new field b to the document set to 1. updateResult contains information about whether there was a matching document to update or not.

    Remove a document

    Remove the document where the field a is equal to 3.

    const deleteResult = await collection.deleteMany({ a: 3 });
    console.log('Deleted documents =>', deleteResult);

    Index a Collection

    Indexes can improve your application's performance. The following function creates an index on the a field in the documents collection.

    const indexName = await collection.createIndex({ a: 1 });
    console.log('index name =', indexName);

    For more detailed information, see the indexing strategies page.

    Error Handling

    If you need to filter certain errors from our driver we have a helpful tree of errors described in docs/

    It is our recommendation to use instanceof checks on errors and to avoid relying on parsing error.message and strings in your code. We guarantee instanceof checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.

    Any new errors we add to the driver will directly extend an existing error class and no existing error will be moved to a different parent class outside of a major release. This means instanceof will always be able to accurately capture the errors that our driver throws (or returns in a callback).

    const client = new MongoClient(url);
    await client.connect();
    const collection = client.db().collection('collection');
    try {
      await collection.insertOne({ _id: 1 });
      await collection.insertOne({ _id: 1 }); // duplicate key error
    } catch (error) {
      if (error instanceof MongoServerError) {
        console.log(`Error worth logging: ${error}`); // special case for some reason
      throw error; // still want to crash

    Next Steps


    Apache 2.0

    © 2009-2012 Christian Amor Kvalheim © 2012-present MongoDB Contributors


    npm i mongodb@4.1.2





    Unpacked Size

    2.7 MB

    Total Files


    Last publish


    • mbroadst
    • durran
    • pearsb1
    • nbbeeken
    • kmahar
    • dariakp