To use the Data Proxy for a JavaScript/TypeScript application that uses Prisma, you must first create a project in Prisma Data Platform. When you create the project, you do the following:

Note

When you create your project, you do not need to also create a Data Proxy connection string. You can always create a new Data Proxy connection string at a later time as described below in Enable Data Proxy for a project.

You can then configure the connection string in your development or deployment environment and configure Prisma project to use Data Proxy.

Enable the Data Proxy for a project

When you create a project in the platform, the Data Proxy is automatically enabled for your project.

Note

The fact that the Data Proxy is enabled for a project does not yet mean that your application starts to use the proxy.

Your application starts to use the proxy only after you configure a generated Data Proxy connection string as an environment variable for your project so that Prisma Client uses the proxy connection string and not the direct connection to the database.

Prerequisites

  • Create a project to add your application in the platform. During the process, select a geographic location for the Data Proxy that is closest to the location of your database.
  • If your database is behind a firewall, enable static IP addresses for your project and add the IP addresses for the selected Data Proxy region to the allowlist of your database.
    • US East 1 (West Virginia)
      • 54.204.197.119
      • 3.222.148.224
      • 54.204.47.202
      • 3.227.136.248
    • EU Central 1 (Frankfurt, Germany)
      • 35.157.74.165
      • 18.194.25.248
      • 18.184.112.103
      • 18.157.219.25

Steps

  1. Open your project in the Prisma Data Platform. You can do so from the Projects page.

  2. Get a Data Proxy connection string for the selected environment.

    1. With the project open and an environment selected, click the Data Proxy tab.

    2. Click Create a connection string.

      Note

      You can generate as many Data Proxy connection strings as you need. You can later revoke any of the connection strings that you no longer need.
    3. Enter a name for the new Data Proxy connection string and click Create.

      Prisma Data Platform - Data Proxy - Create and name a new Data Proxy connection string
    4. Copy the prisma:// connection string.

      Important

      Save the prisma:// connection string securely. After you navigate to another page, you cannot retrieve the connection string again from the Data Proxy. You can only generate a new connection string, if necessary.
      Prisma Data Platform - Data Proxy - Copy the Data Proxy connection string

Configure Prisma project to use Data Proxy

After you create your project in the platform and enable the Data Proxy, you can generate Prisma Client for the Data Proxy and use it with the prisma:// connection string you obtained.

You can generate and use Prisma Client for the Data Proxy in the following environments:

  • In your local development environment, to test the process.
  • In your deployment platform. You must replace the direct database connection string with the Data Proxy connection string and make sure that Prisma Client is auto-generated with the --data-proxy flag as described below.

Prerequisites

Steps

  1. In your local development environment, replace the direct database connection string with the Data Proxy prisma:// connection string.

    .env
    - DATABASE_URL="postgresql://****:****@****"
    + DATABASE_URL="prisma://****:****@****"

    Note

    For security reasons, use environment variables for database connection strings and Data Proxy strings. Do not hard-code them into schema.prisma. For more information, see Using .env files.

  2. To introspect your database or perform migrations using the Prisma CLI, a direct database connection is required. If you are using Prisma version 4.1.0 or later, include the directUrl property in the datasource block of your Prisma schema.

    schema.prisma
    1generator client {
    2 provider = "prisma-client-js"
    3}
    4
    5datasource db {
    6 provider = "postgresql"
    7 url = env("DATABASE_URL")
    + directUrl = env("DIRECT_URL")
    9}

    Then, add the direct database connection string in the .env file.

    .env
    1DATABASE_URL="prisma://****:****@****"
    + DIRECT_URL="postgresql://****:****@****"

    However, in older versions, you need to overwrite the DATABASE_URL environment variable with the direct database connection string when running migrations. Refer to the Prisma CLI commands with the Data Proxy documentation for more information.

  3. Install prisma and @prisma/client.

    Make sure to use version 3.15.2 or later.

    $npm install prisma@latest --save-dev
    $npm install @prisma/client@latest --save
  4. Generate Prisma Client with the --data-proxy option.

    $npx prisma generate --data-proxy

    The generated Prisma Client is a lightweight version because it excludes the local query engine files. The Data Proxy handles the query engine logic.

  5. Instantiate Prisma Client in your application code.

    • To use the Data Proxy with Node.js, instantiate @prisma/client. Learn more.

      TypeScript
      JavaScript
      import { PrismaClient } from '@prisma/client'
      const prisma = new PrismaClient()
      // use `prisma` in your application to read and write data in your DB
    • To use the Data Proxy in Edge runtimes, such as Cloudflare Workers or Vercel Edge Functions, instantiate @prisma/client/edge.

      Note

      You can use @prisma/client/edge only with the Data Proxy. In such cases, make sure to use the --data-proxy flag or the PRISMA_GENERATE_DATAPROXY=true environment variable when you generate Prisma Client.
      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

Result

Your application now uses the Data Proxy.

The generated Prisma Client has a reduced bundle size because the entire query engine logic is now hosted with the Data Proxy.

Manage the number of database connections

You can set the maximum number of database connections per Data Proxy instance via the connection_limit argument in the database connection connection string that's provided to the PDP project via the PDP web UI.

The default value for the connection_limit in each Data Proxy instance is 5. This default value is determined using the calculation num_physical_cpus * 2 + 1. The machines Data Proxy is running on have two CPUs, so: 2 * 2 + 1 = 5.

Here is a sample connection string for the Data Proxy connection that uses the connection_limit argument:

postgresql://USER:PASSWORD@HOST:PORT/DB?connection_limit=10

In the example connection string, the connection limit of 10 is used as a sample value. To ensure that your database's connections are not exhausted, it is recommended to set an appropriate value for the connection limit. This will help manage the surge in traffic effectively and prevent any connection-related issues.

It's important to understand that this connection limit applies to each individual QE instance. For example, if the connection_limit is set to 10 and 5 Query Engine (QE) instances are created, a total of 50 connections would be established with the database (connection_limit * QE instances). It is important to ensure that the database has sufficient capacity to handle this load of 50 connections.

For more detailed information regarding the limits of the Data Proxy and its concurrency limits, we recommend referring to the Concurrency Limits documentation.

Edit this page on GitHub