# Read replicas (Prisma ORM v6) (/docs/orm/v6/prisma-client/setup-and-configuration/read-replicas)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Learn how to set up and use read replicas with Prisma Client

Location: ORM > v6 > Prisma Client > Setup and Configuration > Read replicas

Read replicas enable you to distribute workloads across database replicas for high-traffic workloads. The [read replicas extension](https://github.com/prisma/extension-read-replicas), `@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](https://github.com/prisma/orm/releases/tag/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](https://github.com/prisma/extension-read-replicas/issues/new).

## Setup the read replicas extension [#setup-the-read-replicas-extension]

Install the extension:

  

#### bun

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

#### pnpm

```bash
pnpm add @prisma/extension-read-replicas@latest
```

#### yarn

```bash
yarn add @prisma/extension-read-replicas@latest
```

#### npm

```bash
npm install @prisma/extension-read-replicas@latest
```

> [!NOTE]
> 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:

```ts
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: {
    /** */
  },
});
```

> [!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
>     ```
>
> 
>   #### pnpm

>     ```bash
>     pnpm add @prisma/extension-read-replicas@0.4.1
>     ```
>
> 
>   #### yarn

>     ```bash
>     yarn add @prisma/extension-read-replicas@0.4.1
>     ```
>
> 
>   #### npm

>     ```bash
>     npm install @prisma/extension-read-replicas@0.4.1
>     ```
>
> 
> 
> After installing, configure your replica like this:
> 
> ```ts
> 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](https://github.com/prisma/extension-read-replicas/issues/new).

## Configure multiple database replicas [#configure-multiple-database-replicas]

The `replicas` property accepts an array of `PrismaClient` instances for all your database replicas:

```ts
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 [#executing-read-operations-against-your-primary-database]

You can use the `$primary()` method to explicitly execute a read operation against your primary database:

```ts
const posts = await prisma.$primary().post.findMany();
```

## Executing operations against a database replica [#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:

```ts
const result = await prisma.$replica().user.findFirst(...)
```

## Related pages

- [`Configuring error formatting`](https://www.prisma.io/docs/orm/v6/prisma-client/setup-and-configuration/error-formatting): This page explains how to configure the formatting of errors when using Prisma Client.
- [`Custom model and field names`](https://www.prisma.io/docs/orm/v6/prisma-client/setup-and-configuration/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 connections`](https://www.prisma.io/docs/orm/v6/prisma-client/setup-and-configuration/databases-connections): Databases connections
- [`Database polyfills`](https://www.prisma.io/docs/orm/v6/prisma-client/setup-and-configuration/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.
- [`Generating Prisma Client`](https://www.prisma.io/docs/orm/v6/prisma-client/setup-and-configuration/generating-prisma-client): This page explains how to generate Prisma Client. It also provides additional context on the generated client, typical workflows and Node.js configuration.