Prisma Accelerate 入门
先决条件
要开始使用 Accelerate,你需要以下内容
- A
- 一个使用 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 连接字符串中使用它来验证请求。
用你新的 Accelerate 连接字符串替换你的直接数据库 URL。
# 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
的新变量,其值为直接数据库连接字符串
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")
}
提供此配置后,迁移和内省将使用 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
或更高版本。
💡 Accelerate 扩展 @prisma/extension-accelerate
版本 2.0.0
及更高版本需要 Node.js 版本 18
或更高版本。
安装最新版本的 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
标志可防止将 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),请改用我们的边缘客户端
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 秒的缓存数据,然后在 Accelerate 在后台获取新数据时再提供 60 秒。
你现在应该会看到缓存查询的性能有所提高。
有关哪种策略最适合你的应用程序的信息,请参阅 选择缓存策略。
从 Prisma 版本 5.2.0
开始,你可以使用带有 Accelerate 连接字符串的 Prisma Studio。
使缓存失效并保持缓存的查询结果最新
如果你的应用程序需要实时或接近实时数据,缓存失效可确保用户看到最新数据,即使使用较大的 ttl
(生存时间)或 swr
(陈旧时重新验证)缓存策略。通过使缓存失效,你可以绕过延长缓存期,在需要时显示实时数据。
例如,如果仪表板显示客户信息,并且客户的联系方式发生变化,缓存失效允许你即时刷新这些数据,确保支持人员始终看到最新信息,而无需等待缓存过期。
要使缓存的查询结果失效,你可以添加标签,然后使用 $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;
}