ContextQMD
Back to Prisma

API Reference

apps/docs/content/docs.v6/accelerate/api-reference.mdx

latest11.5 KB
Original Source

The Accelerate API reference documentation is based on the following schema:

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

All example are based on the User model.

cacheStrategy

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

Options

The cacheStrategy parameter takes an option with the following keys:

OptionExampleTypeRequiredDescription
swr60IntNoThe stale-while-revalidate time in seconds.
ttl60IntNoThe time-to-live time in seconds.
tags["user"]String[]NoThe tag serves as a variable to control the invalidation of specific queries within your application. It is an optional array of strings to invalidate the cache, with each tag containing only alphanumeric characters and underscores, and a maximum length of 64 characters.

|

Examples

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":

ts
await prisma.user.findMany({
  where: {
    email: {
      contains: "[email protected]",
    },
  },
  cacheStrategy: {
    // [!code highlight]
    swr: 60, // [!code highlight]
    ttl: 60, // [!code highlight]
    tags: ["emails_with_alice"], // [!code highlight]
  }, // [!code highlight]
});

Supported Prisma Client operations

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

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

withAccelerateInfo

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

To retrieve the status of the response, use:

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

console.dir(info);

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

Return type

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

ts
interface AccelerateInfo {
  cacheStatus: "ttl" | "swr" | "miss" | "none";
  lastModified: Date;
  region: string;
  requestId: string;
  signature: string;
}
PropertyTypeDescription
cacheStatus"ttl" | "swr" | "miss" | "none" The cache status of the response.
<ul><li>`ttl` indicates a cache hit within the `ttl` duration and no database query was executed</li><li>`swr` indicates a cache hit within the `swr` duration and the data is being refreshed by Accelerate in the background </li><li>`miss` indicates that both `ttl` and `swr` have expired and the database query was executed by the request </li><li> `none` indicates that no cache strategy was specified and the database query was executed by the request</li></ul> | | `lastModified` | `Date` | The date the response was last refreshed. | | `region` | `String` | The data center region that received the request. | | `requestId` | `String` | Unique identifier of the request. Useful for troubleshooting. | | `signature` | `String` | The unique signature of the Prisma operation. |

$accelerate.invalidate

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

:::note

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:

ts
await prisma.user.findMany({
  where: {
    email: {
      contains: "[email protected]",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"], // [!code highlight]
  },
});

You need to provide the cache tag in the $accelerate.invalidate API:

ts
try {
  await prisma.$accelerate.invalidate({
    // [!code highlight]
    tags: ["emails_with_alice"], // [!code highlight]
  }); // [!code highlight]
} 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;
}

:::note You can invalidate up to 5 tags per call. :::

$accelerate.invalidateAll

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

Example

To invalidate the query below:

ts
await prisma.user.findMany({
  where: {
    email: {
      contains: "[email protected]",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"], // [!code highlight]
  },
});

Just call the $accelerate.invalidateAll API:

ts
try {
  await prisma.$accelerate.invalidateAll(); // [!code highlight]
} 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;
}

Why use $accelerate.invalidateAll?

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

:::warning

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

:::

Providing a Custom Fetch Implementation

Starting from Accelerate version 2.0.0, you can provide a custom implementation of the fetch function when extending the Prisma Client with Accelerate. This allows you greater flexibility and control over how HTTP requests are handled within your application.

To pass a custom fetch implementation, you can use the following pattern:

ts
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 }));

Errors

Prisma Accelerate-related errors start with P6xxx.

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