跳到主要内容

部署到 Cloudflare Workers & Pages

本页涵盖了将使用 Prisma ORM 的应用程序部署到 Cloudflare WorkerCloudflare Pages 所需了解的一切。

部署到 Cloudflare Workers 的一般注意事项

本节涵盖了在使用 Prisma ORM 部署到 Cloudflare Workers 或 Pages 时需要注意的一般事项,无论您使用哪种数据库提供商。

使用 Prisma Postgres

您可以使用 Prisma Postgres 并部署到 Cloudflare Workers。

创建 Worker 后,运行

npx prisma@latest init --db

输入项目名称并选择数据库区域。

此命令

  • 将您的 CLI 连接到您的账户。如果您未登录或没有账户,您的浏览器将打开以引导您创建新账户或登录现有账户。
  • 创建一个包含数据库模型 `schema.prisma` 文件的 `prisma` 目录。
  • 创建一个包含您的 `DATABASE_URL` 的 `.env` 文件(例如,对于 Prisma Postgres,它应该类似于 `DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."`)。

您需要安装使用 Prisma Postgres 所需的客户端扩展

npm i @prisma/extension-accelerate

并在您的应用程序代码中用该扩展来扩展 `PrismaClient`

import { PrismaClient } from "@prisma/client/edge";
import { withAccelerate } from "@prisma/extension-accelerate";

export interface Env {
DATABASE_URL: string;
}

export default {
async fetch(request, env, ctx) {
const prisma = new PrismaClient({
datasourceUrl: env.DATABASE_URL,
}).$extends(withAccelerate());

const users = await prisma.user.findMany();
const result = JSON.stringify(users);
return new Response(result);
},
} satisfies ExportedHandler<Env>;

然后设置辅助脚本以执行迁移并生成 `PrismaClient`,如本节所示

注意

您需要安装 `dotenv-cli` 包,因为 Cloudflare Workers 不支持 `.env` 文件。您可以通过运行以下命令在您的项目中本地安装该包:`npm install -D dotenv-cli`。

使用边缘兼容驱动程序

当部署使用 Prisma ORM 的 Cloudflare Worker 时,您需要使用边缘兼容驱动程序及其各自的 Prisma ORM 驱动程序适配器

适用于 Cloudflare Workers 和 Pages 的边缘兼容驱动程序是

node-mysql2 驱动程序也正在进行工作,未来也将使 Cloudflare Workers 和 Pages 能够访问传统 MySQL 数据库。

注意

如果您的应用程序使用 PostgreSQL,我们建议使用Prisma Postgres。它在边缘运行时中得到全面支持,并且不需要专门的边缘兼容驱动程序。对于其他数据库,Prisma Accelerate 扩展了边缘兼容性,因此您可以从任何边缘函数提供商连接到任何数据库。

将数据库连接 URL 设置为环境变量

首先,请确保在您的 Prisma schema 中将 `DATABASE_URL` 设置为 `datasource` 的 `url`

datasource db {
provider = "postgresql" // this might also be `mysql` or another value depending on your database
url = env("DATABASE_URL")
}

开发

开发中使用您的 Worker 时,您可以通过本地的 .dev.vars 文件 配置数据库连接。

假设您使用上述的 `DATABASE_URL` 环境变量,您可以将其设置在 `.dev.vars` 中,如下所示

.dev.vars
DATABASE_URL="your-database-connection-string"

在上述代码片段中,`your-database-connection-string` 是一个占位符,您需要将其替换为您自己的连接字符串值,例如

.dev.vars
DATABASE_URL="postgresql://admin:mypassword42@somehost.aws.com:5432/mydb"

请注意,`.dev.vars` 文件与 Prisma ORM 通常使用的 `.env` 文件不兼容。

这意味着您需要确保 Prisma ORM 在需要时(例如运行 `prisma migrate dev` 等 Prisma CLI 命令时)能够访问环境变量。

有几种方法可以实现这一点

  • 使用 dotenv 运行 Prisma CLI 命令,以指定 CLI 应从何处读取环境变量,例如
    dotenv -e .dev.vars -- npx prisma migrate dev
  • 在 `package.json` 中创建一个脚本,通过 dotenv 读取 `.dev.vars`。然后您可以按如下方式执行 `prisma` 命令:`npm run env -- npx prisma migrate dev`。以下是脚本参考
    package.json
    "scripts":  { "env": "dotenv -e .dev.vars" }
  • 将 `DATABASE_URL` 和任何其他相关环境变量复制到一个名为 `.env` 的新文件中,该文件可供 Prisma ORM 使用。
