The Data Proxy provides database connection management and pooling for applications that use Prisma. 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 yet support the following preview features:

To use the Data Proxy, you must first remove metrics and tracing from the previewFeatures section of your schema.prisma file.

For example:

generator client {
provider = "prisma-client-js"
previewFeatures = ["metrics", "tracing"]
previewFeatures = []
}

When you run prisma generate --data-proxy, you will receive an error if you have one or more of these preview features enabled.

Interactive transactions with Data Proxy

Interactive transactions with the Data Proxy are in general availability in Prisma ORM version 4.7.0. Prisma ORM first released interactive transactions with the Data Proxy in preview in version 4.6.0.

Interactive transactions do not work with the Data Proxy with Prisma ORM versions earlier than 4.6.0.

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
1{
2 ...,
3 "scripts": {
4 "generate-client": "prisma generate --data-proxy",
+ "migrate-deploy": "DATABASE_URL=\"$MIGRATE_DATABASE_URL\" prisma migrate deploy",
6 ...
7 }
8}

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

Idle connections to the database

The Data Proxy creates several connection pools that maintain open idle connections even when no queries run from your application. The connection pools and any remaining idle connections close after six minutes of inactivity (no queries are sent to the database).

In each of the supported locations, the Data Proxy architecture includes multiple clusters that maintain idle connections to the database. This architecture ensures high availability in case of failures in any of the clusters.

This architecture has a number of benefits.

  • High availability. The Data Proxy maintains a separate connection pool from each cluster in a location. This guarantees that at least one connection pool is always available to handle queries.
  • Load balancing. The Data Proxy distributes the load of the database queries among the number of available connection pools.
  • Scalability. The Data Proxy starts new connection pools when an application experiences peak activity and stops existing connection pools (but two always remain with at least one being active in a separate cluster) when the peak activity subsides.
Edit this page on GitHub