---
title: "Database"
description: "Required Blyp database schemas, adapter setup, migrations, and failure modes for Prisma, Drizzle, and MongoDB."
canonical_url: "https://www.blyp.dev/docs/database"
markdown_url: "https://www.blyp.dev/docs/database.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
agent:
  task: "Select and configure a supported Blyp database adapter as the primary log destination."
  outcome: "Blyp starts with a valid adapter and persists normalized records matching the schema contract."
  appliesTo:
    package:
      - "@blyp/core"
  prerequisites:
    - "Choose Prisma"
    - "Drizzle"
    - "or MongoDB and ensure its database is reachable."
  files:
    - "blyp.config.ts"
    - "prisma/schema.prisma"
    - "drizzle.config.ts"
  sideEffects:
    - "Database mode writes production log records and may require schema migrations."
  verification:
    - "Apply the schema"
    - "emit a test record"
    - "flush Blyp"
    - "and query the persisted row or document."
  rollback:
    - "Restore the previous destination and remove only Blyp-owned schema objects after preserving required data."
  failureModes:
    - symptom: "Database mode disables itself at startup."
      resolution: "Use an executable config and confirm the adapter object, dialect, and schema contract agree."
---

# Database
URL: /docs/database
LLM index: /llms.txt
Description: Required Blyp database schemas, adapter setup, migrations, and failure modes for Prisma, Drizzle, and MongoDB.
Related: /docs/database/schema, /docs/database/migrations, /docs/database/troubleshooting

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

Task: Select and configure a supported Blyp database adapter as the primary log destination.
Outcome: Blyp starts with a valid adapter and persists normalized records matching the schema contract.

### Applies To

- Package: `@blyp/core`

### Prerequisites

- Choose Prisma
- Drizzle
- or MongoDB and ensure its database is reachable.

### Files

- `blyp.config.ts`
- `prisma/schema.prisma`
- `drizzle.config.ts`

### Side Effects

- Database mode writes production log records and may require schema migrations.

### Verification

- Apply the schema
- emit a test record
- flush Blyp
- and query the persisted row or document.

### Rollback

- Restore the previous destination and remove only Blyp-owned schema objects after preserving required data.

### Failure Modes

- Database mode disables itself at startup. — Recovery: Use an executable config and confirm the adapter object, dialect, and schema contract agree.
<!-- farming-labs:agent-contract:end -->

# Database

Choose exactly one supported adapter, apply the documented schema before enabling
`destination: "database"`, then emit, flush, and query a test record. Treat schema names and indexes
as a compatibility contract. Startup disablement usually means an inert JSON config, missing adapter
object, unsupported dialect, or unapplied migration.

Use database mode when Blyp cannot safely rely on local file persistence, especially in serverless or short-lived runtimes.

In this mode, Blyp replaces file logging as the primary persistence layer and writes normalized log rows into your application database. Connectors such as Better Stack, PostHog, Sentry, Databuddy, and OTLP still work independently.

## Why the schema matters

Database mode is not just a config flag. It depends on a specific schema contract.

If the table, collection, model, columns, indexes, or adapter wiring do not match what Blyp expects, database logging can become partially broken or fully unusable. Typical failure modes include:

- database logging being disabled during config resolution
- adapter startup failures because the expected model, table, collection, or connection is missing
- failed inserts because required fields or JSON storage are missing
- degraded Studio queries and slower inspection when expected indexes are missing
- incorrect assumptions about what Blyp persists

> **Schema is required:** Treat the generated Blyp storage shape as a compatibility contract. If you rename fields, remove indexes, or point the adapter at the wrong model, table, or collection, Blyp database logging may stop working correctly.

## Supported setups

- Prisma + Postgres
- Prisma + MySQL
- Drizzle + Postgres
- Drizzle + MySQL
- MongoDB through Mongoose

## Required setup sequence

1. Choose your adapter: Prisma, Drizzle, or MongoDB through Mongoose.
2. For SQL adapters, choose your dialect: Postgres or MySQL.
3. Create the required Blyp storage contract.
4. For SQL adapters, run migrations so the database actually matches that contract.
5. Wire `blyp.config.ts` to the correct adapter runtime object.
6. Run `blyp db:generate` if you are using Prisma.
7. Emit a test log and confirm the row or document is inserted.

