---
title: MongoDB
description: Give Bapx agents and workflow runs durable, shared state with MongoDB.
package:
  name: '@bapX/mongodb'
  href: https://www.npmjs.com/package/@bapX/mongodb
---

## Quickstart

Add durable, shared state to an existing Bapx project with the [MongoDB](https://www.mongodb.com) blueprint. Run the following command in your terminal or coding agent of choice:

```sh
bapX add database mongodb
```

## Overview

The MongoDB blueprint installs `@bapX/mongodb` and the official `mongodb`
driver, creates a complete `db.ts` runner in the project's source-root, and
follows the project's existing secret convention for `MONGODB_URL` and
`MONGODB_DATABASE`. The generated adapter connects the driver, selects the
database, and passes a project-owned runner to `mongodb()`:

```ts title="src/db.ts (abridged)"
import { mongodb, type MongoOperations, type MongoRunner } from '@bapX/mongodb';
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URL!);
await client.connect();

const db = client.db(process.env.MONGODB_DATABASE);
const runner: MongoRunner = {
  /* ... */
};

export default mongodb(runner);
```

The blueprint does not modify the MongoDB deployment, which must support
transactions. Bapx discovers the adapter during a Node build
and persists canonical agent conversations, immutable attachments, accepted submissions, workflow runs, and event streams so that state survives process replacement. Replicas may share durable state and workflow history, but each agent instance still requires one live Node owner. Application business data remains application-owned.

## Configure

| Variable           | Purpose                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `MONGODB_URL`      | **Required** — MongoDB connection string, including credentials and TLS options when required.                        |
| `MONGODB_DATABASE` | **Optional** — Explicit database name for Bapx state; recommended when the URL does not select the intended database. |

The official driver reads these values at runtime. Never commit credentials.
For local development, `bapX dev --env <file>` and `bapX run --env <file>` load
any `.env`-format file; use the deployment platform's secret store in
production.

`client.db(undefined)` can select the database from the connection string (or
the driver's default), but setting `MONGODB_DATABASE` explicitly avoids an
ambiguous deployment. Prefer a dedicated database. If Bapx must share one, pass
a stable unique `collectionPrefix` to `mongodb()`; changing it selects a new
namespace rather than moving existing data.

The blueprint installs `@bapX/mongodb` and the official `mongodb` driver, then
writes a complete source-root `db.ts` runner. Bapx discovers the file at build
time and wires the adapter into the generated Node server.

This is a **Node.js** adapter. The Cloudflare target uses Durable Object SQLite
and rejects `db.ts`, so MongoDB is not used on that target. See
[Database](/guide/database/) for target-specific persistence behavior.

## Choose a supported deployment

MongoDB transactions require one of these deployments:

- MongoDB Atlas;
- a replica set;
- a transaction-capable sharded cluster; or
- a single-node replica set.

A standalone `mongod` is unsupported. Migration checks the topology before
creating collections or stamping the Bapx schema version and fails when the
deployment cannot run transactions.

For local development, a single-node replica set is one MongoDB server started
with replica-set mode enabled and initialized once as a one-member set. Follow
the instructions for your existing installation or container setup; the
production requirements and operational tradeoffs remain those of a replica
set.

## Transactions and the driver runner

`@bapX/mongodb` exposes a small driver seam rather than bundling a production
client. The generated `db.ts` wraps the official driver with all collection
operations, topology inspection, collection and index management, transactions,
and `close()`.

Each transaction uses one `ClientSession`, snapshot read concern, and majority
write concern. Callback operations are session-bound and serialized because the
driver does not support parallel operations inside one transaction. The runner
uses separate bounded retry loops: it reruns the full callback for
`TransientTransactionError`, while `UnknownTransactionCommitResult` retries
only `commitTransaction()`. This avoids repeating application work when only the
commit outcome is uncertain.

Keep the complete generated runner when adapting connection options. In
particular, do not replace transaction collections with database-level
collections or remove the operation queue.

## Migrations and indexes

Bapx calls `migrate()` automatically at server startup. After validating the
topology, migration creates collections with strict validators and creates the
required indexes. It then inspects the actual validator, validation level and
action, plus each required index's key, uniqueness, partial filter, and
collation before writing the schema version. Incompatible definitions and data
written by a newer Bapx version stop startup. There is no separate migration
command.

## Large values and staged writes

MongoDB limits a BSON document to 16 MiB. The adapter JSON-serializes arbitrary
runtime values and stages them as immutable parts bounded to 4 MiB. A short
transaction publishes the completed generation and its manifest, so large
values are never made visible partially. Abandoned staged generations and
retired values are collected later.

Images keep Bapx's persisted chunk representation and use the same staged value
path. Avoid putting large runtime values directly into custom MongoDB documents;
that bypasses the adapter's BSON-limit handling.

## What gets stored

MongoDB stores append-only canonical conversation records, immutable attachment payloads, accepted direct and dispatched submissions, recovery claims and leases, workflow runs and indexes, and persisted event streams. Sessions append for the agent-instance lifetime; there are no session generations, transcript snapshots, per-session deletion, or recursive session-tree cleanup.

The adapter does not store sandbox files, external API side effects, credentials,
or application-owned business records.

## Verify

Build the Node target and start it with `MONGODB_URL` and `MONGODB_DATABASE`
pointing at a throwaway supported deployment. Confirm migration creates the
collections and indexes, create state, restart Bapx, and verify the state
reloads. Exercise a value larger than 4 MiB to cover multipart staging. A
throwaway standalone `mongod` should fail migration before the schema version is
stamped. Do not verify against a production database.