Cloudflare D1 스토리지

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

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

Cloudflare D1 저장소는 Observability 도메인을 지원하지 않습니다. MastraStorageExporter의 Trace를 D1에 영구 저장할 수 없으며, D1이 유일한 저장소 Provider인 경우 Studio의 Observability 기능이 작동하지 않습니다. Observability를 활성화하려면 복합 저장소를 사용하여 Observability 데이터를 ClickHouse와 같은 지원되는 Provider로 라우팅하세요. :::

:::warning[행 크기 제한] Cloudflare D1의 최대 행 크기는 1 MiB입니다. 이미지와 같이 base64로 인코딩된 첨부 파일이 포함된 메시지를 저장하면 이 제한을 초과할 수 있습니다. 첨부 파일을 외부 저장소에 업로드하는 방법을 비롯한 해결 방법은 대용량 첨부 파일 처리를 참조하세요. :::

설치

npm

npm install @mastra/cloudflare-d1@latest

pnpm

pnpm add @mastra/cloudflare-d1@latest

Yarn

yarn add @mastra/cloudflare-d1@latest

Bun

bun add @mastra/cloudflare-d1@latest

용법

Mastra CloudflareDeployer와 함께 사용

Cloudflare에서 Mastra와 함께 D1Store를 사용하는 표준 방법은 CloudflareDeployer를 이용하는 것입니다. cloudflare:workers에서 env를 가져오고 new Mastra({...}) 내부에서 D1Store를 인라인으로 초기화하세요.

src/mastra/index.ts

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 참고 문서를 참조하세요. :::

HTTP 경로 없이 Cloudflare Worker에서 사용

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

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 접근 방식을 사용합니다.

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:

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

아니면wrangler.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()이 자동으로 호출됩니다.

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()을 명시적으로 호출해야 합니다.

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 옵션을 사용하여 환경별로 격리할 수 있습니다. 그러나 고급 스키마 변경에는 수동 마이그레이션과 신중한 계획이 필요합니다. 데이터 손실을 방지하기 위해 열을 추가하거나 데이터 유형 및 인덱스를 변경하는 작업이 그 예입니다.