mongodb

What is mongodb?

The mongodb npm package is the official Node.js driver for MongoDB. It provides a high-level API to connect to and interact with MongoDB databases. With this package, developers can perform CRUD operations, manage database connections, and work with MongoDB features like transactions, indexes, and aggregation.

What are mongodb's main functionalities?

Connecting to a MongoDB database

This code sample demonstrates how to connect to a MongoDB database using the MongoClient object provided by the mongodb package.

const { MongoClient } = require('mongodb');
const url = 'mongodb://localhost:27017';
const client = new MongoClient(url);
async function connect() {
  try {
    await client.connect();
    console.log('Connected to MongoDB');
  } catch (e) {
    console.error(e);
  }
}
connect();

CRUD Operations

This code sample shows how to perform CRUD (Create, Read, Update, Delete) operations on a MongoDB collection using the mongodb package.

const { MongoClient } = require('mongodb');
const url = 'mongodb://localhost:27017';
const client = new MongoClient(url);
const dbName = 'myDatabase';
async function crudOperations() {
  try {
    await client.connect();
    const db = client.db(dbName);
    const collection = db.collection('documents');

    // Create a document
    await collection.insertOne({ a: 1 });

    // Read documents
    const docs = await collection.find({}).toArray();

    // Update a document
    await collection.updateOne({ a: 1 }, { $set: { b: 1 } });

    // Delete a document
    await collection.deleteOne({ b: 1 });
  } catch (e) {
    console.error(e);
  } finally {
    await client.close();
  }
}
crudOperations();

Index Management

This code sample illustrates how to manage indexes in a MongoDB collection, including creating an index and listing all indexes.

const { MongoClient } = require('mongodb');
const url = 'mongodb://localhost:27017';
const client = new MongoClient(url);
const dbName = 'myDatabase';
async function manageIndexes() {
  try {
    await client.connect();
    const db = client.db(dbName);
    const collection = db.collection('documents');

    // Create an index
    await collection.createIndex({ a: 1 });

    // List indexes
    const indexes = await collection.indexes();
    console.log(indexes);
  } catch (e) {
    console.error(e);
  } finally {
    await client.close();
  }
}
manageIndexes();

Aggregation

This code sample demonstrates how to use the aggregation framework provided by MongoDB to process data and compute aggregated results.

const { MongoClient } = require('mongodb');
const url = 'mongodb://localhost:27017';
const client = new MongoClient(url);
const dbName = 'myDatabase';
async function aggregateData() {
  try {
    await client.connect();
    const db = client.db(dbName);
    const collection = db.collection('documents');

    // Perform an aggregation query
    const aggregation = await collection.aggregate([
      { $match: { a: 1 } },
      { $group: { _id: '$b', total: { $sum: 1 } } }
    ]).toArray();
    console.log(aggregation);
  } catch (e) {
    console.error(e);
  } finally {
    await client.close();
  }
}
aggregateData();

Other packages similar to mongodb

mongoose

Mongoose is an Object Data Modeling (ODM) library for MongoDB and Node.js. It manages relationships between data, provides schema validation, and is used to translate between objects in code and the representation of those objects in MongoDB. Mongoose offers a more structured approach to data handling with predefined schemas compared to the flexibility of the mongodb package.

couchbase

Couchbase is the official Node.js client library for the Couchbase database. While Couchbase is a different NoSQL database system with its own set of features and capabilities, the couchbase npm package offers similar functionalities in terms of CRUD operations, connection management, and querying as the mongodb package does for MongoDB.

redis

Redis is an in-memory data structure store, used as a database, cache, and message broker. The npm package for Redis provides Node.js bindings to the Redis server. It is similar to mongodb in that it allows for data storage and retrieval, but it operates in-memory and is typically used for different use cases such as caching.

README

MongoDB Node.js Driver

The official MongoDB driver for Node.js.

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

Quick Links

Site	Link
Documentation	www.mongodb.com/docs/drivers/node
API Docs	mongodb.github.io/node-mongodb-native
npm package	www.npmjs.com/package/mongodb
MongoDB	www.mongodb.com
MongoDB University	learn.mongodb.com
MongoDB Developer Center	www.mongodb.com/developer
Stack Overflow	stackoverflow.com
Source Code	github.com/mongodb/node-mongodb-native
Upgrade to v6	etc/notes/CHANGES_6.0.0.md
Contributing	CONTRIBUTING.md
Changelog	HISTORY.md

Release Integrity

Releases are created automatically and signed using the Node team's GPG key. This applies to the git tag as well as all release packages provided as part of a GitHub release. To verify the provided packages, download the key and import it using gpg:

gpg --import node-driver.asc

The GitHub release contains a detached signature file for the NPM package (named mongodb-X.Y.Z.tgz.sig).

The following command returns the link npm package.

npm view mongodb@vX.Y.Z dist.tarball

Using the result of the above command, a curl command can return the official npm package for the release.

To verify the integrity of the downloaded package, run the following command:

gpg --verify mongodb-X.Y.Z.tgz.sig mongodb-X.Y.Z.tgz

[!Note] No verification is done when using npm to install the package. The contents of the Github tarball and npm's tarball are identical.

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 jira.mongodb.org.
• Navigate to the NODE project jira.mongodb.org/browse/NODE.
• 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 HISTORY.md.

Compatibility

The driver currently supports 3.6+ servers.

** 3.6 support is deprecated and support will be removed in a future version **

For exhaustive server and runtime version compatibility matrices, please refer to the following links:

• MongoDB
• NodeJS

Component Support Matrix

