Getting started with Prisma Accelerate
Prerequisites
To get started with Accelerate, you will need the following:
- A
- A project that uses Prisma Client
4.16.1
or higher. If your project is using interactive transactions, you need to use5.1.1
or higher. (We always recommend using the latest version of Prisma.) - A hosted PostgreSQL, MySQL/MariaDB, PlanetScale, CockroachDB, or MongoDB database
1. Enable Accelerate
Navigate to your Prisma Data Platform project, choose an environment, and enable Accelerate by providing your database connection string and selecting the region nearest your database.
If you require IP allowlisting or firewall configurations with trusted IP addresses, enable Static IP for enhanced security. Learn more on how to enable static IP for Accelerate in the Platform Console.
2. Add Accelerate to your application
2.1. Update your database connection string
Once enabled, you'll be prompted to generate an API key that you'll use in your new Accelerate connection string to authenticate requests.
Replace your direct database url with your new Accelerate connection string.
# 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"
Your updated connection string will be used as the datasource url
in your Prisma schema file;
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
Prisma Migrate and Introspection do not work with a prisma://
connection string. In order to continue using these features add a new variable to the .env
file named DIRECT_DATABASE_URL
whose value is the direct database connection string:
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"
DIRECT_DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"
Then in your Prisma schema's datasource
block add a field named directUrl
with the following:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
directUrl = env("DIRECT_DATABASE_URL")
}
Migrations and introspections will use the directUrl
connection string rather than the one defined in url
when this configuration is provided.
directUrl
is useful for you to carry out migrations and introspections. However, you don't needdirectUrl
to use Accelerate in your application.
2.2. Install the Accelerate Prisma Client extension
💡 Accelerate requires Prisma Client version 4.16.1
or higher and @prisma/extension-accelerate
version 1.0.0
or higher
Install the latest version of Prisma Client and Accelerate Prisma Client extension
npm install @prisma/client@latest @prisma/extension-accelerate
2.3. Generate Prisma Client for Accelerate
If you're using Prisma version 5.2.0
or greater, Prisma Client will automatically determine how it should connect to the database depending on the protocol in the database connection string. If the connection string in the DATABASE_URL
starts with prisma://
, Prisma Client will try to connect to your database using Prisma Accelerate.
When using Prisma Accelerate in long-running application servers, such as a server deployed on AWS EC2, you can generate the Prisma Client by executing the following command:
npx prisma generate
When using Prisma Accelerate in a Serverless or an Edge application, we recommend you to run the following command to generate Prisma Client:
npx prisma generate --no-engine
The --no-engine
flag prevents a Query Engine file from being included in the generated Prisma Client, this ensures the bundle size of your application remains small.
If your Prisma version is below 5.2.0
, generate Prisma Client with the --accelerate
option:
npx prisma generate --accelerate
If your Prisma version is below 5.0.0
, generate Prisma Client with the --data-proxy
option:
npx prisma generate --data-proxy
2.4. Extend your Prisma Client instance with the Accelerate extension
Add the following to extend your existing Prisma Client instance with the Accelerate extension:
import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'
const prisma = new PrismaClient().$extends(withAccelerate())
If you are going to deploy to an edge runtime (like Cloudflare Workers, Vercel Edge Functions, Deno Deploy, or Supabase Edge Functions), use our edge client instead:
import { PrismaClient } from '@prisma/client/edge'
import { withAccelerate } from '@prisma/extension-accelerate'
const prisma = new PrismaClient().$extends(withAccelerate())
If VS Code does not recognize the $extends
method, refer to this section on how to resolve the issue.
Using the Accelerate extension with other extensions or middleware
Since extensions are applied one after another, make sure you apply them in the correct order. Extensions cannot share behavior and the last extension applied takes precedence.
If you are using Prisma Optimize in your application, make sure you apply it before the Accelerate extension. For example:
const prisma = new PrismaClient().$extends(withOptimize()).$extends(withAccelerate())
If you are using Prisma Middleware in your application, make sure they are added before any Prisma Client extensions (like Accelerate). For example:
const prisma = new PrismaClient().$use(middleware).$extends(withAccelerate())
2.5. Use Accelerate in your database queries
The withAccelerate
extension primarily does two things:
- Gives you access to the
cacheStrategy
field within each applicable model method that allows you to define a cache strategy per-query. - Routes all of your queries through a connection pooler.
No cache strategy to only use connection pool
If you simply want to take advantage of Accelerate's connection pooling feature without applying a cache strategy, you may run your query the same way you would have without Accelerate.
By enabling Accelerate and supplying the Accelerate connection string, your queries now use the connection pooler by default.
Define a cache strategy
Update a query with the new cacheStrategy
property which allows you to define a cache strategy for that specific query:
const user = await prisma.user.findMany({
where: {
email: {
contains: 'alice@prisma.io',
},
},
cacheStrategy: { swr: 60, ttl: 60 },
})
In the example above, swr: 60
and ttl: 60
means Accelerate will serve cached data for 60 seconds and then another 60 seconds while Accelerate fetches fresh data in the background.
You should now see improved performance for your cached queries.
For information about which strategy best serves your application, see Select a cache strategy.
As of Prisma version 5.2.0
you can use Prisma Studio with the Accelerate connection string.
Invalidating a cached query result
To invalidate a cached query result, you can add tags and then use the $accelerate.invalidate
API.
On-demand cache invalidation is available with our paid plans. For more details, please see our pricing.
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(
"You've reached the cache invalidation rate limit. Please try again shortly."
);
}
}
throw e;
}