Releases are created automatically and signed using the Node team's GPG key. All release packages provided as part of a GitHub release are signed. 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:
[!Note]
No GPG verification is done when using npm to install the package. The contents of the GitHub tarball and npm's tarball are identical.
Releases published to the npm registry also include a provenance attestation, which cryptographically links the package to its source repository and build workflow. To verify provenance:
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.
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.
We recommend using the latest version of typescript, however we currently ensure the driver's public types compile against typescript@5.6.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 es2023.
Running in Custom Runtimes
We are working on removing Node.js as a dependency of the driver, so that in the future it will be possible to use the driver in non-Node environments.
This work is currently in progress, and if you're curious, this is our first runtime adapter commit.
Some things to keep in mind if you are using a non-Node runtime:
Users of Webpack/Vite may need to prevent crypto polyfill injection.
Auth mechanism SCRAM-SHA-1 has a hard dependency on Node.js.
Auth mechanism SCRAM-SHA-1 is not supported in FIPS mode.
Installation
The recommended way to get started using the Node.js 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
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 (only needed on Node.js versions earlier than 22.15.0, later versions have zstd built in)
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 myProjectcd 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.
Create a database directory (in this case under /data).
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 } ))
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 URLconst url = 'mongodb://localhost:27017';const client = new MongoClient(url);// Database Nameconst 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.
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.
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.
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.
Experimental Features
The MongoDB Node.js driver offers cutting-edge experimental features that give you early access to new capabilities and APIs. These features are marked with @experimental tags and are great for exploring new functionality and providing feedback.
Experimental features are not subject to semantic versioning rules, so breaking changes or removal may occur in any future release. The use of these features is not recommended for production environments.
Explore the full list of experimental features, complete with descriptions and usage examples, in EXPERIMENTAL_FEATURES.md.