MongoDB Adapter

The MongoDB adapter gives Node-target Flue applications durable, shared state backed by a MongoDB deployment that can run transactions. Use it when accepted agent submissions, workflow runs, conversation streams, event streams, and attachments must survive process replacement or be visible to multiple Node replicas. The adapter is not an application data model; it owns Flue runtime state while your product data stays in your own collections or services. The official database page frames this as a blueprint-driven setup that adds persistence without changing the shape of agents, workflows, channels, or tools.

Sources: apps/docs/src/content/docs/ecosystem/databases/mongodb.md, packages/mongodb/README.md

Purpose and Scope

The fastest path is the MongoDB database blueprint. It installs the adapter package and the official MongoDB driver, then writes a source-root database runner that Flue discovers during a Node build. The generated shape connects a driver client, selects a database from secrets, constructs a runner, and passes that runner into the adapter factory. That generated file is intentionally project-owned because connection options, TLS, credentials, retry policy, and deployment conventions belong to the application rather than to the adapter package.

Sources: apps/docs/src/content/docs/ecosystem/databases/mongodb.md, packages/mongodb/README.md

flue add database mongodb

import { mongodb, type MongoOperations, type MongoRunner } from '@flue/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 = {
  /* project-owned MongoDB operations and transaction implementation */
};
 
export default mongodb(runner);

Relevant Source Files

• apps/docs/src/content/docs/ecosystem/databases/mongodb.md — first-party MongoDB database guide, blueprint command, environment variables, deployment requirements, Node-target note, and collection prefix guidance.
• packages/mongodb/README.md — package-level install and runner example, including transaction, session, retry, and topology responsibilities for driver-backed adapters.
• packages/mongodb/src/mongodb-adapter.ts — adapter factory implementation, migration sequencing, topology rejection, schema version stamping, migration lease, and store wiring.
• packages/mongodb/src/schema.ts — canonical collection names, validators, strict validation settings, and indexes created or verified during migration.
• packages/mongodb/src/submission-store.ts — MongoDB-backed implementation of the agent submission lifecycle, including admission, readiness, runnable ordering, running attempts, and leases.

Configuration and Target Fit

Configure the driver with a required connection string and, preferably, an explicit database name. The documented variables are MONGODB_URL for credentials, hosts, TLS, and driver options, and MONGODB_DATABASE for the database that holds Flue state. If the database name is omitted, the driver may select one from the URL or its default behavior, but an explicit value avoids accidental writes to an unintended database. The docs also recommend a dedicated database, or a stable adapter collection prefix when Flue must share a database namespace.

Sources: apps/docs/src/content/docs/ecosystem/databases/mongodb.md, packages/mongodb/src/mongodb-adapter.ts

The adapter is specific to the Node target. The database guide states that the Cloudflare target uses Durable Object SQLite and rejects a project database file, so MongoDB configuration should be treated as part of Node deployment and local Node development. For development commands, the guide points to environment-file loading through the Flue development and run commands, while production should rely on the hosting platform secret store. Never bake MongoDB credentials into source-controlled configuration because the official driver reads these values at runtime.

Sources: apps/docs/src/content/docs/ecosystem/databases/mongodb.md

Runner Contract and Transactions

The package deliberately does not hide the MongoDB driver behind an internal connection manager. Instead, the application supplies a runner with collection operations and a transaction helper. The README example shows the runner mapping each collection method to driver calls and threading one client session into every operation inside a transaction. It also queues callback operations sequentially, which matters because transaction callbacks must not issue unordered overlapping operations through the same session. This design lets applications keep control of connection pooling, observability, credentials, and deployment-specific driver configuration.

Sources: packages/mongodb/README.md

MongoDB transactions are not optional for this adapter. The runner must use snapshot read concern, majority write concern, a single session per transaction callback, bounded whole-transaction retries for transient transaction errors, and commit-only retries when the driver reports an unknown transaction commit result. The runner also exposes topology information so migration can reject unsupported deployments before creating or stamping Flue collections. Supported deployments include Atlas, replica sets, transaction-capable sharded clusters, and single-node replica sets for local development; standalone servers are rejected.

Sources: apps/docs/src/content/docs/ecosystem/databases/mongodb.md, packages/mongodb/README.md, packages/mongodb/src/mongodb-adapter.ts

Migration, Schema Stamping, and Namespacing

The adapter factory returns a persistence adapter with migration and connection phases. Migration clears its internal migrated flag, reads the metadata collection, checks any existing schema version, rejects unversioned data, validates topology, ensures the metadata collection, and then acquires a migration lock. The implementation uses a generated owner identifier, a thirty-second lease, and periodic renewal while schema work runs. If ownership is lost, migration fails instead of letting two processes race on validation, indexes, or schema version state.

Sources: packages/mongodb/src/mongodb-adapter.ts

Schema stamping is intentionally strict. The schema module derives all collection names from a prefix, defaulting to a Flue namespace, and defines strict JSON schema validation requiring an identifier field. It then verifies collection validators, validation level, validation action, and named indexes against canonical expected forms. Collections cover metadata, counters, value chunks and generations, submissions, attempt markers, workflow runs, conversation streams and batches, attachments, event streams, and event entries. Several indexes use simple collation, uniqueness, ordering, or partial filters to preserve durable ordering and idempotency semantics.

Sources: packages/mongodb/src/schema.ts, packages/mongodb/src/mongodb-adapter.ts

Store Responsibilities

After a successful migration, connect() exposes the stores expected by the runtime persistence contract. The adapter wires the submission store under the execution store and also constructs run, event stream, conversation stream, and attachment stores. Submission state is particularly important because accepted work must be admitted once, ordered, claimed, recovered, and settled without losing the canonical conversation or attachments. The MongoDB submission store therefore separates queued, running, and terminalizing work, tracks canonical readiness, and returns runnable heads by session key so one session does not overtake another.

Sources: packages/mongodb/src/mongodb-adapter.ts, packages/mongodb/src/submission-store.ts

The submission store also demonstrates how the adapter uses transactions for state transitions that must be atomic. Replacing a running attempt happens inside the runner transaction and updates the attempt identifier, recovery timestamp, start time, optional lease owner, lease expiration, and attempt count in one operation. Admission supports both dispatch and direct inputs, and direct admission throws if a conflict produces something other than a concrete submission. The code imports runtime helpers for storage keys, default durability attempts, default timeout, lease duration, attachment preparation, and payload validation, showing that MongoDB stores implement the shared runtime contract rather than inventing separate semantics.

Sources: packages/mongodb/src/submission-store.ts

Compact Reference

Next Steps

Start with the blueprint unless you already have a custom MongoDB runner convention. Verify the deployment supports transactions before first boot, choose a dedicated database or stable prefix, and keep secrets in environment files or platform secret storage. If migration fails, inspect topology support, schema version compatibility, and whether existing collections were created by the same Flue schema. For a broader view of how adapters fit into generated Node applications, read the database guide and the data persistence API reference next.