如何将 Prisma ORM 与 Cloudflare D1 结合使用
介绍
本指南将向您展示如何将 Prisma ORM 与 Cloudflare D1（一个在 Cloudflare 边缘网络上运行的无服务器 SQL 数据库）结合使用。您将学习如何使用 D1 设置 Prisma ORM、处理迁移并将应用程序部署到 Cloudflare Workers。您可以在 GitHub 上找到一个可部署的示例。
先决条件
在开始本指南之前，请确保您已具备以下条件：
- 一个 Cloudflare 账户
- 已安装 Node.js（版本 18 或更高版本）
- 已安装 Wrangler CLI（版本 3.39.0 或更高版本）
- 对 Cloudflare Workers 和 D1 有基本了解
1. 创建一个新的 Cloudflare Worker 并初始化 Prisma ORM
运行以下命令创建一个新的 Cloudflare Worker 项目
npm create cloudflare@latest d1-tutorial -- --type=hello-world --ts=true --git=true --deploy=false
然后进入新创建的目录
cd d1-tutorial
并在项目中初始化 Prisma ORM
npx prisma init --datasource-provider sqlite
并将 Prisma ORM CLI 作为开发依赖项安装
npm install --save-dev prisma
2. 配置 Prisma schema
在您的 Prisma schema 中，将 datasource 的 provider 设置为 sqlite。如果您刚刚使用 prisma init 引导了 Prisma schema，请务必在 generator 块中添加 runtime = "cloudflare" 和以下 User 模型
generator client {
provider = "prisma-client"
output = "../src/generated/prisma"
runtime = "cloudflare"
}
datasource db {
provider = "sqlite"
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
}
3. 安装依赖项
接下来，安装所需的包
npm install @prisma/client @prisma/adapter-d1 dotenv
此外，请务必使用高于 wrangler@^3.39.0 的 Wrangler CLI 版本，否则下一节中使用的 --remote 标志将不可用。
4. 创建 D1 数据库
运行以下命令创建一个新的 D1 数据库
npx wrangler@latest d1 create __YOUR_D1_DATABASE_NAME__
__YOUR_D1_DATABASE_NAME__ 是一个占位符，应替换为您要为 D1 数据库指定的名称。例如，您可以使用 prisma-d1-example。
此命令将使用 Cloudflare 进行身份验证，并要求您选择一个 Cloudflare 账户。之后，它将创建一个新的 D1 数据库并输出数据库 ID 和名称
✅ Successfully created DB '__YOUR_D1_DATABASE_NAME__' in region __REGION__
Created your new D1 database.
{
"d1_databases": [
{
"binding": "DB",
"database_name": "__YOUR_D1_DATABASE_NAME__",
"database_id": "<unique-ID-for-your-database>"
}
]
}
复制终端输出并将内容添加到您的 wrangler.jsonc 文件中。此文件用于配置您的 Cloudflare Worker 及其绑定。
要将您的 Workers 连接到 D1 实例，请将以下绑定添加到您的 wrangler.jsonc
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "d1-tutorial",
"main": "src/index.ts",
"compatibility_date": "2025-08-05",
"d1_databases": [
{
"binding": "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__。
5. 设置数据库迁移
对于 Cloudflare D1，您将使用 Prisma 的迁移工作流结合 Wrangler CLI 来管理您的数据库 schema。由于 D1 是一个无服务器 SQLite 数据库，我们将使用 prisma migrate diff 生成迁移 SQL，然后使用 Wrangler 应用它。
5.1 设置环境变量
在项目根目录中添加一个 .env 文件，其中包含您的本地数据库 URL
DATABASE_URL="file:./prisma/db.sqlite"
还在项目根目录中创建一个 prisma.config.ts 文件
import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';
export default defineConfig({
schema: 'prisma/schema.prisma',
migrations: {
path: 'prisma/migrations',
},
datasource: {
url: env('DATABASE_URL'),
},
});
5.2 生成迁移 SQL
首先，在 prisma 文件夹中创建一个 migrations 目录，并创建一个名为 0001_init.sql 的文件
mkdir -p prisma/migrations
现在使用 prisma migrate diff 生成创建数据库 schema 所需的 SQL
npx prisma migrate diff \
--from-empty \
--to-schema prisma/schema.prisma \
--script > prisma/migrations/0001_init.sql
此命令生成一个 SQL 文件，其中包含创建数据库表所需的语句。您可以在 prisma/migrations/0001_init.sql 中检查生成的 SQL。
5.3 将迁移应用于 D1
现在使用 Wrangler 将迁移应用于您的本地和远程 D1 数据库
# Apply to local database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --local --file=./prisma/migrations/0001_init.sql
# Apply to remote database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --remote --file=./prisma/migrations/0001_init.sql
将 __YOUR_D1_DATABASE_NAME__ 替换为在第 4 步中创建的 D1 数据库的实际名称。
5.4 添加示例数据
让我们创建一些虚拟数据，以便在 Worker 运行后进行查询
# 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
对于未来的 schema 更改，您可以使用以下命令生成新的迁移文件
npx prisma migrate diff \
--from-local-d1 \
--to-schema-datamodel prisma/schema.prisma \
--script > migrations/0002_add_new_field.sql
然后使用上面显示的相同 wrangler d1 execute 命令应用它们。
6. 实现 Worker
在将 Prisma Client 查询添加到 Worker 之前，您需要使用以下命令生成 Prisma Client
npx prisma generate
为了使用 Prisma ORM 从 Worker 查询数据库，您需要
- 将
DB绑定添加到Env接口。此DB名称与您在wrangler.jsonc中配置的绑定名称匹配。（或者，您可以运行npx wrangler types以在名为worker-configuration.d.ts的单独文件中从绑定生成Env类型。） - 使用
PrismaD1驱动程序适配器实例化PrismaClient，传入访问 D1 数据库绑定的env.DB。 - 使用 Prisma Client 发送查询并返回结果。
打开 src/index.ts 并将其全部内容替换为以下内容
import { PrismaClient } from './generated/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);
ctx.waitUntil(prisma.$disconnect()); // or just await prisma.$disconnect()
return new Response(result);
},
};
我们在此处明确调用 prisma.$disconnect() 以保证及时释放资源，否则 worker 可能会耗尽内存。
7. 本地运行 Worker
有了数据库查询和生成的 Prisma Client，您可以在本地运行 Worker。
如果您的 Worker 需要任何环境变量，请在项目根目录中创建一个 .dev.vars 文件。对于此示例，我们不需要任何额外的环境变量，因为 D1 绑定已在 wrangler.jsonc 中配置。
现在在本地运行 Worker
npm run dev
现在您可以在浏览器中打开 https://:8787 以查看数据库查询的结果
;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Local)' }]
8. 部署 Worker
要部署 Worker，请运行以下命令
npm run deploy
您部署的 Worker 可以通过 https://d1-tutorial.USERNAME.workers.dev 访问（将 USERNAME 替换为您的 Cloudflare 账户用户名）。如果您在浏览器中导航到该 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 上参与 加星收藏存储库、报告问题或为问题做出贡献。