@mastra/cloudflare-d1 1.0.0 → 1.0.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/cloudflare-d1
 
+## 1.0.1-alpha.0
+
+### Patch Changes
+
+- `updateWorkflowResults` and `updateWorkflowState` now throw a not-implemented error. This storage backend does not support concurrent workflow updates. ([#12575](https://github.com/mastra-ai/mastra/pull/12575))
+
+- Updated dependencies [[`504fc8b`](https://github.com/mastra-ai/mastra/commit/504fc8b9d0ddab717577ad3bf9c95ea4bd5377bd), [`f9c150b`](https://github.com/mastra-ai/mastra/commit/f9c150b7595ad05ad9cc9a11098e2944361e8c22), [`88de7e8`](https://github.com/mastra-ai/mastra/commit/88de7e8dfe4b7e1951a9e441bb33136e705ce24e), [`edee4b3`](https://github.com/mastra-ai/mastra/commit/edee4b37dff0af515fc7cc0e8d71ee39e6a762f0), [`3790c75`](https://github.com/mastra-ai/mastra/commit/3790c7578cc6a47d854eb12d89e6b1912867fe29), [`e7a235b`](https://github.com/mastra-ai/mastra/commit/e7a235be6472e0c870ed6c791ddb17c492dc188b), [`d51d298`](https://github.com/mastra-ai/mastra/commit/d51d298953967aab1f58ec965b644d109214f085), [`6dbeeb9`](https://github.com/mastra-ai/mastra/commit/6dbeeb94a8b1eebb727300d1a98961f882180794), [`d5f0d8d`](https://github.com/mastra-ai/mastra/commit/d5f0d8d6a03e515ddaa9b5da19b7e44b8357b07b), [`09c3b18`](https://github.com/mastra-ai/mastra/commit/09c3b1802ff14e243a8a8baea327440bc8cc2e32), [`b896379`](https://github.com/mastra-ai/mastra/commit/b8963791c6afa79484645fcec596a201f936b9a2), [`85c84eb`](https://github.com/mastra-ai/mastra/commit/85c84ebb78aebfcba9d209c8e152b16d7a00cb71), [`a89272a`](https://github.com/mastra-ai/mastra/commit/a89272a5d71939b9fcd284e6a6dc1dd091a6bdcf), [`ee9c8df`](https://github.com/mastra-ai/mastra/commit/ee9c8df644f19d055af5f496bf4942705f5a47b7), [`77b4a25`](https://github.com/mastra-ai/mastra/commit/77b4a254e51907f8ff3a3ba95596a18e93ae4b35), [`276246e`](https://github.com/mastra-ai/mastra/commit/276246e0b9066a1ea48bbc70df84dbe528daaf99), [`08ecfdb`](https://github.com/mastra-ai/mastra/commit/08ecfdbdad6fb8285deef86a034bdf4a6047cfca), [`d5f628c`](https://github.com/mastra-ai/mastra/commit/d5f628ca86c6f6f3ff1035d52f635df32dd81cab), [`524c0f3`](https://github.com/mastra-ai/mastra/commit/524c0f3c434c3d9d18f66338dcef383d6161b59c), [`c18a0e9`](https://github.com/mastra-ai/mastra/commit/c18a0e9cef1e4ca004b2963d35e4cfc031971eac), [`4bd21ea`](https://github.com/mastra-ai/mastra/commit/4bd21ea43d44d0a0427414fc047577f9f0aa3bec), [`115a7a4`](https://github.com/mastra-ai/mastra/commit/115a7a47db5e9896fec12ae6507501adb9ec89bf), [`22a48ae`](https://github.com/mastra-ai/mastra/commit/22a48ae2513eb54d8d79dad361fddbca97a155e8), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9311c17`](https://github.com/mastra-ai/mastra/commit/9311c17d7a0640d9c4da2e71b814dc67c57c6369), [`7edf78f`](https://github.com/mastra-ai/mastra/commit/7edf78f80422c43e84585f08ba11df0d4d0b73c5), [`1c4221c`](https://github.com/mastra-ai/mastra/commit/1c4221cf6032ec98d0e094d4ee11da3e48490d96), [`d25b9ea`](https://github.com/mastra-ai/mastra/commit/d25b9eabd400167255a97b690ffbc4ee4097ded5), [`fe1ce5c`](https://github.com/mastra-ai/mastra/commit/fe1ce5c9211c03d561606fda95cbfe7df1d9a9b5), [`b03c0e0`](https://github.com/mastra-ai/mastra/commit/b03c0e0389a799523929a458b0509c9e4244d562), [`0a8366b`](https://github.com/mastra-ai/mastra/commit/0a8366b0a692fcdde56c4d526e4cf03c502ae4ac), [`85664e9`](https://github.com/mastra-ai/mastra/commit/85664e9fd857320fbc245e301f764f45f66f32a3), [`bc79650`](https://github.com/mastra-ai/mastra/commit/bc796500c6e0334faa158a96077e3fb332274869), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`3a3a59e`](https://github.com/mastra-ai/mastra/commit/3a3a59e8ffaa6a985fe3d9a126a3f5ade11a6724), [`3108d4e`](https://github.com/mastra-ai/mastra/commit/3108d4e649c9fddbf03253a6feeb388a5fa9fa5a), [`0c33b2c`](https://github.com/mastra-ai/mastra/commit/0c33b2c9db537f815e1c59e2c898ffce2e395a79), [`191e5bd`](https://github.com/mastra-ai/mastra/commit/191e5bd29b82f5bda35243945790da7bc7b695c2), [`f77cd94`](https://github.com/mastra-ai/mastra/commit/f77cd94c44eabed490384e7d19232a865e13214c), [`e8135c7`](https://github.com/mastra-ai/mastra/commit/e8135c7e300dac5040670eec7eab896ac6092e30), [`daca48f`](https://github.com/mastra-ai/mastra/commit/daca48f0fb17b7ae0b62a2ac40cf0e491b2fd0b7), [`257d14f`](https://github.com/mastra-ai/mastra/commit/257d14faca5931f2e4186fc165b6f0b1f915deee), [`352f25d`](https://github.com/mastra-ai/mastra/commit/352f25da316b24cdd5b410fd8dddf6a8b763da2a), [`93477d0`](https://github.com/mastra-ai/mastra/commit/93477d0769b8a13ea5ed73d508d967fb23eaeed9), [`31c78b3`](https://github.com/mastra-ai/mastra/commit/31c78b3eb28f58a8017f1dcc795c33214d87feac), [`0bc0720`](https://github.com/mastra-ai/mastra/commit/0bc07201095791858087cc56f353fcd65e87ab54), [`36516ac`](https://github.com/mastra-ai/mastra/commit/36516aca1021cbeb42e74751b46a2614101f37c8), [`e947652`](https://github.com/mastra-ai/mastra/commit/e9476527fdecb4449e54570e80dfaf8466901254), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`ec248f6`](https://github.com/mastra-ai/mastra/commit/ec248f6b56e8a037c066c49b2178e2507471d988)]:
+  - @mastra/core@1.9.0-alpha.0
+
 ## 1.0.0
 
 ### Major Changes

package/LICENSE.md

@@ -1,3 +1,18 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
 # Apache License 2.0
 
 Copyright (c) 2025 Kepler Software, Inc.

package/dist/docs/SKILL.md

@@ -1,32 +1,22 @@
 ---
-name: mastra-cloudflare-d1-docs
-description: Documentation for @mastra/cloudflare-d1. Includes links to type definitions and readable implementation code in dist/.
+name: mastra-cloudflare-d1
+description: Documentation for @mastra/cloudflare-d1. Use when working with @mastra/cloudflare-d1 APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/cloudflare-d1"
+  version: "1.0.1-alpha.0"
 ---
 
-# @mastra/cloudflare-d1 Documentation
+## When to use
 
-> **Version**: 1.0.0
-> **Package**: @mastra/cloudflare-d1
+Use this skill whenever you are working with @mastra/cloudflare-d1 to obtain the domain-specific knowledge.
 
-## Quick Navigation
+## How to use
 
-Use SOURCE_MAP.json to find any export:
+Read the individual reference documents for detailed explanations and code examples.
 
-```bash
-cat docs/SOURCE_MAP.json
-```
+### Reference
 
-Each export maps to:
-- **types**: `.d.ts` file with JSDoc and API signatures
-- **implementation**: `.js` chunk file with readable source
-- **docs**: Conceptual documentation in `docs/`
+- [Reference: Cloudflare D1 Storage](references/reference-storage-cloudflare-d1.md) - Documentation for the Cloudflare D1 SQL storage implementation in Mastra.
 
-## Top Exports
 
-
-
-See SOURCE_MAP.json for the complete list.
-
-## Available Topics
-
-- [Storage](storage/) - 1 file(s)
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/{SOURCE_MAP.json → assets/SOURCE_MAP.json}

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.0.1-alpha.0",
   "package": "@mastra/cloudflare-d1",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-storage-cloudflare-d1.md

@@ -0,0 +1,218 @@
+# Cloudflare D1 Storage
+
+The Cloudflare D1 storage implementation provides a serverless SQL database solution using Cloudflare D1, supporting relational operations and transactional consistency.
+
+> **Observability Not Supported:** Cloudflare D1 storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to D1, and Mastra Studio's observability features won't work with D1 as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+> **Row Size Limit:** Cloudflare D1 enforces a **1 MiB maximum row size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/cloudflare-d1@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cloudflare-d1@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cloudflare-d1@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cloudflare-d1@latest
+```
+
+## Usage
+
+### Using with Cloudflare Workers
+
+When using D1Store in a Cloudflare Worker, you need to access the D1 binding from the worker's `env` parameter at runtime. The `D1Database` in your type definition is only for TypeScript type checking—the actual binding is provided by the Workers runtime.
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+import { Mastra } from '@mastra/core'
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
+
+type Env = {
+  D1Database: D1Database // TypeScript type definition
+}
+
+// Factory function to create Mastra with D1 binding
+function createMastra(env: Env) {
+  const storage = new D1Store({
+    binding: env.D1Database, // ✅ Access the actual binding from env
+    tablePrefix: 'dev_', // Optional: isolate tables per environment
+  })
+
+  return new Mastra({
+    storage,
+    deployer: new CloudflareDeployer({
+      name: 'my-worker',
+      d1_databases: [
+        {
+          binding: 'D1Database', // Must match the property name in Env type
+          database_name: 'your-database-name',
+          database_id: 'your-database-id',
+        },
+      ],
+    }),
+  })
+}
+
+// Cloudflare Worker export
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const mastra = createMastra(env)
+
+    // Your handler logic here
+    return new Response('Hello from Mastra with D1!')
+  },
+}
+```
+
+> **Important: Understanding D1 Bindings:** In the `Env` type definition, `D1Database: D1Database` serves two purposes:
+>
+> - The **property name** (`D1Database`) must match the `binding` name in your `wrangler.toml`
+> - The **type** (`: D1Database`) is from `@cloudflare/workers-types` for TypeScript type checking
+>
+> At runtime, Cloudflare Workers provides the actual D1 database instance via `env.D1Database`. You cannot use `D1Database` directly outside of the worker's context.
+
+### Using with REST API
+
+For non-Workers environments (Node.js, serverless functions, etc.), use the REST API approach:
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+
+const storage = new D1Store({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
+  databaseId: process.env.CLOUDFLARE_D1_DATABASE_ID!, // D1 Database ID
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
+  tablePrefix: 'dev_', // Optional: isolate tables per environment
+})
+```
+
+### Wrangler Configuration
+
+Add the D1 database binding to your `wrangler.toml`:
+
+```toml
+[[d1_databases]]
+binding = "D1Database"  # Must match the property name in your Env type
+database_name = "your-database-name"
+database_id = "your-database-id"
+```
+
+Or in `wrangler.jsonc`:
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "D1Database",
+      "database_name": "your-database-name",
+      "database_id": "your-database-id",
+    },
+  ],
+}
+```
+
+## Parameters
+
+**binding?:** (`D1Database`): Cloudflare D1 Workers binding (for Workers runtime)
+
+**accountId?:** (`string`): Cloudflare Account ID (for REST API)
+
+**databaseId?:** (`string`): Cloudflare D1 Database ID (for REST API)
+
+**apiToken?:** (`string`): Cloudflare API Token (for REST API)
+
+**tablePrefix?:** (`string`): Optional prefix for all table names (useful for environment isolation)
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { D1Store } from '@mastra/cloudflare-d1'
+
+type Env = {
+  D1Database: D1Database
+}
+
+// In a Cloudflare Worker
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const storage = new D1Store({
+      binding: env.D1Database, // ✅ Use env.D1Database
+    })
+
+    const mastra = new Mastra({
+      storage, // init() is called automatically
+    })
+
+    // Your handler logic here
+    return new Response('Success')
+  },
+}
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+
+type Env = {
+  D1Database: D1Database
+}
+
+// In a Cloudflare Worker
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const storage = new D1Store({
+      id: 'd1-storage',
+      binding: env.D1Database, // ✅ Use env.D1Database
+    })
+
+    // Required when using storage directly
+    await storage.init()
+
+    // Access domain-specific stores via getStore()
+    const memoryStore = await storage.getStore('memory')
+    const thread = await memoryStore?.getThreadById({ threadId: '...' })
+
+    return new Response('Success')
+  },
+}
+```
+
+> **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+
+### Transactions & Consistency
+
+Cloudflare D1 provides transactional guarantees for single-row operations. This means that multiple operations can be executed as a single, all-or-nothing unit of work.
+
+### Table Creation & Migrations
+
+Tables are created automatically when storage is initialized (and can be isolated per environment using the `tablePrefix` option), but advanced schema changes—such as adding columns, changing data types, or modifying indexes—require manual migration and careful planning to avoid data loss.

package/dist/index.cjs

@@ -1847,27 +1847,24 @@ var WorkflowsStorageD1 = class extends storage.WorkflowsStorage {
     super();
     this.#db = new D1DB(resolveD1Config(config));
   }
+  supportsConcurrentUpdates() {
+    return false;
+  }
   async init() {
     await this.#db.createTable({ tableName: storage.TABLE_WORKFLOW_SNAPSHOT, schema: storage.TABLE_SCHEMAS[storage.TABLE_WORKFLOW_SNAPSHOT] });
   }
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: storage.TABLE_WORKFLOW_SNAPSHOT });
   }
-  updateWorkflowResults({
-    // workflowName,
-    // runId,
-    // stepId,
-    // result,
-    // requestContext,
-  }) {
-    throw new Error("Method not implemented.");
+  async updateWorkflowResults(_args) {
+    throw new Error(
+      "updateWorkflowResults is not implemented for Cloudflare D1 storage. D1 does not support atomic read-modify-write operations needed for concurrent workflow updates."
+    );
   }
-  updateWorkflowState({
-    // workflowName,
-    // runId,
-    // opts,
-  }) {
-    throw new Error("Method not implemented.");
+  async updateWorkflowState(_args) {
+    throw new Error(
+      "updateWorkflowState is not implemented for Cloudflare D1 storage. D1 does not support atomic read-modify-write operations needed for concurrent workflow updates."
+    );
   }
   async persistWorkflowSnapshot({
     workflowName,