Read replicas (Prisma ORM v6)

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.

Setup the read replicas extension

Install the extension:

bun add @prisma/extension-read-replicas@latest

Prisma 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:

bun add @prisma/extension-read-replicas@0.4.1

After 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 in the prisma/extension-read-replicas repository.

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(...)

Read replicas

Setup the read replicas extension

Configure multiple database replicas

Executing read operations against your primary database

Executing operations against a database replica

On this page