Prisma Accelerate 入门

先决条件

开始使用 Accelerate，你需要具备以下条件：

• 一
• 一个使用 Prisma Client `4.16.1` 或更高版本的项目。如果你的项目使用交互式事务，你需要使用 `5.1.1` 或更高版本。（我们始终推荐使用最新版本的 Prisma。）
• 一个托管的 PostgreSQL、MySQL/MariaDB、PlanetScale、CockroachDB 或 MongoDB 数据库

1. 启用 Accelerate

导航到你的 Prisma Data Platform 项目，选择一个环境，然后通过提供你的数据库连接字符串并选择离你的数据库最近的区域来启用 Accelerate。

注意

如果你需要使用可信 IP 地址进行 IP 白名单或防火墙配置，启用静态 IP 可增强安全性。在平台控制台了解如何为 Accelerate 启用静态 IP 的更多信息。

2. 将 Accelerate 添加到你的应用

2.1. 更新你的数据库连接字符串

启用后，系统会提示你生成一个 API 密钥，你将在新的 Accelerate 连接字符串中使用该密钥来验证请求。

将你的直接数据库 URL 替换为新的 Accelerate 连接字符串。

.env

# New Accelerate connection string with generated API_KEY
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"

# Previous (direct) database connection string
# DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"

更新后的连接字符串将用作 Prisma schema 文件中的 datasource `url`；

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

Prisma Migrate 和 Introspection 不适用于 `prisma://` 连接字符串。为了继续使用这些功能，请向 `.env` 文件添加一个新变量 `DIRECT_DATABASE_URL`，其值为直接数据库连接字符串。

.env

DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"
DIRECT_DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"

然后在你的 Prisma schema 的 `datasource` 块中添加一个名为 `directUrl` 的字段，如下所示：

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

提供此配置时，迁移 (Migrations) 和内省 (introspections) 将使用 `directUrl` 连接字符串，而不是 `url` 中定义的连接字符串。

`directUrl` 对于进行迁移和内省很有用。但是，在你的应用中使用 Accelerate 不需要 `directUrl`。

注意

如果你使用 Prisma 和 PostgreSQL，则不需要 `directUrl`，因为 Prisma Migrate 和 Introspection 适用于 `prisma+postgres://` 连接字符串。

2.2. 安装 Accelerate Prisma Client 扩展

信息

💡 Accelerate 需要 Prisma Client 版本 `4.16.1` 或更高，以及 `@prisma/extension-accelerate` 版本 `1.0.0` 或更高

安装最新版本的 Prisma Client 和 Accelerate Prisma Client 扩展

npm install @prisma/client@latest @prisma/extension-accelerate

2.3. 为 Accelerate 生成 Prisma Client

如果你使用 Prisma 版本 `5.2.0` 或更高，Prisma Client 将根据数据库连接字符串中的协议自动确定如何连接到数据库。如果 `DATABASE_URL` 中的连接字符串以 `prisma://` 开头，Prisma Client 将尝试使用 Prisma Accelerate 连接到你的数据库。

在长时间运行的应用服务器（例如部署在 AWS EC2 上的服务器）中使用 Prisma Accelerate 时，你可以通过执行以下命令来生成 Prisma Client：

npx prisma generate

在无服务器 (Serverless) 或边缘 (Edge) 应用中使用 Prisma Accelerate 时，我们建议你运行以下命令来生成 Prisma Client：

npx prisma generate --no-engine

`--no-engine` 标志可防止 Query Engine 文件包含在生成的 Prisma Client 中，这确保了你的应用打包大小保持较小。

警告

如果你的 Prisma 版本低于 `5.2.0`，请使用 `--accelerate` 选项生成 Prisma Client

npx prisma generate --accelerate

如果你的 Prisma 版本低于 `5.0.0`，请使用 `--data-proxy` 选项生成 Prisma Client

npx prisma generate --data-proxy

2.4. 使用 Accelerate 扩展来扩展你的 Prisma Client 实例

添加以下内容以使用 Accelerate 扩展来扩展你的现有 Prisma Client 实例：

import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

如果你将部署到边缘运行时（如 Cloudflare Workers、Vercel Edge Functions、Deno Deploy 或 Supabase Edge Functions），请改用我们的边缘客户端 (edge client)。

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

const prisma = new PrismaClient().$extends(withAccelerate())

如果 VS Code 无法识别 `$extends` 方法，请参考此部分了解如何解决此问题。

将 Accelerate 扩展与其他扩展或中间件一起使用

由于扩展是依次应用的，请确保你以正确的顺序应用它们。扩展不能共享行为，最后应用的扩展具有优先权。

如果你在应用中使用 Prisma Optimize，请确保在 Accelerate 扩展之前应用它。例如：

const prisma = new PrismaClient().$extends(withOptimize()).$extends(withAccelerate())

如果你在应用中使用 Prisma 中间件 (Middleware)，请确保在任何 Prisma Client 扩展（如 Accelerate）之前添加它们。例如：

const prisma = new PrismaClient().$use(middleware).$extends(withAccelerate())

2.5. 在你的数据库查询中使用 Accelerate

`withAccelerate` 扩展主要做两件事：

• 让你在每个适用的模型方法中访问 `cacheStrategy` 字段，该字段允许你为每个查询定义缓存策略。
• 通过连接池将所有查询路由出去。

不使用缓存策略，仅使用连接池

如果你只想利用 Accelerate 的连接池功能而不应用缓存策略，则可以像不使用 Accelerate 时一样运行查询。

通过启用 Accelerate 并提供 Accelerate 连接字符串，你的查询现在默认使用连接池。

定义缓存策略

使用新的 `cacheStrategy` 属性更新查询，该属性允许你为此特定查询定义缓存策略：

const user = await prisma.user.findMany({
  where: {
    email: {
      contains: 'alice@prisma.io',
    },
  },
  cacheStrategy: { swr: 60, ttl: 60 },
})

在上面的示例中，`swr: 60` 和 `ttl: 60` 表示 Accelerate 将服务缓存数据 60 秒，然后在后台抓取新数据时再服务 60 秒。

现在你应该看到缓存查询的性能有所提升。

信息

有关哪种策略最适合你的应用的信息，请参阅选择缓存策略。

信息

从 Prisma 版本 `5.2.0` 开始，你可以在 Prisma Studio 中使用 Accelerate 连接字符串。

使缓存失效并保持缓存查询结果最新

如果你的应用需要实时或准实时数据，缓存失效可确保用户看到最新数据，即使使用了较长的 `ttl` (Time-To-Live) 或 `swr` (Stale-While-Revalidate) 缓存策略。通过使缓存失效，你可以绕过延长的缓存周期，以便在需要时随时显示实时数据。

例如，如果仪表板显示客户信息，并且客户的联系方式发生变化，缓存失效可让你立即刷新该数据，确保支持人员始终看到最新信息，而无需等待缓存过期。

要使缓存的查询结果失效，可以添加标签，然后使用 `$accelerate.invalidate` API。

注意

按需缓存失效功能适用于我们的付费计划。更多详情，请参阅我们的价格。

要使下面的查询失效：

await prisma.user.findMany({
  where: {
    email: {
      contains: "alice@prisma.io",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"],
  },
});

你需要在 `$accelerate.invalidate` API 中提供缓存标签：

try {
  await prisma.$accelerate.invalidate({
    tags: ["emails_with_alice"],
  });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    // The .code property can be accessed in a type-safe manner
    if (e.code === "P6003") {
      console.log(
        "You've reached the cache invalidation rate limit. Please try again shortly."
      );
    }
  }
  throw e;
}