Installing and connecting to MongoDB

This chapter follows A short history of MongoDB. The examples assume MongoDB Server 8.0.x, the Node.js driver 7.8.x, and Node.js 20+. Pin versions in your own projects and check the driver compatibility table when you upgrade the server.

Run MongoDB in Docker

For local development, the community server image is enough for CRUD, aggregation, and geospatial exercises in this series:

1
docker pull mongodb/mongodb-community-server:8.0-ubuntu2204
2
docker run --name mongo-dev -p 27017:27017 \
3
  -e MONGO_INITDB_ROOT_USERNAME=dev \
4
  -e MONGO_INITDB_ROOT_PASSWORD=devpass \
5
  -d mongodb/mongodb-community-server:8.0-ubuntu2204

Verify with mongosh (install from MongoDB Download Center):

1
mongosh "mongodb://dev:devpass@localhost:27017/admin" --eval "db.runCommand({ ping: 1 })"

Create a free Atlas cluster

1. Sign up at MongoDB Atlas.
2. Create an M0 free cluster in a region close to you.
3. Add a database user and note the username and password.
4. Under Network Access, allow your IP (or 0.0.0.0/0 only for short-lived experiments).
5. Copy the connection string from Connect → Drivers.

Install the Atlas CLI if you prefer terminal workflows (Atlas CLI docs):

1
curl -sSf https://fastdl.mongodb.org/mongocli/mongodb-atlas-cli_latest_linux_x86_64.tar.gz | tar -xz
2
# move atlas binary to your PATH, then:
3
atlas auth login
4
atlas clusters list

Atlas URIs look like mongodb+srv://USER:PASS@cluster0.example.mongodb.net/myApp?retryWrites=true&w=majority. The mongodb+srv form resolves replica set members from DNS; the driver handles TLS automatically.

Install the Node.js driver

In your TypeScript project:

1
pnpm add mongodb
2
pnpm add -D typescript @types/node

The mongodb package ships its own TypeScript types; you do not need @types/mongodb.

Connection string anatomy

Store secrets in environment variables, not source control:

1
export MONGODB_URI="mongodb://dev:devpass@localhost:27017/myapp?authSource=admin"

A typed client module

Reuse one MongoClient per process. The driver pools connections internally.

1
import { MongoClient, Db } from 'mongodb';
2

3
const uri = process.env.MONGODB_URI;
4
if (!uri) {
5
  throw new Error('MONGODB_URI is not set');
6
}
7

8
const client = new MongoClient(uri, {
9
  maxPoolSize: 20,
10
  serverSelectionTimeoutMS: 5_000,
11
  socketTimeoutMS: 45_000,
12
});
13

14
let connectPromise: Promise<MongoClient> | undefined;
15

16
export async function getClient(): Promise<MongoClient> {
17
  if (!connectPromise) {
18
    connectPromise = client.connect().then(() => client);
19
  }
20
  return connectPromise;
21
}
22

23
export async function getDb(name = process.env.MONGODB_DB ?? 'myapp'): Promise<Db> {
24
  const c = await getClient();
25
  return c.db(name);
26
}
27

28
export async function closeClient(): Promise<void> {
29
  if (connectPromise) {
30
    await client.close();
31
    connectPromise = undefined;
32
  }
33
}

Ping after connect in health checks:

1
import { getClient } from './client.js';
2

3
export async function pingMongo(): Promise<boolean> {
4
  const client = await getClient();
5
  await client.db('admin').command({ ping: 1 });
6
  return true;
7
}

Graceful shutdown

Register shutdown hooks so in-flight operations finish before the process exits:

1
import { closeClient } from './db/client.js';
2

3
async function shutdown(signal: string) {
4
  console.log(`Received ${signal}, closing MongoDB client`);
5
  await closeClient();
6
  process.exit(0);
7
}
8

9
process.on('SIGINT', () => void shutdown('SIGINT'));
10
process.on('SIGTERM', () => void shutdown('SIGTERM'));

Next: Authentication in MongoDB.