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 in the prisma/extension-read-replicas repository.
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:
TypeScript
import { readReplicas } from"@prisma/extension-read-replicas";
import { PrismaPg } from"@prisma/adapter-pg";
import { PrismaClient } from"./generated/prisma/client";
// Create main client with adapterconst mainAdapter = new PrismaPg({
connectionString: process.env.DATABASE_URL!,
});
const mainClient = new PrismaClient({ adapter: mainAdapter });
// Create replica client with adapterconst replicaAdapter = new PrismaPg({
connectionString: process.env.REPLICA_URL!,
});
const replicaClient = new PrismaClient({ adapter: replicaAdapter });
// Extend main client with read replicasconst prisma = mainClient.$extends(readReplicas({ replicas: [replicaClient] }));
// Query is run against the database replicaawait prisma.post.findMany();
// Query is run against the primary databaseawait prisma.post.create({
data: {
/** */
},
});
[!NOTE]
For Prisma v6 users
For Prisma v6 users, install version 0.4.1 of the Read Replicas extension:
bun
```bash
bun add @prisma/extension-read-replicas@0.4.1
```
After installing, configure your replica like this:
TypeScript
importfrom"../prisma/generated/client";
importfrom"@prisma/extension-read-replicas";
const prisma = new PrismaClient().$extends(
readReplicas({
url: process.env.DATABASE_URL_REPLICA,
}),
);
// This query runs against the read replicaawait prisma.post.findMany();
// This query runs against the primary databaseawait 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.
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, 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.