Cloudflare D1

このページでは、Prisma ORMとCloudflare D1を使用する際の概念について説明し、Cloudflare D1と他のデータベースプロバイダーとの共通点と相違点を解説し、Cloudflare D1と統合するためのアプリケーション設定プロセスを案内します。

Cloudflare D1に対するPrisma ORMのサポートは、現在プレビュー段階です。GitHubでのフィードバックをお待ちしております。

D1とPrisma ORMを使ってCloudflare Workerをデプロイしたい場合は、このチュートリアルに従ってください。

Cloudflare D1とは？

D1はCloudflareのネイティブなサーバーレスデータベースで、2022年に最初にリリースされました。SQLiteをベースにしており、Cloudflare Workersでアプリケーションをデプロイする際に使用できます。

Cloudflareの地理的分散と、計算能力とデータをアプリケーションユーザーに近づけるという原則に従い、D1は自動読み取りレプリケーションをサポートしています。データベースがどれだけ、どこからクエリを受けているかに基づいて、データベースインスタンスの数と読み取り専用レプリカの場所を動的に管理します。

書き込み操作の場合、クエリは単一のプライマリインスタンスに送信され、すべての読み取りレプリカに変更を伝播し、データの一貫性を保証します。

他のデータベースプロバイダーとの共通点

D1はSQLiteをベースにしています。

D1でPrisma ORMを使用する多くの側面は、他のリレーショナルデータベースでPrisma ORMを使用する場合とまったく同じです。引き続き以下のことができます。

• Prismaスキーマ言語でデータベースをモデル化する
• スキーマでPrisma ORMの既存のsqliteデータベースコネクタを使用する
• アプリケーションでPrisma Clientを使用してD1のデータベースサーバーと通信する

考慮すべき相違点

D1とSQLiteにはいくつかの相違点があります。D1とPrisma ORMを使用する際には、以下の点に注意してください。

• スキーマの変更。 v6.6.0以降、prisma.config.tsファイルを使用すると、prisma db pushを使用できます。ただし、Cloudflareファーストのアプローチを好む場合は、D1のマイグレーションシステムと、マイグレーションワークフローにはprisma migrate diffコマンドを使用できます。詳細については、以下の「D1でのPrisma ORMによるスキーママイグレーション」セクションを参照してください。
• ローカルおよびリモートD1 (SQLite) データベース。CloudflareはD1のローカル版とリモート版を提供しています。ローカル版はwrangler d1 CLIの--localオプションを使用して管理され、.wrangler/stateにあります。リモート版はCloudflareによって管理され、HTTP経由でアクセスされます。

Cloudflare WorkersまたはCloudflare PagesでD1に接続する方法

D1でPrisma ORMを使用する場合、sqliteデータベースプロバイダーと@prisma/adapter-d1のドライバーアダプターを使用する必要があります。

D1とPrisma ORMを使ってCloudflare Workerをデプロイしたい場合は、これらのステップバイステップの手順に従ってください。

D1でのPrisma ORMによるスキーママイグレーション

Prisma ORMとD1でデータベーススキーマをマイグレーションするには、2つのアプローチがあります。

• prisma.config.tsのドライバーアダプター経由でprisma db pushを使用する
• Wrangler CLIを使用する

prisma.config.tsのドライバーアダプター経由でPrisma Migrateを使用する (早期アクセス)

警告

この機能は早期アクセスとしてv6.6.0で導入され、以下のコマンドをサポートしています。

• prisma db push
• prisma db pull
• prisma migrate diff

prisma migrate devやprisma migrate deployなどの他のコマンドは近日中に追加されます。

1. Prisma D1ドライバーアダプターをインストールする

ターミナルでこのコマンドを実行します。

npm install @prisma/adapter-d1

2. 環境変数を設定する

D1アダプターをセットアップするには、いくつかのシークレットを.envファイルに追加する必要があります。

• CLOUDFLARE_ACCOUNT_ID: npx wrangler whoamiで取得するCloudflareアカウントID。
• CLOUDFLARE_DATABASE_ID: D1データベース作成時に取得。既存のD1データベースがある場合、npx wrangler d1 listとnpx wrangler d1 info <database_name>でIDを取得できます。
• CLOUDFLARE_D1_TOKEN: このAPIトークンはPrisma ORMがD1インスタンスと直接通信するために使用されます。作成するには、以下の手順に従ってください。
  1. https://dash.cloudflare.com/profile/api-tokensにアクセスします
  2. トークンを作成をクリックします
  3. カスタムトークンテンプレートをクリックします
  4. テンプレートを入力します: 認識できる名前を使用し、Account / D1 / Edit権限を追加してください。
  5. サマリーに進むをクリックし、次にトークンを作成をクリックします。

