@caleblawson/cloudflare-d1

@mastra/cloudflare-d1

A Mastra store for Cloudflare D1 SQL databases, supporting threads, messages, workflows, evaluations, and traces with robust SQL features.

Features

• Thread and message storage using SQL tables
• True sorted order and filtering via SQL queries
• Rich metadata support (JSON-encoded)
• Timestamp tracking for all records
• Workflow snapshot persistence
• Trace and evaluation storage
• Efficient batch operations (with prepared statements)
• Automatic JSON serialization/deserialization for metadata and custom fields
• Error handling and logging for all operations
• Supports both Cloudflare Workers D1 Binding and REST API

Prerequisites

• Access to a Cloudflare account with D1 enabled
• D1 database created and configured
• For Workers binding: Worker configured with D1 binding
• For REST API: Cloudflare API Token with D1 permissions

Installation

pnpm add @mastra/cloudflare-d1

Usage

With Workers D1 Binding

import { D1Store } from '@mastra/cloudflare-d1';

const store = new D1Store({
  binding: env.DB, // D1Database binding from Worker environment
  tablePrefix: 'mastra_', // optional
});

With REST API

import { D1Store } from '@mastra/cloudflare-d1';

const store = new D1Store({
  accountId: '<your-account-id>',
  databaseId: '<your-d1-database-id>',
  apiToken: '<your-api-token>',
  tablePrefix: 'mastra_', // optional
});

Supported Methods

Thread Operations

• saveThread(thread): Create or update a thread
• getThreadById({ threadId }): Get a thread by ID
• getThreadsByResourceId({ resourceId }): Fetch all threads associated with a resource.
• updateThread({ id, title, metadata }): Update the title and/or metadata of a thread.
• deleteThread({ threadId }): Delete a thread and all its messages.

Message Operations

• saveMessages({ messages }): Save multiple messages in a batch operation (uses prepared statements).
• getMessages({ threadId, selectBy? }): Retrieve messages for a thread, with optional filtering (e.g., last N, include surrounding messages).

Workflow Operations

• persistWorkflowSnapshot({ workflowName, runId, snapshot }): Save workflow state for a given workflow/run.
• loadWorkflowSnapshot({ workflowName, runId }): Load persisted workflow state.

Trace/Evaluation Operations

• getTraces({ name?, scope?, page, perPage, attributes? }): Query trace records with optional filters and pagination.
• getEvalsByAgentName({ agentName, type? }): Query evaluation results by agent name.

Utility

• clearTable({ tableName }): Remove all records from a logical table.
• batchInsert({ tableName, records }): Batch insert multiple records.
• insert({ tableName, record }): Insert a single record into a table.

Data Types

The D1 store supports the following data types:

• text: String
• timestamp: ISO8601 string (converted to/from Date)
• uuid: String
• jsonb: JSON-encoded object
• integer: Integer (for internal counters, etc)

All metadata and custom fields are automatically serialized/deserialized as JSON.

Configuration Reference

Option	Type	Description
binding	D1Database	D1 Workers binding (for Workers)
accountId	string	Cloudflare Account ID (for REST API)
databaseId	string	D1 Database ID (for REST API)
apiToken	string	Cloudflare API Token (for REST API)
tablePrefix	string	Optional prefix for all table names

Table/Namespace Mapping

Each logical Mastra table maps to a SQL table in D1 (with optional prefix):

• mastra_threads — stores threads
• mastra_messages — stores messages
• mastra_workflow_snapshot — stores workflow snapshots
• mastra_evals — stores evaluations
• mastra_traces — stores traces

(The prefix is configurable via tablePrefix.)

Limitations

• No multi-statement transactions (D1 currently supports single statements per query)
• No advanced SQL joins (D1 is SQLite-based, but some features may be limited)
• Batch operations are processed in chunks, not truly atomic
• Some REST API operations may be slower than Workers binding
• D1 is in beta and may have evolving limitations
• No vector search capabilities
• Note: D1 has specific limitations and behaviors, please refer to the official Cloudflare D1 documentation for more information.

Cleanup / Disconnect

No explicit cleanup is required. Connections are managed by the platform.