Data Proxy

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).

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 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

import { PrismaClient } from '@prisma/client/edge'
const prisma = new PrismaClient()
// use `prisma` in your application to read and write data in your DB

Step 6: Start your app

You are now ready to try the Data Proxy. Go ahead and start your app!

Limitations

The Data Proxy does not yet support the following preview features:

• Metrics
• OpenTelemetry tracing

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:

• Add an environment variable PRISMA_GENERATE_DATAPROXY to your Vercel project settings and set its value to true.
• 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

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.