Setting up MongoDB for local development

This guide gets MongoDB running on your own computer and shows you how to connect to it and test against it. We also set things up so a coding agent can start and reset the database on its own, since you'll probably be working with one.

Follow the numbered steps in order and you'll be set up. In step 1, you'll open the section for your operating system and follow it. Every other collapsed section, like the one below, is optional background.

1. Install Podman and Compose

We'll run MongoDB inside a container. A container bundles a program with everything it needs to run, so MongoDB behaves the same way on every computer in the class. Containers start from images, which are packaged programs you download once. To run containers we use Podman, which works on macOS, Windows, and Linux. We also install Compose, which lets you describe your containers in a file instead of typing long commands. Podman uses the same images and Compose files as Docker, another popular container tool, so you'll see the name Docker in a few places.

Open the section for your operating system and follow its steps. Unlike the other collapsed sections, this one is required.

# Ubuntu and Debian
sudo apt-get update && sudo apt-get install -y podman podman-compose

# Fedora
sudo dnf install -y podman podman-compose

# Arch
sudo pacman -S podman podman-compose

systemctl --user enable --now podman.socket

Now check that both work:

podman run --rm docker.io/library/hello-world
podman compose version

The first command should print a message starting with "Hello from Docker!" That's expected, since the image comes from Docker Hub. The second should print a version number. Podman may also mention that it's running an external compose provider, which is normal.

2. Start MongoDB

For this guide, you'll work in a new, empty practice folder. Create one and move into it:

mkdir mongo-practice
cd mongo-practice

Run the rest of the commands in this guide from inside this folder. Now create a file called compose.yaml here:

services:
  mongo:
    image: docker.io/library/mongo:8.0
    ports:
      - "127.0.0.1:27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: dev
      MONGO_INITDB_ROOT_PASSWORD: dev
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

This file describes one container, called mongo:

• image is MongoDB 8.0 from Docker Hub.
• ports makes MongoDB's port, 27017, reachable from your computer only.
• environment creates a user named dev with the password dev the first time MongoDB starts. After that, every connection has to log in.
• volumes keeps MongoDB's data in a volume named mongo-data, outside the container, so it's still there after the container stops. The empty mongo-data: at the bottom is on purpose. It tells Compose to create that volume with the default settings.

Start it:

podman compose up -d

The first run takes a little while because Podman has to download the image. The -d flag runs MongoDB in the background. To check that it's up, ask it for a ping:

podman compose exec mongo mongosh --quiet --eval "db.runCommand({ ping: 1 })"

If you see { ok: 1 }, you're all set. If you get a connection error, MongoDB is probably still starting, so wait a few seconds and try again.

These are the commands you'll use most:

podman compose stop       # stop MongoDB, keeping your data
podman compose up -d      # start it again
podman compose logs       # see what it has printed
podman compose down -v    # delete the container and all its data

After you restart your computer, start the Podman machine if you're on macOS or Windows, then run podman compose up -d. In step 4 we'll turn these commands into short scripts.

podman run -d --name mongo -p 127.0.0.1:27017:27017 -e MONGO_INITDB_ROOT_USERNAME=dev -e MONGO_INITDB_ROOT_PASSWORD=dev -v mongo-data:/data/db docker.io/library/mongo:8.0

podman compose exec mongo mongosh -u dev -p dev

3. Connect from your code

The rest of this guide uses Bun to run TypeScript. If you don't have it yet, follow the install instructions on the Bun website, then check that bun --version prints a version number.

Turn your practice folder into a Bun project, then add the official MongoDB driver:

bun init -y
bun add mongodb

bun init creates a package.json, a TypeScript config, and a few starter files next to your compose.yaml. The -y accepts the defaults without asking any questions.

Next, tell your app where to find the database. Create a file called .env in the same folder with this line:

MONGODB_URL=mongodb://dev:dev@127.0.0.1:27017/myapp?authSource=admin

The dev:dev part is the username and password from compose.yaml. The /myapp part names the database, and authSource=admin tells MongoDB where to check the credentials, because the container's user belongs to the admin database. Bun reads .env automatically whenever it runs your code, and the value shows up as process.env.MONGODB_URL.

