Read replicas
Learn how to set up and use read replicas with Prisma Client
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.
The read replicas extension supports Prisma ORM versions 5.2.0 and higher. For Prisma 7.0+, the extension requires passing full PrismaClient instances instead of connection URLs. If you run into a bug or have feedback, create a GitHub issue here.
Setup the read replicas extension
Install the extension:
npm install @prisma/extension-read-replicas@latestPrisma 7 compatibility
The latest version of @prisma/extension-read-replicas requires Prisma 7.0+ and uses a new API that requires passing full PrismaClient instances instead of connection URLs. This change is necessary due to Prisma 7's architectural changes.
If you're using Prisma 6.x or earlier, see the note below.
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: {
/** */
},
});For Prisma v6 users
For Prisma v6 users, install version 0.4.1 of the Read Replicas extension:
npm install @prisma/extension-read-replicas@0.4.1After installing, configure your replica like this:
import { PrismaClient } from "../prisma/generated/client";
import { readReplicas } from "@prisma/extension-read-replicas";
const prisma = new PrismaClient().$extends(
readReplicas({
url: process.env.DATABASE_URL_REPLICA,
}),
);
// This query runs against the read replica
await prisma.post.findMany();
// This query runs against the primary database
await prisma.post.create({
data: {
/* ... */
},
});All read operations, e.g. findMany, will be executed against the database replica with the above setup. All write operations — e.g. create, update — and $transaction queries, will be executed against your primary database.
If you run into a bug or have feedback, create a GitHub issue here.
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(...)Custom model and field names
Learn how you can decouple the naming of Prisma models from database tables to improve the ergonomics of the generated Prisma Client API.
Database polyfills
Prisma Client provides features that are not achievable with relational databases. These features are referred to as "polyfills" and explained on this page.