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:

TypeScript
JavaScript
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:

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

Edit this page on GitHub