Read replicas - Prisma

Read replicas enable you to distribute workloads across database replicas for high-traffic workloads. The read replicas extension, @prisma/extension-read-replicas, adds support for read-only database replicas to Prisma Client.

If you run into a bug or have feedback, create a GitHub issue here.

Setup the read replicas extension

Install the extension:

npm

npm install @prisma/extension-read-replicas@latest

Initialize the extension by extending your Prisma Client instance and provide the extension with full PrismaClient instances for your read replicas. The default approach is to use driver adapters:

import { readReplicas } from "@prisma/extension-read-replicas";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";

// Create main client with adapter
const mainAdapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
});

const mainClient = new PrismaClient({ adapter: mainAdapter });

// Create replica client with adapter
const replicaAdapter = new PrismaPg({
  connectionString: process.env.REPLICA_URL!,
});

const replicaClient = new PrismaClient({ adapter: replicaAdapter });

// Extend main client with read replicas
const prisma = mainClient.$extends(readReplicas({ replicas: [replicaClient] }));

// Query is run against the database replica
await prisma.post.findMany();

// Query is run against the primary database
await prisma.post.create({
  data: {
    /** */
  },
});

All read operations (e.g. findMany) are executed against the database replica. All write operations (e.g. create, update) and $transaction queries are executed against your primary database.

Configure multiple database replicas

The replicas property accepts an array of PrismaClient instances for all your database replicas:

import { readReplicas } from "@prisma/extension-read-replicas";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";

// Create main client
const mainAdapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
});
const mainClient = new PrismaClient({ adapter: mainAdapter });

// Create multiple replica clients
const replicaAdapter1 = new PrismaPg({
  connectionString: process.env.DATABASE_URL_REPLICA_1!,
});
const replicaClient1 = new PrismaClient({ adapter: replicaAdapter1 });

const replicaAdapter2 = new PrismaPg({
  connectionString: process.env.DATABASE_URL_REPLICA_2!,
});
const replicaClient2 = new PrismaClient({ adapter: replicaAdapter2 });

// Configure multiple replicas
const prisma = mainClient.$extends(
  readReplicas({
    replicas: [replicaClient1, replicaClient2],
  }),
);

If you have more than one read replica configured, a database replica will be randomly selected to execute your query.

Executing read operations against your primary database

You can use the $primary() method to explicitly execute a read operation against your primary database:

const posts = await prisma.$primary().post.findMany();

Executing operations against a database replica

You can use the $replica() method to explicitly execute your query against a replica instead of your primary database:

const result = await prisma.$replica().user.findFirst(...)