Read replicas
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 in the prisma/extension-read-replicas repository.
Install the extension:
bun add @prisma/extension-read-replicas@latestpnpm add @prisma/extension-read-replicas@latestyarn add @prisma/extension-read-replicas@latestnpm install @prisma/extension-read-replicas@latestInitialize 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.
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.
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
Section titled “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
Section titled “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(...)