---
title: "Schema Contract"
description: "The required Blyp table, columns, indexes, and naming contract for database mode."
canonical_url: "https://www.blyp.dev/docs/database/schema"
markdown_url: "https://www.blyp.dev/docs/database/schema.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
---

# Schema Contract
URL: /docs/database/schema
LLM index: /llms.txt
Description: The required Blyp table, columns, indexes, and naming contract for database mode.

# Schema Contract

Database mode depends on a fixed storage contract. The schema is not optional for SQL adapters, and MongoDB documents should preserve the same normalized Blyp row shape.

If your database shape drifts away from the Blyp contract, inserts can fail, config resolution can disable database logging, and tooling such as Studio can lose the query shape it expects.

> **Do not improvise the schema:** In database mode, Blyp expects the documented storage contract. Missing columns, renamed fields, missing JSON columns, missing indexes, or a mismatched MongoDB collection can make the feature effectively unusable.

## Canonical names

- SQL table: `blyp_logs`
- Prisma model: `BlypLog`
- Prisma delegate name used in adapter config: `blypLog`
- Drizzle export: `blypLogs`
- MongoDB collection: `blyp_logs`
- MongoDB `_id`: Blyp row `id`

SQL adapters use fixed columns and indexes. MongoDB stores the same normalized Blyp row fields as document properties and maps `id` to `_id`.

## Required columns

For Prisma and Drizzle, the SQL table must include these columns:

| App field | DB column or model field | Type shape | Required | Why Blyp stores it |
| --- | --- | --- | --- | --- |
| `id` | `id` | UUID or 36-char string | yes | Stable row identity for each log record |
| `timestamp` | `timestamp` | datetime with microsecond precision | yes | Original log event time |
| `level` | `level` | short string | yes | Severity filtering and query grouping |
| `message` | `message` | text | yes | Human-readable event message |
| `caller` | `caller` | text | no | Source location when available |
| `type` | `type` | short string | no | Event category such as request or error types |
| `groupId` | `group_id` | short string | no | Structured/grouped log correlation |
| `method` | `method` | short string | no | HTTP method when the log is request-related |
| `path` | `path` | text | no | HTTP path when the log is request-related |
| `status` | `status` | integer | no | HTTP status or similar numeric outcome |
| `duration` | `duration` | floating-point number | no | Timing information for the event |
| `hasError` | `has_error` | boolean | yes | Fast error presence check without opening JSON payloads |
| `data` | `data` | JSON | no | Structured event payload fields |
| `bindings` | `bindings` | JSON object | no | Child logger bindings and contextual fields |
| `error` | `error` | JSON object | no | Normalized error payload |
| `events` | `events` | JSON array | no | Structured log event trail |
| `record` | `record` | JSON | yes | Full normalized Blyp record |
| `createdAt` | `created_at` | datetime with default now | yes | Insert time in the database |

## Why `record` is required

`record` is the full normalized Blyp log payload. It is not a convenience field. It is part of the required contract and should be treated as mandatory even when some individual fields are also projected into first-class columns.

## JSON columns

The JSON-backed fields are:

- `data`
- `bindings`
- `error`
- `events`
- `record`

The first four can be `null` for some rows. That does not make them optional in the schema contract. They still need to exist with the expected JSON-capable type.

`record` is required and must not be removed.

## Required indexes

- `blyp_logs_timestamp_idx`
- `blyp_logs_level_timestamp_idx`
- `blyp_logs_type_timestamp_idx`
- `blyp_logs_group_id_timestamp_idx`

MongoDB support does not currently create or require these SQL indexes. Add MongoDB indexes yourself only when your own query workload needs them.

## Why the indexes exist

- `blyp_logs_timestamp_idx`: supports time-based browsing and recent-log queries
- `blyp_logs_level_timestamp_idx`: supports severity filters sorted by time
- `blyp_logs_type_timestamp_idx`: supports event-type filtering such as request vs error style queries
- `blyp_logs_group_id_timestamp_idx`: supports grouped and structured log inspection over time

## `traceId`

`traceId` is part of the persisted database row contract in current Blyp releases. Keep it in the supported schema when you want request correlation to survive beyond runtime memory and connector forwarding.

## Adapter-specific implementations

Use these pages for the exact generated schema by adapter and dialect:

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

## 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).