跳转至主要内容

Prisma Accelerate 入门

前提条件​

要开始使用 Accelerate，您需要以下内容

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

1. 启用 Accelerate​

导航到您的 Prisma 数据平台项目，选择一个环境，并通过提供您的数据库连接字符串并选择离您的数据库最近的区域来启用 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 模式文件中的数据源 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 模式的 datasource 块中添加一个名为 directUrl 的字段，其值如下

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

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

directUrl 对于您执行迁移和内省很有用。但是，您不需要 directUrl 即可在您的应用程序中使用 Accelerate。

注意

如果您将 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

在无服务器或边缘应用程序中使用 Prisma Accelerate 时，我们建议您运行以下命令来生成 Prisma Client

npx prisma generate --no-engine

--no-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），请改用我们的边缘客户端

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 中间件，请确保在任何 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: '[email protected]',
    },
  },
  cacheStrategy: { swr: 60, ttl: 60 },
})

在上面的示例中，swr: 60 和 ttl: 60 表示 Accelerate 将为缓存数据提供 60 秒，然后在 Accelerate 在后台获取新数据时再提供 60 秒。

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

信息

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

信息

从 Prisma 版本 5.2.0 开始，您可以将 Prisma Studio 与 Accelerate 连接字符串一起使用。

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

如果您的应用程序需要实时或接近实时的数据，缓存失效可确保用户看到最新的数据，即使在使用较大的 ttl（生存时间）或 swr（过时时重新验证）缓存策略时也是如此。通过使您的缓存失效，您可以绕过扩展的缓存期限，以便在需要时显示实时数据。

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

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

注意

按需缓存失效功能仅在我们的付费计划中提供。有关更多详细信息，请参阅我们的定价。

要使以下查询失效

await prisma.user.findMany({
  where: {
    email: {
      contains: "[email protected]",
    },
  },
  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;
}