docs: read replicas

content/200-concepts/100-components/02-prisma-client/065-read-replicas.mdx

@@ -0,0 +1,84 @@
+---
+title: 'Read replicas'
+metaTitle: 'Read replicas'
+metaDescription: 'Learn how to set up and use read replicas with Prisma Client'
+tocDepth: 3
+---
+
+<TopBlock>
+
+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 versions 5.2.0 and higher.
+
+</TopBlock>
+
+## Setup the read replicas extension
+
+Install the extension:
+
+```terminal
+npm install @prisma/extension-read-replicas
+```
+
+Initialize the extension by extending your Prisma Client instance and providing the extension a connection string that points to your read replica in the `url` option of the extension.
+
+<!-- prettier-ignore-start -->
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { readReplicas } from '@prisma/extension-read-replicas'
+
+const prisma = new PrismaClient().$extends(
+  readReplicas({
+    url: process.env.DATABASE_URL_REPLICA,
+  })
+)
+
+// Query is run against the database replica
+await prisma.post.findMany()
+
+// Query is run against the primary database
+await prisma.post.create({ 
+  data: {/** */},
+})
+```
+<!-- prettier-ignore-end -->
+
+With the above setup, all read operations, e.g. `findMany`, will be executed against the database replica. All write operations, e.g. `create`, `update`, and `$transaction`, will be executed against your primary database.
+
+
+## Configure multiple database replicas
+
+The `url` property also accepts an array of values, i.e. an array of all your database replicas you would like to configure:
+
+```ts
+const prisma = new PrismaClient().$extends(
+  readReplicas({
+    url: [
+      process.env.DATABASE_URL_REPLICA_1,
+      process.env.DATABASE_URL_REPLICA_2,
+    ],
+  })
+)
+```
+
+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:
+
+```ts
+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:
+
+```ts
+const result = await prisma.$replica().$queryRaw`SELECT ...`
+```
+
+Try it out and share your feedback with us [here](https://github.com/prisma/extension-read-replicas/issues/new).