Node.js Quick Start

Connect to DocumentDB from Node.js using the official MongoDB driver.

Have a running DocumentDB instance?

If yes, keep it and continue with the client prerequisites below. Otherwise, choose one server installation:

Docker: run a local container on Linux, macOS, or Windows. Recommended for evaluation and development.
Linux packages: install the complete stack, then create a private PostgreSQL instance with the setup wizard.

The Docker Quick Start and Linux Packages Quick Start include the full server instructions. Do not start a second instance if one is already running.

These examples connect to localhost:10260, so run the client on the same host as DocumentDB. Use the credentials chosen for Docker, or username admin and the password chosen during Linux package setup. If you changed the endpoint, use its configured host and port.

Self-signed certificate bypasses below are for local development only. For network access, use a trusted certificate. Linux package setup binds the gateway on all interfaces by default: firewall port 10260 before setup and follow network and certificate guidance. Docker examples publish only on loopback.

Prerequisites

Node.js 20.19 or later (required by the current mongodb driver)
npm
Basic familiarity with JavaScript

Set your client credentials

Set these in the terminal that will run your application. Replace the placeholders with your existing instance's credentials (for Linux packages, admin and your setup password). The driver passes them as raw values, not embedded in a connection URI.

export DOCUMENTDB_USERNAME='<YOUR_USERNAME>'
export DOCUMENTDB_PASSWORD='<YOUR_PASSWORD>'

Optional: start a Docker instance

Skip this if you installed Linux packages or already have a running instance. If you chose Docker and have Docker installed, replace the placeholders below with your chosen credentials. This self-contained command also sets the environment variables read by your application:

export DOCUMENTDB_USERNAME='<YOUR_USERNAME>'
export DOCUMENTDB_PASSWORD='<YOUR_PASSWORD>'

docker run -dt --name documentdb \
  -p 127.0.0.1:10260:10260 \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME}" \
  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD}"

Wait for the readiness banner in docker logs documentdb before connecting; see Docker Quick Start.

Create a project

mkdir my-documentdb-app
cd my-documentdb-app
npm init -y
npm install mongodb

Connect and run your first queries

Create an index.js file. The certificate bypass is for local development only, with the default self-signed certificate from Linux package setup or Docker.

const { MongoClient } = require("mongodb");

const username = process.env.DOCUMENTDB_USERNAME;
const password = process.env.DOCUMENTDB_PASSWORD;

if (!username || !password) {
  throw new Error(
    "Set DOCUMENTDB_USERNAME and DOCUMENTDB_PASSWORD before running this script"
  );
}

const uri = "mongodb://localhost:10260/";
const options = {
  auth: { username, password },
  authSource: "admin",
  tls: true,
  tlsAllowInvalidCertificates: true,
  directConnection: true
};

async function main() {
  const client = new MongoClient(uri, options);

  try {
    await client.connect();

    const db = client.db("quickstart");
    await db.command({ ping: 1 });

    const movies = db.collection("movies");

    await movies.insertMany([
      { title: "The Matrix", year: 1999, genres: ["sci-fi", "action"] },
      { title: "Dune", year: 2021, genres: ["sci-fi", "adventure"] },
      { title: "Arrival", year: 2016, genres: ["sci-fi", "drama"] }
    ]);

    await movies.createIndex({ title: 1 });

    const recentMovies = await movies
      .find(
        { year: { $gte: 2000 } },
        { projection: { _id: 0, title: 1, year: 1 } }
      )
      .sort({ year: -1 })
      .toArray();

    console.log("Connected to DocumentDB");
    console.log(recentMovies);
  } finally {
    await client.close();
  }
}

main().catch(console.error);

Run the script:

node index.js

Connect with a trusted local certificate instead

If you want certificate validation instead of tlsAllowInvalidCertificates=true, obtain the trusted certificate or CA file for your endpoint and replace the original options object with the version below. For Linux packages, follow certificate configuration. For Docker, copy the local certificate with:

docker cp documentdb:/home/documentdb/.local/state/documentdb-gateway/tls/cert.pem ~/documentdb-cert.pem

const options = {
  auth: { username, password },
  authSource: "admin",
  tls: true,
  tlsCAFile: "/absolute/path/documentdb-cert.pem",
  directConnection: true
};