Also save the same line in a file called .env.example. Your .env stays on your computer, since the .gitignore that bun init created already lists it. .env.example is the copy you commit, so teammates and agents know what to put in their own .env.

Now let's make sure your code can reach MongoDB. Create a folder called scripts, and save this in it as check-db.ts:

import { MongoClient } from "mongodb";

const url = process.env.MONGODB_URL ?? "mongodb://127.0.0.1:27017/myapp";
// With --wait, keep trying for 30 seconds. That gives a fresh container time to start.
const timeout = process.argv.includes("--wait") ? 30_000 : 3_000;
const client = new MongoClient(url, { serverSelectionTimeoutMS: timeout });

try {
  await client.connect();
  const db = client.db();
  await db.command({ ping: 1 });
  const checks = db.collection("setup_checks");
  await checks.insertOne({ at: new Date() });
  console.log(`Connected to ${db.databaseName}. It has ${await checks.countDocuments()} check(s).`);
} catch (error) {
  console.error(`Could not reach MongoDB at ${url}`);
  console.error(error instanceof Error ? error.message : error);
  process.exitCode = 1;
} finally {
  await client.close();
}

Then run it:

bun scripts/check-db.ts

You should see Connected to myapp. It has 1 check(s). Here myapp is the database named in the connection string. client.db() with no name uses that database, so the code works unchanged when a deployed app gets a different connection string. MongoDB creates the database the first time you write to it. In a real project, you'd name it after the project. Run it again and the count goes up, which tells you the data is being saved. If something's wrong, it prints "Could not reach MongoDB" along with the reason. By default it gives up after three seconds. With --wait, it keeps trying for thirty seconds, which step 4 uses.

The script is a one-off check. In your actual app, create one client when the app starts and share it everywhere. The client keeps a pool of connections open and reuses them, so making a new client for every request is slow and can run out of connections. Create a folder called src, and save this in it as db.ts. The example below uses it.

import { MongoClient } from "mongodb";

const url = process.env.MONGODB_URL;
if (!url) {
  throw new Error("MONGODB_URL is not set. Add it to your .env file.");
}

export const client = new MongoClient(url);
export const db = client.db();

Other files in src can then import { db } from "./db.ts" and use db.collection(...). You don't need to call connect() yourself. The driver connects the first time you run a query.

A small example

Here's an example based on the restaurant reservations from the Designing State lecture. A user can reserve a resource, like a table at a certain time, and claim the reservation when they show up. The rule that matters is that a resource can't be reserved twice, and a unique index in MongoDB enforces it. Reservations live in a collection named reserving.reservations. The dot is just part of the name. We'll also test this class in step 5. Save it as src/reserving.ts:

import { MongoServerError, type Collection, type Db } from "mongodb";

export interface Reservation {
  _id: string;
  user: string;
  resource: string;
  claimed: boolean;
}

export class Reserving {
  private readonly reservations: Collection<Reservation>;
  private readonly ready: Promise<string>;

  constructor(db: Db) {
    this.reservations = db.collection<Reservation>("reserving.reservations");
    // The unique index stops a resource from being reserved twice.
    this.ready = this.reservations.createIndex({ resource: 1 }, { unique: true });
  }

  async reserve(user: string, resource: string): Promise<string> {
    await this.ready;
    const reservation: Reservation = { _id: crypto.randomUUID(), user, resource, claimed: false };
    try {
      await this.reservations.insertOne(reservation);
    } catch (error) {
      if (error instanceof MongoServerError && error.code === 11000) {
        throw new Error(`${resource} is already reserved`);
      }
      throw error;
    }
    return reservation._id;
  }

  async claim(id: string): Promise<void> {
    const result = await this.reservations.updateOne({ _id: id, claimed: false }, { $set: { claimed: true } });
    if (result.matchedCount === 0) {
      throw new Error("No unclaimed reservation with that id");
    }
  }

