Back to Documentation

Getting Started

Mongo Shell Quick Start

Use mongosh to verify a local DocumentDB instance, inspect sample data, and run your first document commands.

Prerequisites

Start DocumentDB first

For the fastest local setup, start DocumentDB Local with Docker:

docker run -dt --name documentdb \
  -p 10260:10260 \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>

If you prefer a host installation instead of Docker, use Linux Packages Quick Start and complete the documentdb-setup step first.

Replace <YOUR_USERNAME> and <YOUR_PASSWORD> with your own credentials.

DocumentDB Local loads built-in sample data into sampledb by default. It also uses a self-signed certificate by default, so the fastest local mongosh connection adds --tlsAllowInvalidCertificates.

Connect and verify the connection

mongosh localhost:10260 \
  -u <YOUR_USERNAME> \
  -p <YOUR_PASSWORD> \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls \
  --tlsAllowInvalidCertificates

After you connect, run a quick health check:

db.runCommand({ ping: 1 })

db.adminCommand({ listDatabases: 1 })

Successful output confirms authentication, TLS, and the gateway endpoint are working.

Explore the built-in sample data

DocumentDB Local loads sample collections into sampledb by default.

use sampledb

db.users.find(
  {},
  { name: 1, email: 1, _id: 0 }
).limit(3)

db.products.find(
  { category: "Electronics" },
  { name: 1, price: 1, _id: 0 }
)

Create your own collection

use quickstart

db.movies.deleteMany({})

db.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"] }
])

db.movies.createIndex({ title: 1 })

db.movies.find(
  { year: { $gte: 2000 } },
  { _id: 0, title: 1, year: 1 }
).sort({ year: -1 })

Use a trusted local certificate instead

If you want certificate validation instead of --tlsAllowInvalidCertificates, copy the generated certificate from the container and pass it to mongosh.

docker cp documentdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem

mongosh localhost:10260 \
  -u <YOUR_USERNAME> \
  -p <YOUR_PASSWORD> \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls \
  --tlsCAFile ~/documentdb-cert.pem

Troubleshooting and debugging

If mongosh does not connect on the first try:

  • Verify the local DocumentDB instance is running before you connect
  • If you used Docker, check docker ps --filter "name=documentdb" and docker logs documentdb
  • If you used Linux packages, check sudo systemctl status documentdb-gateway and sudo journalctl -u documentdb-gateway --no-pager -n 50
  • If authentication fails, confirm the username and password you used when you started DocumentDB or ran documentdb-setup
  • If TLS validation fails, either keep --tlsAllowInvalidCertificates for the default local self-signed setup or switch to --tlsCAFile with a trusted certificate
  • If mongosh is not installed, follow the mongosh install guide
  • Use Python Quick Start or Node.js Quick Start to verify the same endpoint from an application driver

Next steps