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

# Cloudflare D1 스토리지

Cloudflare D1 스토리지 구현은 Cloudflare D1을 사용하여 서버리스 SQL 데이터베이스 솔루션을 제공하여 관계형 작업 및 트랜잭션 일관성을 지원합니다.

:::warning\[관측성이 지원되지 않음]

Cloudflare D1 저장소는 **Observability 도메인을 지원하지 않습니다**. `MastraStorageExporter`의 Trace를 D1에 영구 저장할 수 없으며, D1이 유일한 저장소 Provider인 경우 [Studio의](https://mastra.zisheng.pro/ko/docs/studio/overview) Observability 기능이 작동하지 않습니다. Observability를 활성화하려면 [복합 저장소](https://mastra.zisheng.pro/ko/reference/storage/composite)를 사용하여 Observability 데이터를 ClickHouse와 같은 지원되는 Provider로 라우팅하세요. :::

:::warning\[행 크기 제한] Cloudflare D1의 **최대 행 크기는 1 MiB입니다**. 이미지와 같이 base64로 인코딩된 첨부 파일이 포함된 메시지를 저장하면 이 제한을 초과할 수 있습니다. 첨부 파일을 외부 저장소에 업로드하는 방법을 비롯한 해결 방법은 [대용량 첨부 파일 처리](https://mastra.zisheng.pro/ko/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({...})` 내부에서 `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'`를 사용할 때 `D1Store`는 모듈 수준 변수로 추출하지 말고 `new Mastra({...})` 내부에서 인라인으로 초기화해야 합니다. 또는 `env`를 사용할 수 있게 된 후 `fetch` 핸들러 내부에서 `D1Store`를 초기화하세요. 자세한 내용은 [CloudflareDeployer 참고 문서](https://mastra.zisheng.pro/ko/reference/deployer/cloudflare)를 참조하세요. :::

### HTTP 경로 없이 Cloudflare Worker에서 사용

HTTP 경로를 제공하지 않고 Worker에서 직접 Mastra를 호출하려는 경우(예: Agent를 실행하거나 Workflow를 트리거하기 위해) `CloudflareDeployer`를 사용하세요. Worker의 `env` 매개변수에서 D1 바인딩에 접근하고 프로그래밍 방식으로 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와 함께 사용

작업자가 아닌 환경(Node.js, 서버리스 함수 등)의 경우 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
})
```

### 랭글러 구성

D1 데이터베이스 바인딩을`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 바인딩(Workers 런타임용)

**accountId** (`string`): Cloudflare 계정 ID(REST API용)

**databaseId** (`string`): Cloudflare D1 데이터베이스 ID(REST API용)

**apiToken** (`string`): Cloudflare API 토큰(REST API용)

**tablePrefix** (`string`): 모든 테이블 이름에 사용할 선택적 접두사(환경 격리에 유용)

## 추가 참고사항

### 스키마 관리

저장소 구현은 스키마 생성 및 업데이트를 자동으로 처리합니다. 다음 테이블이 생성됩니다.

- `threads`: 대화 스레드를 저장합니다.
- `messages`: 개별 메시지를 저장합니다.
- `metadata`: 스레드 및 메시지에 대한 추가 메타데이터를 저장합니다.

### 초기화

Mastra 클래스에 저장소를 전달하면 저장소 작업 전에 `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')
  },
}
```

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은 단일 행 작업에 대한 트랜잭션 보장을 제공합니다. 여러 작업을 단일 작업 단위로 실행할 수 있습니다.

### 테이블 생성 및 마이그레이션

저장소가 초기화되면 테이블이 자동으로 생성되며 `tablePrefix` 옵션을 사용하여 환경별로 격리할 수 있습니다. 그러나 고급 스키마 변경에는 수동 마이그레이션과 신중한 계획이 필요합니다. 데이터 손실을 방지하기 위해 열을 추가하거나 데이터 유형 및 인덱스를 변경하는 작업이 그 예입니다.