如何在 Cloudflare D1 中使用 Prisma ORM
簡介
本指南將向您展示如何在 Cloudflare D1（一個在 Cloudflare 邊緣網路上執行的無伺服器 SQL 資料庫）中使用 Prisma ORM。您將學習如何使用 D1 設定 Prisma ORM、處理遷移以及將應用程式部署到 Cloudflare Workers。您可以在 GitHub 上找到一個部署就緒的示例。
先決條件
在開始本指南之前，請確保您已具備：
- 一個 Cloudflare 賬戶
- 已安裝 Node.js（版本 18 或更高）
- 已安裝 Wrangler CLI（版本 3.39.0 或更高）
- 對 Cloudflare Workers 和 D1 有基本瞭解
1. 配置 Prisma schema
在您的 Prisma schema 中，將 driverAdapters 預覽功能新增到 generator 塊中，並將 datasource 的 provider 設定為 sqlite。如果您剛剛使用 prisma init 啟動了 Prisma schema，請務必新增以下 User 模型：
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：
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. 設定資料庫遷移
我們建議使用 prisma migrate 來保持 D1 中的資料遷移。但是，如果您更喜歡使用 Cloudflare 的遷移系統，該工作流也可用
4.1 新增所需的環境變數
為了使用 Prisma D1 介面卡，您需要向 .env 檔案新增一些金鑰：
DATABASE_URL：您的本地 D1 例項的路徑。通常是"file:./prisma/db.sqlite"。CLOUDFLARE_ACCOUNT_ID：您的 Cloudflare 賬戶 ID，透過npx wrangler whoami獲取。CLOUDFLARE_DATABASE_ID：您的資料庫 ID，在D1 資料庫建立期間檢索。CLOUDFLARE_D1_TOKEN：此 API 令牌由 Prisma ORM 用於直接與您的 D1 例項通訊。要建立此令牌，請按照以下步驟操作：- 訪問 https://dash.cloudflare.com/profile/api-tokens
- 點選“建立令牌”
- 點選“自定義令牌”模板
- 填寫模板：確保使用易於識別的名稱並新增
Account / D1 / Edit許可權。 - 點選“繼續摘要”，然後點選“建立令牌”。
您現在可以儲存這些金鑰供 Prisma ORM 使用。我們建議使用 .env 檔案進行本地開發，但任何金鑰儲存都可以。
DATABASE_URL="file:./prisma/db.sqlite"
CLOUDFLARE_ACCOUNT_ID="0773..."
CLOUDFLARE_DATABASE_ID="01f30366-..."
CLOUDFLARE_D1_TOKEN="F8Cg..."
4.2 配置 Prisma Config
確保您的專案根目錄中有一個 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>
這將允許 prisma migrate 與您的 D1 資料庫互動。
4.3 執行您的第一次遷移
您現在可以執行 prisma migrate dev 來遷移您的資料庫以匹配您的本地 schema
npx prisma migrate dev --name init
我們再建立一些虛擬資料，以便在 Worker 執行後可以查詢。這次，我們將使用 wrangler 執行 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
為了使用 Prisma ORM 從 Worker 查詢您的資料庫，您需要：
- 將
DB繫結新增到Env介面。（或者，您可以執行npx wrangler types從繫結中生成Env型別，並將其儲存在一個名為worker-configuration.d.ts的單獨檔案中。） - 使用
PrismaD1驅動介面卡例項化PrismaClient。 - 使用 Prisma Client 傳送查詢並返回結果。
開啟 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://: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)' }]
後續步驟
現在您已經使用 Cloudflare D1 設定了 Prisma ORM，您可以：
- 使用 Prisma 強大的查詢 API 新增更復雜的查詢
- 設定 Prisma Studio 進行資料庫管理
- 實施資料庫監控
- 新增自動化測試
更多資訊
與 Prisma 保持聯絡
透過以下方式與我們聯絡，繼續您的 Prisma 之旅： 我們的活躍社群。保持瞭解、參與並與其他開發者協作。
- 在 X 上關注我們 獲取公告、直播活動和實用技巧。
- 加入我們的 Discord 提問、與社群交流，並透過對話獲得積極支援。
- 在 YouTube 上訂閱 獲取教程、演示和直播。
- 在 GitHub 上參與 透過點贊倉庫、報告問題或為問題貢獻程式碼。