これらの情報は.envファイルに追加するか、別のシークレットストアに保存されている場合は直接使用できます。

.env

CLOUDFLARE_ACCOUNT_ID="0773..."
CLOUDFLARE_DATABASE_ID="01f30366-..."
CLOUDFLARE_D1_TOKEN="F8Cg..."

3. Prisma設定ファイルをセットアップする

プロジェクトにprisma.config.tsファイルがあることを確認してください。次に、D1を参照するようにマイグレーションドライバーアダプターをセットアップします。

prisma.config.ts

import path from 'node:path'
import type { PrismaConfig } from 'prisma'
import { PrismaD1HTTP } from '@prisma/adapter-d1'

// import your .env file
import 'dotenv/config'

type Env = {
  CLOUDFLARE_D1_TOKEN: string
  CLOUDFLARE_ACCOUNT_ID: string
  CLOUDFLARE_DATABASE_ID: string
}

export default {
  earlyAccess: true,
  schema: path.join('prisma', 'schema.prisma'),

  migrate: {
    async adapter(env) {
      return new PrismaD1HTTP({
        CLOUDFLARE_D1_TOKEN: env.CLOUDFLARE_D1_TOKEN,
        CLOUDFLARE_ACCOUNT_ID: env.CLOUDFLARE_ACCOUNT_ID,
        CLOUDFLARE_DATABASE_ID: env.CLOUDFLARE_DATABASE_ID,
      })
    },
  },
} satisfies PrismaConfig<Env>

4. データベースをマイグレーションする

Prisma Migrateは、prisma.config.tsで提供された設定に基づいて、リモートD1データベースに対してマイグレーションを実行します。

このワークフローでリモートスキーマを更新するには、以下のコマンドを実行します。

npx prisma db push

注記

データベースのクエリについては、引き続き@prisma/adapter-d1パッケージのPrismaD1ドライバーアダプターを使用してください。

import { PrismaD1HTTP } from '@prisma/adapter-d1'

Wrangler CLIを使用する

Cloudflare D1には独自のマイグレーションシステムが付属しています。我々はネイティブのPrisma Migrateワークフローを使用することを推奨しますが、wrangler d1 migrationsコマンドによるこのマイグレーションシステムも利用可能です。

ただし、このコマンドは、これらのマイグレーションファイル*内に*配置する必要があるデータベーススキーマを作成するためのSQLステートメントを見つけるのに役立ちません。Prisma Clientを使用してデータベースにクエリを実行したい場合、データベーススキーマがPrismaスキーマにマッピングされていることが重要であり、これがPrismaスキーマからSQLステートメントを生成することが推奨される理由です。

D1を使用する場合、その目的のためにprisma migrate diffコマンドを使用できます。

初期マイグレーションの作成

初期マイグレーションを作成するワークフローは以下のとおりです。テーブルのない新規のD1インスタンスがあると仮定します。

1. Prismaデータモデルを更新する

これは、D1インスタンスにマッピングしたいPrismaスキーマの初期バージョンです。

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

2. wrangler CLIを使用してマイグレーションファイルを作成する

次に、wrangler d1 migrations createコマンドを使用してマイグレーションファイルを作成する必要があります。

npx wrangler d1 migrations create __YOUR_DATABASE_NAME__ create_user_table

これが最初のマイグレーションであるため、このコマンドはmigrationsフォルダも作成するようにプロンプトを表示します。マイグレーションファイルを別の場所に保存したい場合は、Wranglerを使用してカスタマイズできることに注意してください。

コマンドが実行され（マイグレーションファイルの場所としてデフォルトのmigrations名を選択したと仮定）、コマンドは以下のフォルダとファイルを生成しました。

migrations/
└── 0001_create_user_table.sql

しかし、D1インスタンスにマイグレーションを適用する前に、現在空の0001_create_user_table.sqlファイルにSQLステートメントを挿入する必要があります。

3. prisma migrate diffを使用してSQLステートメントを生成する

初期SQLステートメントを生成するには、2つの*スキーマ*を比較し（--to-Xと--from-Xオプション経由）、一方から他方に「進化」するために必要なステップを生成するprisma migrate diffコマンドを使用できます。これらのスキーマはPrismaスキーマまたはSQLスキーマのいずれかです。

ただし、初期マイグレーションでは、特別な--from-emptyオプションを使用できます。

npx prisma migrate diff \
  --from-empty \
  --to-schema-datamodel ./prisma/schema.prisma \
  --script \
  --output migrations/0001_create_user_table.sql

