跳到主要内容

API 参考

Accelerate API 参考文档基于以下 Schema

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

所有示例均基于 User 模型。

cacheStrategy​

借助 Prisma Client 的 Accelerate 扩展，你可以使用 cacheStrategy 参数进行模型查询，并使用 ttl 和 swr 参数来定义 Accelerate 的缓存策略。Accelerate 扩展要求你安装 Prisma Client 版本 4.10.0。

选项​

cacheStrategy 参数接受一个带有以下键的选项

选项示例类型必需描述
swr60整数否过期后重新验证时间（秒）。
ttl60整数否存活时间（秒）。
标签["user"]字符串数组否tag 用作控制应用程序中特定查询失效的变量。它是一个可选的字符串数组，用于使缓存失效，每个标签只能包含字母数字字符和下划线，最大长度为 64 个字符。

示例​

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

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

支持的 Prisma Client 操作​

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

信息

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

withAccelerateInfo​

任何支持 cacheStrategy 的查询都可以附加 withAccelerateInfo() 来封装响应数据并包含有关 Accelerate 响应的额外信息。

要检索响应状态，请使用

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

console.dir(info)
信息

请注意响应对象的 info 属性。请求信息存储在此处。

返回类型​

info 对象类型为 AccelerateInfo，并遵循以下接口

interface AccelerateInfo {
  cacheStatus: 'ttl' | 'swr' | 'miss' | 'none'
  lastModified: Date
  region: string
  requestId: string
  signature: string
}
属性类型描述
缓存状态"ttl" | "swr" | "miss" | "none"响应的缓存状态。
  • ttl 表示在 ttl 持续时间内发生缓存命中，且未执行数据库查询
  • swr 表示在 swr 持续时间内发生缓存命中，且数据正在由 Accelerate 在后台刷新
  • miss 表示 ttl 和 swr 都已过期，并且请求执行了数据库查询
  • none 表示未指定缓存策略，并且请求执行了数据库查询
上次修改日期响应上次刷新的日期。
区域字符串接收请求的数据中心区域。
请求 ID字符串请求的唯一标识符。有助于故障排除。
签名字符串Prisma 操作的唯一签名。

$accelerate.invalidate​

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

注意

要按需使缓存查询结果失效，需要付费计划。每个计划每天允许的基于缓存标签的失效次数有具体限制，但调用 $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(
        "The cache invalidation rate limit has been reached. Please try again later."
      );
    }
  }
  throw e;
}
注意

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

$accelerate.invalidateAll​

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

示例​

要使以下查询失效

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

只需调用 $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?​

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

警告

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

提供自定义 Fetch 实现​

从 Accelerate 2.0.0 版开始，在通过 Accelerate 扩展 Prisma Client 时，你可以提供 fetch 函数的自定义实现。这使你能够更灵活地控制应用程序中 HTTP 请求的处理方式。

要传递自定义 fetch 实现，可以使用以下模式

const myFetch = (input: URL, init?: RequestInit): Promise<Response> => {
  // Your custom fetch logic here
  return fetch(input, init);
};

const prisma = new PrismaClient().$extends(withAccelerate({ fetch: myFetch }));

错误​

与 Prisma Accelerate 相关的错误以 P6xxx 开头。

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

© . All rights reserved.