Use Neon read replicas with Prisma
Learn how to scale Prisma applications with Neon read replicas
A Neon read replica is an independent read-only compute instance that performs read operations on the same data as your read-write compute, which means adding a read replica to a Neon project requires no additional storage.
A key benefit of read replicas is that you can distribute read requests to one or more read replica compute instances, enabling you to easily scale your applications and achieve higher throughput for both read-write and read-only workloads.
For more information about Neon's read replica feature, see Read replicas.
In this guide, we'll show you how you can leverage Neon read replicas to efficiently scale Prisma applications using Prisma Client's read replica extension: @prisma/extension-read-replicas.
- An application that uses Prisma with a Neon database.
- A Neon Pro plan account. Read replicas are a Neon Pro plan feature.
Create a read replica
You can create one or more read replicas for any branch in your Neon project. Creating a read replica involves adding a read-only compute endpoint to the Neon branch. You can add a read-only compute endpoint by following these steps:
In the Neon Console, select Branches.
Select the branch where your database resides.
Click Add compute.
On the Create Compute Endpoint dialog, select Read-only as the Compute type.
Specify the Compute size options. You can configure a Fixed Size compute with a specific amount of vCPU and RAM (the default) or enable Autoscaling and configure a minimum and maximum compute size. You can also configure the Auto-suspend delay period, which is the amount of idle time after which your read-only compute is transitioned to an idle state. The default setting is 300 seconds (5 minutes). You can set this value up to 604800 seconds (7 days).
The compute size configuration determines the processing power of your database. More vCPU and memory means more processing power but also higher compute costs. For information about compute costs, see Billing metrics.
When you finish making selections, click Create.
Your read-only compute is provisioned and appears in the Computes section of the Branches page.
Retrieve the connection string for your read replica
Connecting to a read replica is the same as connecting to any branch in a Neon project, except you connect via a read-only compute endpoint instead of a read-write compute endpoint. The following steps describe how to retrieve the connection string (the URL) for a read replica from the Neon Console.
On the Neon Dashboard, under Connection Details, select the branch, the database, and the role you want to connect with.
Under Compute, select your Read-only compute endpoint.
Select the connection string and copy it. This is the information you need to connect to the read replica from your Prisma Client. The connection string appears similar to the following:
If you expect a high number of connections, select Pooled connection to add the
-poolerflag to the connection string, but remember to append
?pgbouncer=trueto the connection string when using a pooled connection. Prisma requires this flag when using Prisma Client with PgBouncer. See Connect from serverless functions for more information.
Update your env file
.env file, set a
DATABASE_REPLICA_URL environment variable to the connection string of your read replica. Your
.env file should look something like this, with your regular
DATABASE_URL and the newly added
Notice that the
endpoint_id for the read replica compute differs. The read replica is a different compute instance and therefore has a different
Configure Prisma Client to use a read replica
@prisma/extension-read-replicas adds support to Prisma Client for read replicas. The following steps show you how to install the extension and configure it to use a Neon read replica.
Install the extension in your Prisma project:
Extend your Prisma Client instance by importing the extension and adding the
DATABASE_REPLICA_URLenvironment variable as shown:
You can also pass an array of read replica connection strings if you want to use multiple read replicas. Neon supports adding multiple read replicas to a database branch.
When your application runs, read operations are sent to the read replica. If you specify multiple read replicas, a read replica is selected randomly.
All write and
$transactionqueries are sent to the primary compute endpoint defined by
DATABASE_URL, which is your read/write compute endpoint.
If you want to read from the primary compute endpoint and bypass read replicas, you can use the
$primary()method in your extended Prisma Client instance:
This Prisma Client query will be routed to your primary database.
This example demonstrates how to use the @prisma/extension-read-replicas extension in Prisma Client. It uses a simple TypeScript script to read and write data in a Postgres database.