Getting started
Prerequisites
To get started with Accelerate, you will need the following:
- A GitHub account.
- 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.) - A hosted PostgreSQL, MySQL, PlanetScale, CockroachDB, or MongoDB database.
1. Enable Accelerate in a Cloud Project
In order to enable Accelerate, you can log in to Prisma Data Platform and create a new Cloud Project. Follow the instructions in the UI to add Accelerate.
For further information on each individual step, you can find additional documentation here.
At the end of the setup process, you'll obtain a connection string that connects to Accelerate. This connection string also contains an API key that you need to use when configuring Prisma Client to use Accelerate.
2. Use Accelerate in your application
To get started using Accelerate, ensure you’re using Prisma Client 4.16.1
or higher.
2.1. Update your database connection string
After enabling Accelerate in your Cloud Project and creating a new API key, you should be given an Accelerate connection string.
To use this connection string, update the datasource
block's url
field in your Prisma schema:
datasource db {provider = "postgresql"url = env("DATABASE_URL")}
Most likely, as shown above, your database connection string in defined in a .env
file rather than hard-coded into the schema file.
Update that variable to use the new Accelerate connection string:
.env
1# __API_KEY__ is a unique API key that Accelerate generates and automatically assigns to a project.2DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"34# Previous connection string5# DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"
Prisma Migrate and Prisma Studio 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:
.env
1DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"2DIRECT_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")}
Prisma Migrate and Prisma Studio will use the directUrl
connection string rather than the one defined in url
when this configuration is provided.
2.2. Install the Accelerate Prisma Client extension
Run the following command to install the Accelerate extension for Prisma Client:
$npm install @prisma/extension-accelerate
If your Prisma version is below 4.16.1
, enable the Prisma Client extension feature:
/// prisma/schema.prismagenerator client {provider = "prisma-client-js"previewFeatures = ["clientExtensions"]}
2.3. Generate Prisma Client for Accelerate
Run the following command to generate Prisma Client for Accelerate:
$npx prisma generate --accelerate
5.0.0
, generate Prisma Client with the --data-proxy
option:$npx prisma generate --data-proxy
2.4. Extend your Prisma Client instance to add the Accelerate extension
To use Accelerate, you must extend Prisma Client with the Accelerate extension. Extend your Prisma Client instance to add 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 Netlify 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.
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.