  async cancel(id: string): Promise<void> {
    const result = await this.reservations.deleteOne({ _id: id, claimed: false });
    if (result.deletedCount === 0) {
      throw new Error("No unclaimed reservation with that id");
    }
  }

  async forUser(user: string): Promise<Reservation[]> {
    return this.reservations.find({ user }).toArray();
  }
}

To try it, save this as scripts/try-reserving.ts:

import { client, db } from "../src/db.ts";
import { Reserving } from "../src/reserving.ts";

const reserving = new Reserving(db);

try {
  const id = await reserving.reserve("barish", "friday-7pm-table-4");
  console.log("barish reserved friday-7pm-table-4");
  await reserving.claim(id);
  console.log("barish claimed the reservation");
} catch (error) {
  console.log(`barish: ${(error as Error).message}`);
}

try {
  await reserving.reserve("eagon", "friday-7pm-table-4");
  console.log("eagon reserved friday-7pm-table-4");
} catch (error) {
  console.log(`eagon: ${(error as Error).message}`);
}

try {
  await reserving.reserve("carmel", "friday-8pm-table-4");
  console.log("carmel reserved friday-8pm-table-4");
} catch (error) {
  console.log(`carmel: ${(error as Error).message}`);
}

console.log(await reserving.forUser("barish"));
await client.close();

Run it with bun scripts/try-reserving.ts. Barish reserves the table and claims it, Eagon is turned away because the table is taken, and Carmel gets the 8pm table. Run it again, and this time everyone is turned away, because the reservations from the last run are still in the database.

4. Make it one command

