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

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