跳到主要內容

如何搭配 Cloudflare D1 使用 Prisma ORM

10 分鐘

簡介​

本指南將說明如何搭配 Cloudflare D1（一種在 Cloudflare 邊緣網路運行的無伺服器 SQL 資料庫）使用 Prisma ORM。您將學習如何使用 D1 設定 Prisma ORM、處理遷移，以及將應用程式部署到 Cloudflare Workers。您可以在 GitHub 上找到可直接部署的範例。

先決條件​

開始本指南之前，請確保您已具備以下條件

  • Cloudflare 帳戶
  • 已安裝 Node.js (16 或更高版本)
  • 已安裝 Wrangler CLI (3.39.0 或更高版本)
  • 基本熟悉 Cloudflare Workers 和 D1

1. 設定 Prisma schema​

在您的 Prisma schema 中，將 driverAdapters 預覽功能新增至 generator 區塊，並將 datasource 的 provider 設定為 sqlite。如果您剛使用 prisma init 啟動 Prisma schema，也請務必將以下 User 模型新增至其中

schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

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

2. 安裝依賴套件​

接下來，安裝必要的套件

npm install @prisma/adapter-d1

此外，請務必使用高於 wrangler@^3.39.0 的 Wrangler CLI 版本，否則在接下來的章節中使用的 --remote 標誌將無法使用。

3. 設定 D1 資料庫連線​

若要將您的 Workers 連接到 D1 實例，請將以下繫結新增至您的 wrangler.toml

wrangler.toml
name = "prisma-cloudflare-worker-example"
main = "src/index.ts"
compatibility_date = "2024-03-20"
compatibility_flags = ["nodejs_compat"]

[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "__YOUR_D1_DATABASE_NAME__" # to be replaced
database_id = "__YOUR_D1_DATABASE_ID__"     # to be replaced

請注意，上方程式碼片段中的 __YOUR_D1_DATABASE_NAME__ 和 __YOUR_D1_DATABASE_ID__ 是預留位置，應替換為您自己的 D1 實例的資料庫名稱和 ID。

如果您無法從終端機輸出中取得此 ID，您也可以在 Cloudflare 儀表板中找到它，或在終端機中執行 npx wrangler d1 list 和 npx wrangler d1 info __YOUR_D1_DATABASE_NAME__。

4. 設定資料庫遷移​

使用 D1 的遷移系統建立並套用遷移

# Create migration directory and file
npx wrangler d1 migrations create __YOUR_D1_DATABASE_NAME__ create_user_table

再次將 __YOUR_D1_DATABASE_NAME__ 替換為您的資料庫名稱，並在出現提示時確認您要建立 migrations 目錄。執行此命令後，應該會有一個名為 migrations 的新資料夾，其中包含一個名為 0001_create_user_table.sql 的檔案。

您現在可以產生必要的 SQL 陳述式，以建立可對應至 Prisma schema 中 User 模型的 User 表格，如下所示

# Generate SQL using Prisma Migrate
npx prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql

請注意，產生的 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");

您現在需要使用 wrangler d1 migrations apply 命令將此 SQL 陳述式傳送至 D1。請注意，此命令接受兩個選項

  • --local：針對 D1 的本機版本執行陳述式。D1 的本機版本是一個 SQLite 資料庫檔案，將位於您的專案中。當您想要在本機電腦上開發和測試 Worker 時，此方法非常有用。在 Cloudflare 文件 中瞭解更多資訊。
  • --remote：針對 D1 的遠端版本執行陳述式。此版本由您已部署的 Cloudflare Workers 使用。在 Cloudflare 文件 中瞭解更多資訊。

在本教學課程中，您將同時執行兩者：在本機測試 Worker 並在之後部署它。因此，您需要執行以下兩個命令。開啟您的終端機並貼上以下命令

# For the local database
npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --local

# For the remote database
npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --remote

和之前一樣，您需要將 __YOUR_D1_DATABASE_NAME__ 替換為您的 D1 資料庫名稱。

讓我們也建立一些虛擬資料，以便在 Worker 執行後可以查詢。這次，您將執行 SQL 陳述式，而無需將其儲存在檔案中

# For the local database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --local

# For the remote database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Remote)');" --remote

5. 實作 Worker​

在將 Prisma Client 查詢新增至 Worker 之前，您需要使用以下命令產生 Prisma Client

npx prisma generate

為了從 Worker 使用 Prisma ORM 查詢您的資料庫，您需要

  1. 將 DB 繫結新增至 Env 介面。(或者，您可以執行 npx wrangler types 從名為 worker-configuration.d.ts 的個別檔案中的繫結產生 Env 類型。)
  2. 使用 PrismaD1 驅動程式介面例項化 PrismaClient。
  3. 使用 Prisma Client 傳送查詢並傳回結果。

開啟 src/index.ts 並將整個內容替換為以下內容

src/index.ts
import { PrismaClient } from '@prisma/client'
import { PrismaD1 } from '@prisma/adapter-d1'

export interface Env {
  DB: D1Database
}

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    const adapter = new PrismaD1(env.DB)
    const prisma = new PrismaClient({ adapter })

    const users = await prisma.user.findMany()
    const result = JSON.stringify(users)
    return new Response(result)
  },
}

6. 在本機執行 Worker​

在資料庫查詢到位並產生 Prisma Client 後，您可以繼續在本機執行 Worker

npm run dev

現在您可以開啟瀏覽器並前往 https://127.0.0.1:8787 以查看資料庫查詢的結果

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Local)' }]

7. 設定 DATABASE_URL 環境變數並部署 Worker​

若要部署 Worker，請執行以下命令

npm run deploy

您的已部署 Worker 可透過 https://prisma-d1-example.USERNAME.workers.dev 存取。如果您在瀏覽器中導覽至該 URL，您應該會看到從您的遠端 D1 資料庫查詢的以下資料

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Remote)' }]

後續步驟​

現在您已設定 Prisma ORM 與 Cloudflare D1，您可以

  • 使用 Prisma 強大的查詢 API 新增更複雜的查詢
  • 設定 Prisma Studio 以進行資料庫管理
  • 實作資料庫監控
  • 新增自動化測試

如需更多資訊和更新