> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Cloudflare D1 儲存

Cloudflare D1 儲存實作使用 Cloudflare D1 提供 serverless SQL 資料庫方案，支援關聯式操作及交易一致性。

> **不支援可觀測性:** Cloudflare D1 儲存**不支援 observability domain**。來自 `MastraStorageExporter` 的 Trace 無法持久保存至 D1，而當 D1 是你唯一的 storage provider 時，[Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 的可觀測性功能亦無法運作。如要啟用可觀測性，請使用[複合儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

> **資料列大小限制:** Cloudflare D1 強制實施 **1 MiB 的資料列大小上限**。儲存包含圖片等 base64 編碼附件的訊息時，可能會超出此限制。請參閱[處理大型附件](https://mastra.zisheng.pro/zh-HK/docs/memory/memory-processors)，了解包括將附件上載至外部儲存空間在內的解決方法。

## 安裝

**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
```

## 用法

### 配合 Mastra CloudflareDeployer 使用

在 Cloudflare 上配合 Mastra 使用 D1Store 的標準方式，是使用 `CloudflareDeployer`。從 `cloudflare:workers` 匯入 `env`，並在 `new Mastra({...})` 內以 inline 方式初始化 `D1Store`。

```typescript
import { env } from 'cloudflare:workers'
import { D1Store } from '@mastra/cloudflare-d1'
import { Mastra } from '@mastra/core'
import { CloudflareDeployer } from '@mastra/deployer-cloudflare'

export const mastra = new Mastra({
  storage: new D1Store({ binding: env.DB }),
  deployer: new CloudflareDeployer({
    name: 'my-worker',
    d1_databases: [
      {
        binding: 'DB',
        database_name: 'your-database-name',
        database_id: 'your-database-id',
      },
    ],
  }),
})
```

> **備註:** 使用 `import { env } from 'cloudflare:workers'` 時，必須在 `new Mastra({...})` 內以 inline 方式初始化 `D1Store`，不可將其抽取為 module-level 變數。另一做法是在 `env` 可用後，於 `fetch` handler 內初始化 `D1Store`。詳情請參閱 [CloudflareDeployer 參考](https://mastra.zisheng.pro/zh-HK/reference/deployer/cloudflare)。

### 在沒有 HTTP 路由的 Cloudflare Worker 中使用

如要直接在 Worker 中呼叫 Mastra（例如執行 Agent 或觸發 Workflow），而不提供 HTTP 路由，便不需要 `CloudflareDeployer`。從 Worker 的 `env` 參數存取 D1 binding，然後以程式方式呼叫 Mastra。

```typescript
import { D1Store } from '@mastra/cloudflare-d1'
import { Mastra } from '@mastra/core'

type Env = {
  DB: D1Database
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const mastra = new Mastra({
      storage: new D1Store({ binding: env.DB }),
    })

    const agent = mastra.getAgent('my-agent')
    const result = await agent.generate('Hello')

    return Response.json({ text: result.text })
  },
}
```

### 配合 REST API 使用

在非 Workers 環境（Node.js、serverless function 等）中，請使用 REST API 方式：

```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 設定

將 D1 資料庫 binding 加至你的 `wrangler.toml`：

```toml
[[d1_databases]]
binding = "DB"
database_name = "your-database-name"
database_id = "your-database-id"
```

或在 `wrangler.jsonc` 中設定：

```jsonc
{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "your-database-name",
      "database_id": "your-database-id",
    },
  ],
}
```

## 參數

**binding** (`D1Database`): Cloudflare D1 Workers binding（用於 Workers runtime）

**accountId** (`string`): Cloudflare Account ID（用於 REST API）

**databaseId** (`string`): Cloudflare D1 Database ID（用於 REST API）

**apiToken** (`string`): Cloudflare API Token（用於 REST API）

**tablePrefix** (`string`): 所有資料表名稱的可選前綴（適合用作環境隔離）

## 補充說明

### Schema 管理

儲存實作會自動處理 schema 建立及更新，並建立以下資料表：

- `threads`：儲存對話 thread
- `messages`：儲存個別訊息
- `metadata`：儲存 thread 及訊息的額外 metadata

### 初始化

將 storage 傳入 Mastra class 時，系統會在任何儲存操作前自動呼叫 `init()`：

```typescript
import { Mastra } from '@mastra/core'
import { D1Store } from '@mastra/cloudflare-d1'

type Env = {
  DB: D1Database
}

// In a Cloudflare Worker
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const storage = new D1Store({
      binding: env.DB,
    })

    const mastra = new Mastra({
      storage, // init() is called automatically
    })

    // Your handler logic here
    return new Response('Success')
  },
}
```

如直接使用 storage 而不配合 Mastra，則必須明確呼叫 `init()` 來建立資料表：

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

type Env = {
  DB: D1Database
}

// In a Cloudflare Worker
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const storage = new D1Store({
      id: 'd1-storage',
      binding: env.DB,
    })

    // 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')
  },
}
```

> **注意:** 如未呼叫 `init()`，資料表便不會建立，而儲存操作會在沒有提示的情況下失敗或拋出錯誤。

### 交易及一致性

Cloudflare D1 為單一資料列操作提供交易保證。多項操作可以作為單一、全有或全無的工作單元執行。

### 建立資料表及 migration

初始化 storage 時會自動建立資料表（亦可使用 `tablePrefix` 選項按環境隔離），但進階 schema 變更需要手動 migration 及仔細規劃。例如加入欄位，或變更資料類型及 index，以免資料遺失。