## Required storage contract

The current CLI-generated SQL contract is:

- SQL table: `blyp_logs`
- Prisma model: `BlypLog`
- Prisma adapter delegate name: `blypLog`
- Drizzle exported table symbol: `blypLogs`

MongoDB uses the `blyp_logs` collection by default and maps the Blyp row `id` to MongoDB `_id`.

For the full column and index contract, see [Schema Contract](/docs/database/schema).

## Adapter guides

- [Prisma](/docs/database/prisma)
- [Drizzle](/docs/database/drizzle)
- [MongoDB](/docs/database/mongodb)
- [Migrations](/docs/database/migrations)
- [Troubleshooting](/docs/database/troubleshooting)

## `blyp.config.ts` requirement

Database mode requires an executable config file such as `blyp.config.ts`, `blyp.config.mts`, `blyp.config.js`, or `blyp.config.cjs`.

`blyp.config.json` is not enough because database adapters are runtime objects, not plain JSON values.

## Prisma example

```ts
import { PrismaClient } from "@prisma/client";
import { createPrismaDatabaseAdapter } from "@blyp/core/database";

const prisma = new PrismaClient();

export default {
  destination: "database",
  database: {
    dialect: "postgres",
    adapter: createPrismaDatabaseAdapter({
      client: prisma,
      model: "blypLog",
    }),
  },
};
```

## Drizzle example

```ts
import { createDrizzleDatabaseAdapter } from "@blyp/core/database";
import { db } from "./db";
import { blypLogs } from "./db/schema/blyp";

export default {
  destination: "database",
  database: {
    dialect: "mysql",
    adapter: createDrizzleDatabaseAdapter({
      db,
      table: blypLogs,
    }),
  },
};
```

## MongoDB example

```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",
    }),
  },
};
```

## Delivery behavior

Database delivery supports immediate writes and batched writes.

Default values:

- `strategy: "immediate"`
- `batchSize: 1`
- `flushIntervalMs: 250`
- `maxQueueSize: 1000`
- `overflowStrategy: "drop-oldest"`
- `flushTimeoutMs: 5000`
- `retry.maxRetries: 1`
- `retry.backoffMs: 100`

```ts
export default {
  destination: "database",
  database: {
    dialect: "postgres",
    adapter,
    delivery: {
      strategy: "batch",
      batchSize: 50,
      flushIntervalMs: 1000,
    },
  },
};
```

## Flushing and shutdown

All Blyp loggers expose:

```ts
await logger.flush();
await logger.shutdown();
```

Promise-based and hook-driven integrations such as Elysia, Hono, Next.js, React Router, Astro, Nitro, Nuxt, SolidStart, SvelteKit, and TanStack Start flush database writes before the request finishes.

For callback-style servers such as Express, Fastify, and NestJS, call `await logger.flush()` at your own boundary when you need a hard durability point.

## CLI workflow

The recommended guided flow is:

```bash
blyp db:init
blyp db:migrate
blyp db:generate
```

`db:generate` is Prisma-only.

Without a global install:

```bash
bunx @blyp/cli db:init
bunx @blyp/cli db:migrate
bunx @blyp/cli db:generate
```

The detailed command behavior is documented in [Migrations](/docs/database/migrations).

## `traceId` in database rows

As of `@blyp/core@0.1.22`, request trace IDs are persisted in database records. Use this together with [Request Tracing](/docs/working-with-blyp/request-tracing) when you want request logs, browser logs, AI traces, connector-forwarded logs, and database rows to share the same correlation ID.

## Related docs

- [Schema Contract](/docs/database/schema)
- [Prisma](/docs/database/prisma)
- [Drizzle](/docs/database/drizzle)
- [MongoDB](/docs/database/mongodb)
- [Migrations](/docs/database/migrations)
- [Troubleshooting](/docs/database/troubleshooting)
- [CLI](/docs/cli)
- [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).