MongoDB Adapter

Overview

The MongoDB adapter connects to a MongoDB server for durable, document-oriented storage. It supports all Bounda storage concerns and is a production-ready alternative to PostgreSQL.

Installation

npm i @bounda-dev/adapter-mongodb

Once installed, the adapter is discovered automatically at runtime via Bounda’s adapter discovery mechanism.

Supported Features

Feature	Supported
Event Store	Yes
Read Model	Yes
Policy DLQ	Yes
Process Manager DLQ	Yes
Scheduling	Yes

When to Use

Applications with MongoDB infrastructure — Reuse your existing MongoDB deployment.
Document-oriented read models — Filtering, sorting, pagination, and nested document queries.
Production deployments — Full durability and concurrent access.

Configuration

Every MongoDB configuration requires a url (connection string) and a dbName (database name). Bounda creates the collections and indexes automatically on first boot.

Event Store

domain: {
  user: {
    eventStore: {
      type: "mongodb",
      url: process.env.MONGODB_URL,
      dbName: "bounda",
    },
  },
}

Read Model

read: {
  "users-directory": {
    type: "mongodb",
    url: process.env.MONGODB_URL,
    dbName: "bounda",
  },
}

Scheduling

domain: {
  user: {
    scheduling: {
      type: "mongodb",
      url: process.env.MONGODB_URL,
      dbName: "bounda",
    },
  },
}

Process Manager DLQ

domain: {
  user: {
    processManagers: {
      dlq: {
        type: "mongodb",
        url: process.env.MONGODB_URL,
        dbName: "bounda",
      },
    },
  },
}

Policy DLQ

domain: {
  user: {
    policies: {
      dlq: {
        type: "mongodb",
        url: process.env.MONGODB_URL,
        dbName: "bounda",
      },
    },
  },
}

Option	Type	Description
`type`	`"mongodb"`	Adapter type
`url`	`string`	MongoDB connection URL (e.g., `mongodb://user:pass@host:27017`)
`dbName`	`string`	Database name

Query API

Queries against a MongoDB read model have access to MongoDB-style operations:

export const handler: Query.HandlerFunction = async ({ db }) => {
  const users = await db
    .collection("users")
    .find({ status: "active" })
    .sort({ createdAt: -1 })
    .skip(0)
    .limit(10)
    .toArray();

  return users;
};

Environment Variables

Using environment variables for connection details keeps secrets out of your codebase:

import type { Config } from "@bounda-dev/config";

export default {
  domain: {
    user: {
      eventStore: {
        type: "mongodb",
        url: process.env.MONGODB_URL,
        dbName: "bounda",
      },
      scheduling: {
        type: "mongodb",
        url: process.env.MONGODB_URL,
        dbName: "bounda",
      },
      processManagers: {
        dlq: {
          type: "mongodb",
          url: process.env.MONGODB_URL,
          dbName: "bounda",
        },
      },
    },
  },
  read: {
    "users-directory": {
      type: "mongodb",
      url: process.env.MONGODB_URL,
      dbName: "bounda",
    },
  },
} satisfies Config;

Testing

Integration tests for the MongoDB adapter use TestContainers to spin up a real mongo:7 instance. A single container is shared across all test suites via vitest’s globalSetup; each suite gets its own database for isolation.

To run the tests locally, Docker must be running:

npm test --workspace=@bounda-dev/adapter-mongodb

Adapters Overview — Comparison of all available adapters
SQLite — Lightweight alternative for development
PostgreSQL — Production-grade relational alternative
Configuration Reference — Full config reference