Read replicas

Source URL: https://docs.prisma.io/docs/orm/prisma-client/setup-and-configuration/read-replicas

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.

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

Setup the read replicas extension

Install the extension:

npm

pnpm

yarn

bun

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