---
title: "MongoDB"
description: "Use Blyp's Mongoose database adapter to persist normalized logs into MongoDB."
canonical_url: "https://www.blyp.dev/docs/database/mongodb"
markdown_url: "https://www.blyp.dev/docs/database/mongodb.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
agent:
  task: "Configure the Blyp Mongoose adapter and persist normalized logs to MongoDB."
  outcome: "A flushed test log appears in the configured MongoDB collection with expected indexes."
  appliesTo:
    package:
      - "@blyp/core"
      - "mongoose"
  prerequisites:
    - "A MongoDB deployment is reachable and Mongoose can connect to it."
  files:
    - "blyp.config.ts"
    - "src/db/mongoose.ts"
  commands:
    - "pnpm add @blyp/core mongoose"
  sideEffects:
    - "Blyp writes documents and creates or relies on collection indexes."
  verification:
    - "Emit and flush a test log"
    - "then query the configured collection for it."
  rollback:
    - "Restore the previous destination and disconnect the Blyp adapter cleanly."
  failureModes:
    - symptom: "The adapter cannot load from configuration."
      resolution: "Use an executable blyp.config file because JSON cannot contain a live Mongoose adapter."
---

# MongoDB
URL: /docs/database/mongodb
LLM index: /llms.txt
Description: Use Blyp's Mongoose database adapter to persist normalized logs into MongoDB.
Related: /docs/database, /docs/database/schema, /docs/database/troubleshooting

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Configure the Blyp Mongoose adapter and persist normalized logs to MongoDB.
Outcome: A flushed test log appears in the configured MongoDB collection with expected indexes.

### Applies To

- Package: `@blyp/core`, `mongoose`

### Prerequisites

- A MongoDB deployment is reachable and Mongoose can connect to it.

### Files

- `blyp.config.ts`
- `src/db/mongoose.ts`

### Commands

- `pnpm add @blyp/core mongoose`

### Side Effects

- Blyp writes documents and creates or relies on collection indexes.

### Verification

- Emit and flush a test log
- then query the configured collection for it.

### Rollback

- Restore the previous destination and disconnect the Blyp adapter cleanly.

### Failure Modes

- The adapter cannot load from configuration. — Recovery: Use an executable blyp.config file because JSON cannot contain a live Mongoose adapter.
<!-- farming-labs:agent-contract:end -->

# MongoDB

Connect Mongoose first, create the documented Blyp adapter in an executable config, and verify a
flushed record in the target collection. Do not use `blyp.config.json` for database adapters. If the
adapter cannot load, move configuration to TypeScript or JavaScript before investigating MongoDB.

Use this path when your project stores Blyp logs in MongoDB through Mongoose.

This is database persistence, not connector forwarding. Blyp writes normalized database rows into a MongoDB collection when `destination: "database"` is enabled.

## Prerequisites

- `mongoose` installed
- a MongoDB deployment available
- an executable Blyp config file such as `blyp.config.ts` or `blyp.config.js`
- no `blyp.config.json`, because database adapters need runtime objects

## Install

```bash
bun add mongoose
```

## Config with a Mongoose instance

```ts
import mongoose from "mongoose";
import { createMongooseDatabaseAdapter } from "@blyp/core/database";

export default {
  destination: "database",
  database: {
    adapter: createMongooseDatabaseAdapter({
      mongoose,
      mongoUrl: process.env.MONGODB_URI,
      collection: "blyp_logs",
    }),
  },
};
```

## Config with an existing connection

```ts
import mongoose from "mongoose";
import { createMongooseDatabaseAdapter } from "@blyp/core/database";

const connection = mongoose.connection;

export default {
  destination: "database",
  database: {
    adapter: createMongooseDatabaseAdapter({
      connection,
      collection: "blyp_logs",
    }),
  },
};
```

## Config fields

- `mongoose`: a Mongoose module or object with `connection` and `connect()`
- `mongoUrl`: MongoDB connection URI used when Blyp should open the connection
- `connection`: existing Mongoose connection
- `collection`: target collection name, defaults to `blyp_logs`

The adapter config shape is:

```ts
type MongooseDatabaseAdapterConfig = {
  type: "mongoose";
  mongoose?: unknown;
  mongoUrl?: string;
  connection?: unknown;
  collection?: string;
};
```

`createMongooseDatabaseAdapter` and `MongooseDatabaseAdapterConfig` are exported from `@blyp/core/database`. The adapter is also available from the root `@blyp/core` package.

MongoDB does not require `database.dialect: "postgres" | "mysql"`. That dialect field is only needed for SQL-backed Prisma and Drizzle setups.

## Document shape

The MongoDB collection defaults to `blyp_logs`.

Blyp maps the internal row `id` to MongoDB `_id`. Other normalized log fields are stored on the document, including:

- `timestamp`
- `level`
- `message`
- `caller`
- `type`
- `groupId`
- `method`
- `path`
- `status`
- `duration`
- `hasError`
- `traceId`
- `data`
- `bindings`
- `error`
- `events`
- `record`
- `createdAt`

`record` contains the full normalized Blyp log payload. Keep it available when building queries or inspection tools around the collection.

## Connection behavior

If `connection` is provided, Blyp uses it directly and expects the connection to expose a native MongoDB `db` instance.

If `mongoose` and `mongoUrl` are provided, Blyp connects before writing when the Mongoose connection is not already open.

If `mongoose` is already connected, Blyp reuses that connection.

If no usable Mongoose object or connection exists, database logging is disabled during config resolution or insert setup fails with a Blyp warning or error.

## Delivery behavior

MongoDB uses the same database delivery settings as the other database adapters.

Default values:

- `strategy: "immediate"`
- `batchSize: 1`
- `flushIntervalMs: 250`
- `maxQueueSize: 1000`
- `overflowStrategy: "drop-oldest"`
- `flushTimeoutMs: 5000`

Batch delivery also works with MongoDB:

```ts
import mongoose from "mongoose";
import { createMongooseDatabaseAdapter } from "@blyp/core/database";

export default {
  destination: "database",
  database: {
    adapter: createMongooseDatabaseAdapter({
      mongoose,
      mongoUrl: process.env.MONGODB_URI,
    }),
    delivery: {
      strategy: "batch",
      batchSize: 50,
      flushIntervalMs: 1000,
    },
  },
};
```

## Related docs

- [Database](/docs/database)
- [Schema Contract](/docs/database/schema)
- [Troubleshooting](/docs/database/troubleshooting)
- [Configuration](/docs/configuration)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).