You and your agent will start, check, and reset the database a lot. Instead of remembering the commands, give them short names. Open package.json and paste this right after the first { line:

  "scripts": {
    "db:up": "podman compose up -d && bun scripts/check-db.ts --wait",
    "db:down": "podman compose down",
    "db:reset": "podman compose down -v && bun run db:up",
    "db:logs": "podman compose logs mongo",
    "db:shell": "podman compose exec mongo mongosh -u dev -p dev",
    "db:check": "bun scripts/check-db.ts"
  },

Try it:

bun run db:up

This starts MongoDB and then runs the check script with --wait, so the command only finishes once the database is ready to use. You should see Connected to myapp at the end.

The other scripts do the following:

• db:down stops and removes the container. Your data stays in the volume.
• db:reset also deletes the volume, then starts MongoDB again with an empty database.
• db:logs shows what MongoDB has printed.
• db:shell opens mongosh, already logged in.
• db:check runs the connection check by itself.

When you start your real project, copy compose.yaml, .env.example, scripts/check-db.ts, and these scripts into it. Anyone who clones it can then copy .env.example to .env, run bun run db:up, and get the same database.

Finally, tell your agent about these scripts. Agents look for instructions in a file called AGENTS.md at the root of your project. A short section is enough:

## Database

This project uses MongoDB, defined in `compose.yaml`. The connection string is in `.env`.

- `bun run db:up` starts MongoDB and waits until it accepts connections.
- `bun run db:check` checks that the app can connect.
- `bun run db:reset` deletes all local data and starts fresh. It is safe to run at any time.
- `bun run db:logs` shows MongoDB's output.
- Only use the local database. Never connect to a hosted one.

5. Test against MongoDB

We give each test file its own fresh database with a random name, so tests never touch the data in myapp, and two test runs never get in each other's way.

The helper below has two modes. By default, tests use the real MongoDB that bun run db:up starts. In memory mode, which you turn on with TEST_MONGO=memory, they start a temporary MongoDB just for the test run. Memory mode is useful when you can't run a container, like in a cloud workspace or on an automated test server, or when your computer is low on memory. You won't need it otherwise, but we'll try it once so you know it works.

The temporary MongoDB comes from the mongodb-memory-server package. Add it to your project:

bun add -d mongodb-memory-server

Then create a folder called tests, and save this helper in it as test-db.ts:

import { MongoClient, type Db } from "mongodb";
import { MongoMemoryServer } from "mongodb-memory-server";

export interface TestDb {
  db: Db;
  close(): Promise<void>;
}

// Opens a fresh database for one test file. By default it uses the real MongoDB
// from compose.yaml. Set TEST_MONGO=memory to start a temporary MongoDB instead.
export async function openTestDb(): Promise<TestDb> {
  let url = process.env.MONGODB_URL;
  let server: MongoMemoryServer | undefined;

  if (process.env.TEST_MONGO === "memory") {
    server = await MongoMemoryServer.create();
    url = server.getUri();
  }
  if (!url) {
    throw new Error("MONGODB_URL is not set. Add it to .env, or run `bun run test:memory` instead.");
  }

  const client = new MongoClient(url, { serverSelectionTimeoutMS: 3000 });
  try {
    await client.connect();
  } catch {
    throw new Error("Could not reach MongoDB. Start it with `bun run db:up`, or run `bun run test:memory` instead.");
  }
  const db = client.db(`test-${crypto.randomUUID()}`);

  return {
    db,
    async close() {
      await db.dropDatabase();
      await client.close();
      await server?.stop();
    },
  };
}

Now write a few tests for the Reserving class from step 3. Save this as tests/reserving.test.ts:

import { afterAll, beforeAll, beforeEach, expect, test } from "bun:test";
import { Reserving } from "../src/reserving.ts";
import { openTestDb, type TestDb } from "./test-db.ts";

let testDb: TestDb;
let reserving: Reserving;

beforeAll(async () => {
  testDb = await openTestDb();
}, 120_000);

beforeEach(async () => {
  await testDb.db.dropDatabase();
  reserving = new Reserving(testDb.db);
});

afterAll(async () => {
  await testDb.close();
});

test("a table can only be reserved once", async () => {
  await reserving.reserve("barish", "table-4");
  await expect(reserving.reserve("eagon", "table-4")).rejects.toThrow("table-4 is already reserved");
});

test("when two people reserve at the same moment, only one gets the table", async () => {
  const results = await Promise.allSettled([
    reserving.reserve("barish", "table-4"),
    reserving.reserve("eagon", "table-4"),
  ]);
  const succeeded = results.filter((result) => result.status === "fulfilled");
  expect(succeeded).toHaveLength(1);
});

test("a reservation can only be claimed once", async () => {
  const id = await reserving.reserve("barish", "table-4");
  await reserving.claim(id);
  await expect(reserving.claim(id)).rejects.toThrow("No unclaimed reservation");
});

test("a claimed reservation can't be cancelled", async () => {
  const id = await reserving.reserve("barish", "table-4");
  await reserving.claim(id);
  await expect(reserving.cancel(id)).rejects.toThrow("No unclaimed reservation");
});

test("cancelling frees the table for someone else", async () => {
  const id = await reserving.reserve("barish", "table-4");
  await reserving.cancel(id);
  await expect(reserving.reserve("carmel", "table-4")).resolves.toBeString();
});

beforeAll opens the test database once for the whole file. beforeEach empties it and creates a fresh Reserving, which builds the unique index again, so every test starts from nothing. afterAll deletes the test database and closes the connection. The long timeout on beforeAll is for memory mode, because the very first run downloads MongoDB, and that takes longer than Bun's default of five seconds.

The second test is the interesting one. It makes two reservations for the same table at the same moment and checks that only one of them succeeds.

Next, add two lines to the scripts section of package.json, right after the db:check line. Put a comma at the end of the db:check line first:

    "test": "bun test",
    "test:memory": "TEST_MONGO=memory bun test"

Run the tests against the real MongoDB:

bun run db:up
bun run test

You should see 5 pass and 0 fail. Now try memory mode. It doesn't need the container, so you can stop it first with bun run db:down if you like:

bun run test:memory

The first time, this downloads MongoDB, which can take a minute. After that the download is cached, and the tests should pass the same way.

Add both commands to the AGENTS.md section from step 4, so your agent knows how to run the tests:

- `bun run test` runs the tests against the local MongoDB. Run `bun run db:up` first.
- `bun run test:memory` runs the tests with a temporary MongoDB and needs no container.