Data Proxy
The Data Proxy provides database connection management and pooling for Prisma applications. By using the Data Proxy, your application can seamlessly scale up while maintaining predictable database performance, by limiting the number of total connections used.
The benefits of using the Data Proxy include:
avoid exhausting the number of database connections or needlessly scaling up your database
avoid serverless cold starts by reusing existing database connections
reduced bundle size for frictionless serverless deployments
About the Data Proxy
Serverless functions are ephemeral and short-lived, so their database connections are numerous and brief.
Because of this, using traditional databases in serverless functions often leads to exhausting the limit of concurrent database connections and increased latencies on each request to establish a database connection.
Using the Data Proxy in a Prisma application
We assume you already have an account and a project on the Prisma Data Platform. If you don't, sign up using your GitHub account before continuing.
Step 1. Generate a Data Proxy connection string
Navigate to the Data Proxy tab of your Prisma Data Platform project, select the desired proxy location, and click Enable.
The Data Proxy is currently available in the AWS Frankfurt (eu-central-1) and N. Virginia (us-east-1) regions. If you'd like support for other providers or regions, we'd love to hear from you.
Copy the connection string and store it securely, similarly to how you would treat a database credential. You may generate more connection strings in this section if you wish and of course, revoke them if you don't need them anymore.
Connection strings always have the following format:
prisma://{DEPLOYMENT_LOCATION}.prisma-data.com/?api_key={DATA_PROXY_API_KEY}
Note: When you use the Data Proxy, your connection string must begin with prisma://
, as described above. Do not use the direct connection string to your PostgreSQL, MySQL, or other database.
Step 2. Install up-to-date Prisma dependencies
To use the Data Proxy, use version 3.15.2
or later of the prisma
and @prisma/client
npm packages.
$npm install prisma@latest --save-dev$npm install @prisma/client@latest --save
Step 3: Make sure that the datasource URL is read from environment
For security reasons, we strongly recommend that you always use environment variables to provide your database connection strings, instead of hard-coding them into your schema.prisma
file:
datasource db {provider = "postgresql"url = env("DATABASE_URL")}
You can use the Data Proxy with Node.js (deployed in any environment where you can also deploy a normal project using Prisma Client), or with Edge runtimes like Cloudflare Workers and Vercel Edge Functions (Middleware).
Node.js
To use the Data Proxy with Node.js, set and define the environment variable with your database connection string as usual. See Environment Variables.
For guidance on how to configure environment variables in your deployment, please refer to your provider's documentation. For example:
Edge runtimes
Edge runtimes, such as Cloudflare Workers and Vercel Edge Functions, cannot access files in the file system. This prevents Prisma Client from automatically loading .env
files. Instead, you must use environment variables to pass the connection string to the Data Proxy. Depending on your provider, you might need to set the DATABASE_URL
differently.
Cloudflare Workers
In Cloudflare Workers, you can define environment variables with either wrangler
or the dashboard. For more information, see Environment Variables in the Cloudflare documentation.
Vercel Edge Functions
In Vercel Edge Functions, you can define environment variables as you would for Vercel Serverless Functions, for example in any Next.js
project. For more information, see Environment Variables in the Vercel documentation.
Step 4: Generate the client
To generate Prisma Client with the Data Proxy, call prisma generate
with the option --data-proxy
:
$npx prisma generate --data-proxy
Alternatively, you can set the environment variable PRISMA_GENERATE_DATAPROXY=true
to generate a Prisma Client with Data Proxy when a normal prisma generate
command is executed.
When deploying to Vercel Serverless Functions you need to define PRISMA_GENERATE_DATAPROXY=true
as an environment variable in your Vercel project settings to generate the correct Prisma Client for the Data Proxy.
When you use --data-proxy
or PRISMA_GENERATE_DATAPROXY=true
, you get a very lightweight Prisma Client runtime. This is because the Data Proxy does not need local engine files, so the generation process does not include the query engine.
Step 5: Import and instantiate Prisma Client in your code
Node.js
To use the Data Proxy with Node.js, use @prisma/client
as described in Generating the client.
Edge runtimes
To use the Data Proxy with Cloudflare Workers or Vercel Edge Functions, you need to import @prisma/client/edge
instead of the usual @prisma/client
, as follows:
import { PrismaClient } from '@prisma/client/edge'const prisma = new PrismaClient()// use `prisma` in your application to read and write data in your DB
You can use @prisma/client/edge
only with the Data Proxy. Make sure to use the --data-proxy
flag or PRISMA_GENERATE_DATAPROXY=true
environment variable when you generate the client.
Step 6: Start your app
You are now ready to try the Data Proxy. Go ahead and start your app!
Important Considerations about the Data Proxy
Limitations
The Data Proxy does not support the preview features Interactive Transactions or Metrics yet. To use the Data Proxy, you must first remove interactiveTransactions
and metrics
from the previewFeatures
section of your schema.prisma
file. When you run prisma generate --data-proxy
, you will receive an error if you have either of these preview features enabled.
Providing the connection string to Prisma Migrate
Currently, the Data Proxy can only be used to query your database with Prisma Client.
Migrations can be only be run on a direct (non-proxied) database connection. Assuming that your schema uses env("DATABASE_URL")
, you'll need to override the DATABASE_URL
environment variable before running prisma migrate
. You can declare another environment variable, for example MIGRATE_DATABASE_URL
, and use that to override the connection:
// package.json{...,"scripts": {"generate-client": "prisma generate --data-proxy","migrate": "DATABASE_URL=\"$MIGRATE_DATABASE_URL\" prisma migrate deploy",...}}
Deploying to Vercel Serverless Functions
You only need minimal changes to an existing project using Prisma Client with Vercel Serverless Functions to start using the Data Proxy.
Our Vercel Deployment sample repository has a special branch showing how to deploy a Prisma application to Vercel Serverless Functions using the Data Proxy. Use this link to create a Vercel project based on this branch. It makes sure you set the correct environment variables for getting a Prisma Client for Data Proxy and running migrations when Data Proxy is configured.
If you want to adapt your project manually:
- Add an environment variable
PRISMA_GENERATE_DATAPROXY
to your Vercel project settings and set its value totrue
. - If you want to deploy migrations via Vercel, follow our instructions on how to "Providing the connection string to Prisma Migrate"
Deploying to Cloudflare Workers
The Data Proxy allows you to deploy Prisma projects to Cloudflare Workers. To learn more, check out the Cloudflare Workers deployment guide.
Connecting to a database hosted with a provider different than AWS
It's possible to connect to a database hosted on any provider, but it needs to be accessible from the public internet. For best results and response times, you should configure the proxy in a region that is the same or as close as possible to the database.
We are looking to expand the number of providers and regions in the future. If a region or provider is not yet supported, you can submit a request. This will help us prioritize providers and regions to add next.
Connection limits
We recommend using a database that supports at least 20 concurrent connections. Setting a concurrency limit on AWS Lambda should not be required, but you should be aware that, if necessary, requests will be queued until they can be processed.
Reaching the Data Proxy concurrency limits
Depending on your project plan, the Prisma Data Proxy provides a different limit of concurrent proxy instances.
The performance of a single proxy instance depends on a large number of variables:
- the type of queries
- latencies and deployment locations
- the performance of your database
- ...
If you are seeing 429
HTTP errors in your logs, this probably means that you are hitting the concurrency limits.
Contact Support if you are hitting the concurrency limits and have trouble scaling your Prisma application.
Managing the number of database connections
Each Data Proxy instance has its own connection pool. The size of each of these individual connection pools can be adjusted via the connection_limit
parameter in the database connection string of the environment.
postgresql://user:password@host:5432/mydb?connection_limit=60
Error codes
Because Data Proxy connections operate differently from a local database connection, error codes will be different from regular ones. In general, all Data Proxy-related errors will start with P5xxx
.
P5000
This request could not be understood by the server
P5001
This request must be retried
P5002
The datasource provided is invalid:
- Could not parse the URL of the datasource
- Datasource URL must use
prisma://
protocol when--data-proxy
is used - No valid API key found
P5003
Requested resource does not exist
P5004
The feature is not yet implemented:
beforeExit
event is not yet supported
P5005
Schema needs to be uploaded
P5006
Unknown server error
P5007
Unauthorized, check your connection string
P5008
Usage exceeded, retry again later
P5009
Request timed out
P5010
Cannot fetch data from service