上記のコマンドでは以下のオプションを使用しています。

• --from-empty: SQLステートメントのソースは空のスキーマです。
• --to-schema-datamodel ./prisma/schema.prisma: SQLステートメントのターゲットは./prisma/schema.prisma内のデータモデルです。
• --script: 結果をSQLとして出力します。このオプションを省略すると、「マイグレーションステップ」は平易な英語で生成されます。
• --output migrations/0001_create_user_table.sql: 結果をmigrations/0001_create_user_table.sqlに保存します。

このコマンドを実行すると、migrations/0001_create_user_table.sqlには以下の内容が含まれます。

migrations/0001_create_user_table.sql

-- CreateTable
CREATE TABLE "User" (
    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    "email" TEXT NOT NULL,
    "name" TEXT
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

4. wrangler d1 migrations applyを使用してマイグレーションを実行する

最後に、D1インスタンスに対してマイグレーションを適用できます。

ローカルインスタンスの場合は、実行します。

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --local

リモートインスタンスの場合は、実行します。

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --remote

さらなるマイグレーションでスキーマを進化させる

それ以降のマイグレーションでは、同じワークフローを使用できますが、--from-emptyを使用する代わりに--from-local-d1を使用する必要があります。これは、prisma migrate diffコマンドのソーススキーマがローカルD1インスタンスの現在のスキーマになり、ターゲットは（その後更新された）Prismaスキーマのままだからです。

1. Prismaデータモデルを更新する

別のモデルでPrismaスキーマを更新したと仮定します。

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id       Int    @id @default(autoincrement())
  title    String
  author   User   @relation(fields: [authorId], references: [id])
  authorId Int
}

2. wrangler CLIを使用してマイグレーションファイルを作成する

以前と同様に、まずマイグレーションファイルを作成する必要があります。

npx wrangler d1 migrations create __YOUR_DATABASE_NAME__ create_post_table

コマンドが実行されると（ここでもマイグレーションファイルの場所としてデフォルトのmigrations名を選択したと仮定）、migrationsフォルダ内に新しいファイルが作成されます。

migrations/
├── 0001_create_user_table.sql
└── 0002_create_post_table.sql

以前と同様に、現在空の0002_create_post_table.sqlファイルにSQLステートメントを挿入する必要があります。

3. prisma migrate diffを使用してSQLステートメントを生成する

上記で説明したように、ソーススキーマを指定するために、--from-emptyの代わりに--from-local-d1を使用する必要があります。

npx prisma migrate diff \
  --from-local-d1 \
  --to-schema-datamodel ./prisma/schema.prisma \
  --script \
  --output migrations/0002_create_post_table.sql

上記のコマンドでは以下のオプションを使用しています。

• --from-local-d1: SQLステートメントのソースはローカルのD1データベースファイルです。
• --to-schema-datamodel ./prisma/schema.prisma: SQLステートメントのターゲットは./prisma/schema.prisma内のデータモデルです。
• --script: 結果をSQLとして出力します。このオプションを省略すると、「マイグレーションステップ」は平易な英語で生成されます。
• --output migrations/0002_create_post_table.sql: 結果をmigrations/0002_create_post_table.sqlに保存します。

このコマンドを実行すると、migrations/0002_create_post_table.sqlには以下の内容が含まれます。

migrations/0002_create_post_table.sql

-- CreateTable
CREATE TABLE "Post" (
    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    "title" TEXT NOT NULL,
    "authorId" INTEGER NOT NULL,
    CONSTRAINT "Post_authorId_fkey" FOREIGN KEY ("authorId") REFERENCES "User" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
);

4. wrangler d1 migrations applyを使用してマイグレーションを実行する

最後に、D1インスタンスに対してマイグレーションを適用できます。

ローカルインスタンスの場合は、実行します。

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --local

リモートインスタンスの場合は、実行します。

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --remote

制限事項

トランザクションはサポートされていません

Cloudflare D1は現在トランザクションをサポートしていません（未解決の機能リクエストを参照）。結果として、Prisma ORMはCloudflare D1のトランザクションをサポートしていません。PrismaのD1アダプターを使用する場合、暗黙的および明示的なトランザクションは無視され、個別のクエリとして実行されるため、トランザクションのACID特性の保証が破られます。

Prisma MigrateはリモートD1データベースのみをサポートします

Wrangler CLIは--localオプションと--remoteオプションを介してローカルD1とリモートD1（つまりSQLite）データベースインスタンスを区別できます。この区別は、現在のネイティブのPrisma Migrateワークフローでは利用できません。