API 参考

Prisma Postgres API 参考文档基于以下架构：

¥The Prisma Postgres API reference documentation is based on the following schema:

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

所有示例均基于 User 模型。

¥All example are based on the User model.

cacheStrategy

使用 适用于 Prisma Postgres 的 Prisma 客户端扩展，你可以使用 cacheStrategy 参数进行模型查询，并使用 ttl 和 swr 参数为 Prisma Postgres 查询定义缓存策略。客户端扩展需要你安装 Prisma Client 4.10.0 版本。

¥With the Prisma client extension for Prisma Postgres, you can use the cacheStrategy parameter for model queries and use the ttl and swr parameters to define a cache strategy for your Prisma Postgres queries. The client extension requires that you install Prisma Client version 4.10.0.

选项

¥Options

cacheStrategy 参数接受一个包含以下键的选项：

¥The cacheStrategy parameter takes an option with the following keys:

选项	示例	类型	必需的	描述
swr	60	Int	不	stale-while-revalidate 时间（以秒为单位）。
ttl	60	Int	不	生存时间（秒）。
tags	["user"]	String[]	不	tag 用作变量，用于控制应用中特定查询的失效。它是一个可选的字符串数组，用于 invalidate 缓存，每个标签仅包含字母数字字符和下划线，最大长度为 64 个字符。

示例

¥Examples

为查询添加缓存策略，定义 60 秒的重新验证时过期时间 (SWR) 值、60 秒的生存时间 (TTL) 值以及 "emails_with_alice" 的缓存标签：

¥Add a caching strategy to the query, defining a 60-second stale-while-revalidate (SWR) value, a 60-second time-to-live (TTL) value, and a cache tag of "emails_with_alice":

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

支持的 Prisma 客户端操作

¥Supported Prisma Client operations

以下是所有支持 cacheStrategy 的读取查询操作的列表：

¥The following is a list of all read query operations that support cacheStrategy:

• findUnique()

• findUniqueOrThrow()

• findFirst()

• findFirstOrThrow()

• findMany()

• count()

• aggregate()

• groupBy()

info

任何写入操作（例如 create()）都不支持 cacheStrategy 参数。

¥The cacheStrategy parameter is not supported on any write operations, such as create().

withAccelerateInfo

任何支持 cacheStrategy 的查询都可以附加 withAccelerateInfo() 来封装响应数据，并包含有关缓存响应的其他信息。

¥Any query that supports the cacheStrategy can append withAccelerateInfo() to wrap the response data and include additional information about the cached response.

要检索响应状态，请使用：

¥To retrieve the status of the response, use:

const { data, info } = await prisma.user
  .count({
    cacheStrategy: { ttl: 60, swr: 600 },
    where: { myField: 'value' },
  })
  .withAccelerateInfo()

console.dir(info)

info

请注意响应对象的 info 属性。这是存储请求信息的地方。

¥Notice the info property of the response object. This is where the request information is stored.

返回类型

¥Return type

info 对象属于 AccelerateInfo 类型，并遵循以下接口：

¥The info object is of type AccelerateInfo and follows the interface below:

interface AccelerateInfo {
  cacheStatus: 'ttl' | 'swr' | 'miss' | 'none'
  lastModified: Date
  region: string
  requestId: string
  signature: string
}

属性	类型	描述
cacheStatus	"ttl" | "swr" | "miss" | "none"	响应的缓存状态 ttl indicates a cache hit within the ttl duration and no database query was executed swr indicates a cache hit within the swr duration and the data is being refreshed by Prisma Postgres in the background miss indicates that both ttl and swr have expired and the database query was executed by the request none indicates that no cache strategy was specified and the database query was executed by the request
lastModified	Date	上次刷新响应的日期。
region	String	接收请求的数据中心区域。
requestId	String	请求的唯一标识符。有助于故障排除。
signature	String	Prisma 操作的唯一签名。

$accelerate.invalidate

你可以使用 $accelerate.invalidate API 使缓存失效。

¥You can invalidate the cache using the $accelerate.invalidate API.

注意

要按需使缓存的查询结果无效，需要付费计划。每个计划对每天允许的基于缓存标签的失效次数都有特定的限制，但调用 $accelerate.invalidate API 本身没有限制。请参阅我们的 更多定价详情。

¥To invalidate cached query results on-demand, a paid plan is required. Each plan has specific limits on the number of cache tag-based invalidations allowed per day, though there are no limits on calling the $accelerate.invalidate API itself. See our pricing for more details.

示例

¥Example

要使以下查询无效：

¥To invalidate the query below:

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

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

¥You need to provide the cache tag in the $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(
        "The cache invalidation rate limit has been reached. Please try again later."
      );
    }
  }
  throw e;
}

注意

每次调用最多可以使 5 个标签失效。

¥You can invalidate up to 5 tags per call.

$accelerate.invalidateAll

你可以使用 $accelerate.invalidateAll API 使整个缓存失效。

¥You can invalidate the entire cache using the $accelerate.invalidateAll API.

示例

¥Example

要使以下查询无效：

¥To invalidate the query below:

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

只需调用 $accelerate.invalidateAll API：

¥Just call the $accelerate.invalidateAll API:

try {
  await prisma.$accelerate.invalidateAll();
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    if (e.code === "P6003") {
      console.log(
        "The cache invalidation rate limit has been reached. Please try again later."
      );
    }
  }
  throw e;
}

为什么要使用 $accelerate.invalidateAll？

¥Why use $accelerate.invalidateAll?

与 invalidate("all") 等替代方案相比，此方法提供更好的编辑器支持（例如 IntelliSense）。

¥This method offers better editor support (e.g. IntelliSense) than alternatives like invalidate("all").

警告

这将清除整个环境的缓存 - 请谨慎使用。

¥This clears cache for the entire environment—use with care.

错误

¥Errors

Prisma Postgres 相关错误以 P6xxx 开头。

¥Prisma Postgres-related errors start with P6xxx.

你可以找到 Prisma Postgres 此处 的完整错误代码参考。

¥You can find the full error code reference for Prisma Postgres here.