注意

如果您使用需要 `dotenv` 的方法,您需要安装 dotenv-cli 包。您可以通过运行此命令在您的项目中本地安装该包:`npm install -D dotenv-cli`。

生产环境

将您的 Worker 部署到生产环境时,您需要使用 `wrangler` CLI 设置数据库连接

npx wrangler secret put DATABASE_URL

该命令是交互式的,下一步将要求您在终端中输入 `DATABASE_URL` 环境变量的值。

注意

此命令要求您进行身份验证,如果您未登录,它将要求您登录 Cloudflare 账户。

免费账户的大小限制

Cloudflare 对免费套餐的 Workers 有 3 MB 的大小限制。如果您的应用程序包(含 Prisma ORM)超出此大小,我们建议您升级到付费 Worker 计划或使用 Prisma Accelerate 部署您的应用程序。

使用 @cloudflare/next-on-pages 将 Next.js 应用程序部署到 Cloudflare Pages

Cloudflare 提供了一个选项,可以使用 @cloudflare/next-on-pages 在 Cloudflare Pages 上运行 Next.js 应用程序,请参阅文档以获取说明。

根据一些测试,我们发现以下情况

  • 您可以使用 PlanetScale 或 Neon 无服务器驱动程序进行部署。
  • 使用 `pg` 的传统 PostgreSQL 部署不起作用,因为 `pg` 本身目前不支持 `@cloudflare/next-on-pages`(参见此处)。

如果您发现情况有任何变化,请随时通过 Discord 联系我们。

使用 `node` 在本地运行时设置 PRISMA_CLIENT_FORCE_WASM=1

一些框架(例如 hono)使用 `node` 而不是 `wrangler` 在本地运行 Workers。如果您正在使用此类框架或因其他原因使用 `node` 在本地运行 Worker,您需要设置 `PRISMA_CLIENT_FORCE_WASM` 环境变量

export PRISMA_CLIENT_FORCE_WASM=1

数据库特定注意事项 & 示例

本节提供了使用 Prisma ORM 部署 Cloudflare Worker 的数据库特定说明。

先决条件

作为以下部分的先决条件,您需要有一个在本地运行的 Cloudflare Worker,并安装 Prisma CLI。

如果您还没有,可以运行这些命令

npm create cloudflare@latest prisma-cloudflare-worker-example -- --type hello-world
cd prisma-cloudflare-worker-example
npm install prisma --save-dev && npm install @prisma/client
npx prisma init --output ../generated/prisma

您还需要一个您选择的数据库提供商的数据库实例。请参阅该提供商的相应文档以设置该实例。

下面的示例中我们将使用默认的 `User` 模型

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

PostgreSQL(传统)