The following table describes add-on component version compatibility for the Node.js driver. Only packages with versions in these supported ranges are stable when used in combination.

Component	mongodb@3.x	mongodb@4.x	mongodb@5.x	mongodb@6.x
bson	^1.0.0	^4.0.0	^5.0.0	^6.0.0
bson-ext	^1.0.0 || ^2.0.0	^4.0.0	N/A	N/A
kerberos	^1.0.0	^1.0.0 || ^2.0.0	^1.0.0 || ^2.0.0	^2.0.1
mongodb-client-encryption	^1.0.0	^1.0.0 || ^2.0.0	^2.3.0	^6.0.0
mongodb-legacy	N/A	^4.0.0	^5.0.0	^6.0.0
@mongodb-js/zstd	N/A	^1.0.0	^1.0.0	^1.1.0

Typescript Version

We recommend using the latest version of typescript, however we currently ensure the driver's public types compile against typescript@4.4.0. This is the lowest typescript version guaranteed to work with our driver: older versions may or may not work - use at your own risk. Since typescript does not restrict breaking changes to major versions, we consider this support best effort. If you run into any unexpected compiler failures against our supported TypeScript versions, please let us know by filing an issue on our JIRA.

Additionally, our Typescript types are compatible with the ECMAScript standard for our minimum supported Node version. Currently, our Typescript targets es2021.

Installation

The recommended way to get started using the Node.js 5.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

Driver Extensions

The MongoDB driver can optionally be enhanced by the following feature packages:

Maintained by MongoDB:

• Zstd network compression - @mongodb-js/zstd
• MongoDB field level and queryable encryption - mongodb-client-encryption
• GSSAPI / SSPI / Kerberos authentication - kerberos

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

Third party:

• Snappy network compression - snappy
• AWS authentication - @aws-sdk/credential-providers

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: Resolving DNS Connection issues

Node.js 18 changed the default DNS resolution ordering from always prioritizing IPv4 to the ordering returned by the DNS provider. In some environments, this can result in localhost resolving to an IPv6 address instead of IPv4 and a consequent failure to connect to the server.

This can be resolved by:

• specifying the IP address family using the MongoClient family option (MongoClient(<uri>, { family: 4 } ))
• launching mongod or mongos with the ipv6 flag enabled (--ipv6 mongod option documentation)
• using a host of 127.0.0.1 in place of localhost
• specifying the DNS resolution ordering with the --dns-resolution-order Node.js command line argument (e.g. node --dns-resolution-order=ipv4first)

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.';
}

main()
  .then(console.log)
  .catch(console.error)
  .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 documents 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 etc/notes/errors.md.

It is our recommendation to use instanceof checks on errors and to avoid relying on parsing error.message and error.name 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.

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
}

Nightly releases

If you need to test with a change from the latest main branch, our mongodb npm package has nightly versions released under the nightly tag.

npm install mongodb@nightly

Nightly versions are published regardless of testing outcome. This means there could be semantic breakages or partially implemented features. The nightly build is not suitable for production use.

Next Steps

• MongoDB Documentation
• MongoDB Node Driver Documentation
• Read about Schemas
• Star us on GitHub

License

Apache 2.0

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

Changelog

6.11.0 (2024-11-22)

Features

• NODE-5682: set maxTimeMS on commands and preempt I/O (#4174) (e4e6a5e)
• NODE-5844: add iscryptd to ServerDescription (#4239) (c39d443)
• NODE-6069: OIDC k8s machine workflow (#4270) (82c931c)
• NODE-6090: Implement CSOT logic for connection checkout and server selection (bd8a9f4)
• NODE-6231: Add CSOT behaviour for retryable reads and writes (#4186) (2ffd5eb)
• NODE-6274: add CSOT support to bulkWrite (#4250) (c5a9ae5)
• NODE-6275: Add CSOT support to GridFS (#4246) (3cb8187)
• NODE-6304: add CSOT support for non-tailable cursors (#4195) (131f6ed)
• NODE-6305: Add CSOT support to tailable cursors (#4218) (2398fc6)
• NODE-6312: add error transformation for server timeouts (#4192) (c2c0cb9)
• NODE-6313: add CSOT support to sessions and transactions (#4199) (5f1102f)
• NODE-6387: Add CSOT support to change streams (#4256) (4588ff2)
• NODE-6389: add support for timeoutMS in StateMachine.execute() (#4243) (c55f965)
• NODE-6390: Add timeoutMS support to auto encryption (#4265) (55e08e7)
• NODE-6391: Add timeoutMS support to explicit encryption (#4269) (f745b99)
• NODE-6392: add timeoutMS support to ClientEncryption helpers part 1 (#4281) (e86f11e)
• NODE-6403: add CSOT support to client bulk write (#4261) (365d63b)
• NODE-6421: add support for timeoutMS to explain helpers (#4268) (5b2629b)
• NODE-6446: deprecate legacy timeout options (#4279) (c28608b)
• NODE-6551: update bson to 6.10.0 (#4329) (adb15fe)

Bug Fixes

• NODE-6374: MongoOperationTimeoutError inherits MongoRuntimeError (#4237) (9fb896a)
• NODE-6412: read stale response from previously timed out connection (#4273) (fd8f3bd)
• NODE-6454: use timeoutcontext for state machine execute() cursor options (#4291) (5dd8ee5)
• NODE-6469: pool is cleared before connection checkin on error (#4296) (06a2e2c)
• NODE-6523: deleteMany in gridfs passes timeoutMS to predicate, not options (#4319) (1965ed5)

Performance Improvements

• NODE-6525: remove setPrototype and defineProperty from hot path (#4321) (48ed47e)