# Storage Overview

Mastra requires the following tables to be present in the database.

## Core Schema

**Messages**:

Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.

iduuidv4PRIMARYKEYNOT NULLUnique identifier for the message (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)thread\_iduuidv4FK → threads.idNOT NULLParent thread referenceresourceIduuidv4CAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering

The message `content` column contains a JSON object conforming to the `MastraMessageContentV2` type, which is designed to align closely with the AI SDK `UIMessage` message shape.

formatintegerNOT NULLMessage format version (currently 2)partsarray (JSON)NOT NULLArray of message parts (text, tool-invocation, file, reasoning, etc.). The structure of items in this array varies by `type`.experimental\_attachmentsarray (JSON)CAN BE NULLOptional array of file attachmentscontenttextCAN BE NULLOptional main text content of the messagetoolInvocationsarray (JSON)CAN BE NULLOptional array summarizing tool calls and resultsreasoningobject (JSON)CAN BE NULLOptional information about the reasoning process behind the assistant's responseannotationsobject (JSON)CAN BE NULLOptional additional metadata or annotations

**Threads**:

Groups related messages together and associates them with a resource. Contains metadata about the conversation.

iduuidv4PRIMARYKEYNOT NULLUnique identifier for the thread (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)resourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatatextCustom thread metadata as stringified JSON. Example:

```json
{
  "category": "support",
  "priority": 1
}
```

createdAttimestampNOT NULLupdatedAttimestampNOT NULLUsed for thread ordering history

**Resources**:

Stores user-specific data for resource-scoped working memory. Each resource represents a user or entity, allowing working memory to persist across all conversation threads for that user.

idtextPRIMARYKEYNOT NULLResource identifier (user or entity ID) - same as resourceId used in threads and agent callsworkingMemorytextCAN BE NULLPersistent working memory data as Markdown text. Contains user profile, preferences, and contextual information that persists across conversation threads.metadatajsonbCAN BE NULLAdditional resource metadata as JSON. Example:

```json
{
  "preferences": {
    "language": "en",
    "timezone": "UTC"
  },
  "tags": [
    "premium",
    "beta-user"
  ]
}
```

createdAttimestampNOT NULLWhen the resource record was first createdupdatedAttimestampNOT NULLWhen the working memory was last updated

**Workflows**:

When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.

workflow\_nametextNOT NULLName of the workflowrun\_iduuidv4NOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)snapshottextNOT NULLSerialized workflow state as JSON. Example:

```json
{
  "value": {
    "currentState": "running"
  },
  "context": {
    "stepResults": {},
    "attempts": {},
    "triggerData": {}
  },
  "activePaths": [],
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1648176000000
}
```

createdAttimestampNOT NULLupdatedAttimestampNOT NULLLast modification time, used to track state changes during workflow execution

**Evals**:

Stores eval results from running metrics against agent outputs.

inputtextNOT NULLInput provided to the agentoutputtextNOT NULLOutput generated by the agentresultjsonbNOT NULLEval result data that includes score and details. Example:

```json
{
  "score": 0.95,
  "details": {
    "reason": "Response accurately reflects source material",
    "citations": [
      "page 1",
      "page 3"
    ]
  }
}
```

agent\_nametextNOT NULLmetric\_nametextNOT NULLe.g Faithfulness, Hallucination, etc.instructionstextNOT NULLSystem prompt or instructions for the agenttest\_infojsonbNOT NULLAdditional test metadata and configurationglobal\_run\_iduuidv4NOT NULLGroups related evaluation runs (e.g. all unit tests in a CI run)run\_iduuidv4NOT NULLUnique identifier for the run being evaluated (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)created\_attimestampNOT NULL

**Traces**:

Captures OpenTelemetry traces for monitoring and debugging.

idtextNOT NULLPRIMARYKEYUnique trace identifierparentSpanIdtextID of the parent span. Null if span is top levelnametextNOT NULLHierarchical operation name (e.g. `workflow.myWorkflow.execute`, `http.request`, `database.query`)traceIdtextNOT NULLRoot trace identifier that groups related spansscopetextNOT NULLLibrary/package/service that created the span (e.g. `@mastra/core`, `express`, `pg`)kindintegerNOT NULL`INTERNAL` (0, within process), `CLIENT` (1, outgoing calls), `SERVER` (2, incoming calls), `PRODUCER` (3, async job creation), `CONSUMER` (4, async job processing)attributesjsonbUser defined key-value pairs that contain span metadatastatusjsonbJSON object with `code` (UNSET=0, ERROR=1, OK=2) and optional `message`. Example:

```json
{
  "code": 1,
  "message": "HTTP request failed with status 500"
}
```

eventsjsonbTime-stamped events that occurred during the spanlinksjsonbLinks to other related spansothertextAdditional OpenTelemetry span fields as stringified JSON. Example:

```json
{
  "droppedAttributesCount": 2,
  "droppedEventsCount": 1,
  "instrumentationLibrary": "@opentelemetry/instrumentation-http"
}
```

startTimebigintNOT NULLNanoseconds since Unix epoch when span startedendTimebigintNOT NULLNanoseconds since Unix epoch when span endedcreatedAttimestampNOT NULL