如果您正在使用通过 TCP 和 `pg` 驱动程序访问的传统 PostgreSQL 数据库,您需要

  • 使用 `@prisma/adapter-pg` 数据库适配器(通过 `driverAdapters` 预览功能)
  • 在 `wrangler.toml` 中设置 `node_compat = true`(请参阅 Cloudflare 文档

1. 配置 Prisma schema & 数据库连接

注意

如果您没有要部署的项目,请按照先决条件中的说明启动一个包含 Prisma ORM 的基本 Cloudflare Worker。

首先,确保数据库连接已正确配置。在您的 Prisma schema 中,将 `datasource` 块的 `url` 设置为 `DATABASE_URL` 环境变量。您还需要启用 `driverAdapters` 功能标志

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

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

接下来,您需要将 `DATABASE_URL` 环境变量设置为您的数据库连接字符串的值。您将在 Cloudflare 使用的名为 `.dev.vars` 的文件中完成此操作

.dev.vars
DATABASE_URL="postgresql://admin:mypassword42@somehost.aws.com:5432/mydb"

由于 Prisma CLI 默认仅与 `.env` 文件兼容,您可以调整 `package.json` 中的以下脚本,该脚本从 `.dev.vars` 加载环境变量。然后,您可以使用此脚本在执行 `prisma` 命令之前加载环境变量。

将此脚本添加到您的 `package.json`

package.json
{
// ...
"scripts": {
// ....
"env": "dotenv -e .dev.vars"
},
// ...
}

现在,您可以按如下方式执行 Prisma CLI 命令,同时确保该命令可以访问 `.dev.vars` 中的环境变量

npm run env -- npx prisma

2. 安装依赖项

接下来,安装所需的软件包

npm install @prisma/adapter-pg

3. 在 `wrangler.toml` 中设置 node_compat = true

在您的 `wrangler.toml` 文件中,添加以下行

wrangler.toml
node_compat = true
注意

对于 Cloudflare Pages,官方不支持使用 `node_compat`。如果您想在 Cloudflare Pages 中使用 `pg`,可以在此处找到一个变通方法。

4. 迁移您的数据库 schema(如果适用)

如果您在上面运行了 `npx prisma init`,您需要迁移您的数据库 schema 以创建 Prisma schema 中定义的 `User` 表(如果您的数据库中已有所需的所有表,则可以跳过此步骤)

npm run env -- npx prisma migrate dev --name init

5. 在 Worker 中使用 Prisma Client 向数据库发送查询

这是一个您可以用来实例化 `PrismaClient` 并向数据库发送查询的代码片段示例

import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

export default {
async fetch(request, env, ctx) {
const adapter = new PrismaPg({ connectionString: env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

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

6. 在本地运行 Worker

要在本地运行 Worker,您可以运行 `wrangler dev` 命令

npx wrangler dev

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

要部署 Worker,您首先需要通过 `wrangler` CLI设置 `DATABASE_URL` 环境变量

npx wrangler secret put DATABASE_URL

该命令是交互式的,下一步将要求您在终端中输入 `DATABASE_URL` 环境变量的值。

注意

此命令要求您进行身份验证,如果您未登录,它将要求您登录 Cloudflare 账户。

然后您可以继续部署 Worker

npx wrangler deploy

该命令将输出您可以访问已部署 Worker 的 URL。

PlanetScale

如果您正在使用 PlanetScale 数据库,您需要

  • 使用 `@prisma/adapter-planetscale` 数据库适配器(通过 `driverAdapters` 预览功能)

  • 手动删除冲突的 `cache` 字段

    export default {
    async fetch(request, env, ctx) {
    const adapter = new PrismaPlanetScale({
    url: env.DATABASE_URL,
    // see https://github.com/cloudflare/workerd/issues/698
    fetch(url, init) {
    delete init['cache']
    return fetch(url, init)
    },
    })
    const prisma = new PrismaClient({ adapter })

    // ...
    },
    }

1. 配置 Prisma schema & 数据库连接

注意

如果您没有要部署的项目,请按照先决条件中的说明启动一个包含 Prisma ORM 的基本 Cloudflare Worker。

首先,确保数据库连接已正确配置。在您的 Prisma schema 中,将 `datasource` 块的 `url` 设置为 `DATABASE_URL` 环境变量。您还需要启用 `driverAdapters` 功能标志

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

datasource db {
provider = "mysql"
url = env("DATABASE_URL")
relationMode = "prisma" // required for PlanetScale (as by default foreign keys are disabled)
}

接下来,您需要将 `DATABASE_URL` 环境变量设置为您的数据库连接字符串的值。您将在 Cloudflare 使用的名为 `.dev.vars` 的文件中完成此操作

.dev.vars
DATABASE_URL="mysql://32qxa2r7hfl3102wrccj:password@us-east.connect.psdb.cloud/demo-cf-worker-ps?sslaccept=strict"

由于 Prisma CLI 默认仅与 `.env` 文件兼容,您可以调整 `package.json` 中的以下脚本,该脚本从 `.dev.vars` 加载环境变量。然后,您可以使用此脚本在执行 `prisma` 命令之前加载环境变量。

将此脚本添加到您的 `package.json`

package.json
{
// ...
"scripts": {
// ....
"env": "dotenv -e .dev.vars"
},
// ...
}

现在,您可以按如下方式执行 Prisma CLI 命令,同时确保该命令可以访问 `.dev.vars` 中的环境变量

npm run env -- npx prisma

2. 安装依赖项

接下来,安装所需的软件包

npm install @prisma/adapter-planetscale

3. 迁移您的数据库 schema(如果适用)

如果您在上面运行了 `npx prisma init`,您需要迁移您的数据库 schema 以创建 Prisma schema 中定义的 `User` 表(如果您的数据库中已有所需的所有表,则可以跳过此步骤)

npm run env -- npx prisma db push

4. 在 Worker 中使用 Prisma Client 向数据库发送查询

这是一个您可以用来实例化 `PrismaClient` 并向数据库发送查询的代码片段示例

import { PrismaClient } from '@prisma/client'
import { PrismaPlanetScale } from '@prisma/adapter-planetscale'

export default {
async fetch(request, env, ctx) {
const adapter = new PrismaPlanetScale({
url: env.DATABASE_URL,
// see https://github.com/cloudflare/workerd/issues/698
fetch(url, init) {
delete init['cache']
return fetch(url, init)
},
})
const prisma = new PrismaClient({ adapter })

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

6. 在本地运行 Worker

要在本地运行 Worker,您可以运行 `wrangler dev` 命令

npx wrangler dev

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

要部署 Worker,您首先需要通过 `wrangler` CLI设置 `DATABASE_URL` 环境变量

npx wrangler secret put DATABASE_URL

该命令是交互式的,下一步将要求您在终端中输入 `DATABASE_URL` 环境变量的值。

注意

此命令要求您进行身份验证,如果您未登录,它将要求您登录 Cloudflare 账户。

然后您可以继续部署 Worker

npx wrangler deploy

该命令将输出您可以访问已部署 Worker 的 URL。

Neon

如果您正在使用 Neon 数据库,您需要

  • 使用 `@prisma/adapter-neon` 数据库适配器(通过 `driverAdapters` 预览功能)

1. 配置 Prisma schema & 数据库连接

注意

如果您没有要部署的项目,请按照先决条件中的说明启动一个包含 Prisma ORM 的基本 Cloudflare Worker。

首先,确保数据库连接已正确配置。在您的 Prisma schema 中,将 `datasource` 块的 `url` 设置为 `DATABASE_URL` 环境变量。您还需要启用 `driverAdapters` 功能标志

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

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

接下来,您需要将 `DATABASE_URL` 环境变量设置为您的数据库连接字符串的值。您将在 Cloudflare 使用的名为 `.dev.vars` 的文件中完成此操作

.dev.vars
DATABASE_URL="postgresql://janedoe:password@ep-nameless-pond-a23b1mdz.eu-central-1.aws.neon.tech/neondb?sslmode=require"

由于 Prisma CLI 默认仅与 `.env` 文件兼容,您可以调整 `package.json` 中的以下脚本,该脚本从 `.dev.vars` 加载环境变量。然后,您可以使用此脚本在执行 `prisma` 命令之前加载环境变量。

将此脚本添加到您的 `package.json`

package.json
{
// ...
"scripts": {
// ....
"env": "dotenv -e .dev.vars"
},
// ...
}

现在,您可以按如下方式执行 Prisma CLI 命令,同时确保该命令可以访问 `.dev.vars` 中的环境变量

npm run env -- npx prisma

2. 安装依赖项

接下来,安装所需的软件包

npm install @prisma/adapter-neon

3. 迁移您的数据库 schema(如果适用)

如果您在上面运行了 `npx prisma init`,您需要迁移您的数据库 schema 以创建 Prisma schema 中定义的 `User` 表(如果您的数据库中已有所需的所有表,则可以跳过此步骤)

npm run env -- npx prisma migrate dev --name init

5. 在 Worker 中使用 Prisma Client 向数据库发送查询

这是一个您可以用来实例化 `PrismaClient` 并向数据库发送查询的代码片段示例

import { PrismaClient } from '@prisma/client'
import { PrismaNeon } from '@prisma/adapter-neon'

export default {
async fetch(request, env, ctx) {
const adapter = new PrismaNeon({ connectionString: env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

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

6. 在本地运行 Worker

要在本地运行 Worker,您可以运行 `wrangler dev` 命令

npx wrangler dev

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

要部署 Worker,您首先需要通过 `wrangler` CLI设置 `DATABASE_URL` 环境变量

npx wrangler secret put DATABASE_URL

该命令是交互式的,下一步将要求您在终端中输入 `DATABASE_URL` 环境变量的值。

注意

此命令要求您进行身份验证,如果您未登录,它将要求您登录 Cloudflare 账户。

然后您可以继续部署 Worker

npx wrangler deploy

该命令将输出您可以访问已部署 Worker 的 URL。

© . All rights reserved.