API Reference (/docs/accelerate/reference/api-reference)

For the complete Prisma documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL.

API reference documentation for Accelerate

Location: Accelerate > Reference > API Reference

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

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

All example are based on the User model.

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.

The cacheStrategy parameter takes an option with the following keys:

|

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"],  },});

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

• findUnique()
• findUniqueOrThrow()
• findFirst()
• findFirstOrThrow()
• findMany()
• count()
• aggregate()
• groupBy()

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

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:

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.

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

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.

To invalidate the query below:

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

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

[!NOTE] You can invalidate up to 5 tags per call.

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

To invalidate the query below:

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

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

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

[!WARNING] This clears the cache for the entire environment. Use it with care.

Starting from Accelerate version 2.0.0, you can provide a custom implementation of the fetch function when extending the Prisma Client with Accelerate. Use it to control how HTTP requests are handled within your application.

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

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-related errors start with P6xxx.

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