读取副本

只读副本使你能够跨数据库副本分配工作负载，以应对高流量工作负载。读取副本扩展、@prisma/extension-read-replicas 向 Prisma 客户端添加了对只读数据库副本的支持。

¥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.

只读副本扩展支持 Prisma ORM 版本 5.2.0 及更高版本。对于 Prisma 7.0 及更高版本，此扩展程序要求传递完整的 PrismaClient 实例，而不是连接 URL。如果你遇到错误或有反馈，请创建 GitHub 问题 此处。

¥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 here.

设置只读副本扩展

¥Setup the read replicas extension

安装扩展：

¥Install the extension:

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

兼容 Prisma 7

最新版本的 @prisma/extension-read-replicas 需要 Prisma 7.0 或更高版本，并使用新的 API，该 API 要求传递完整的 PrismaClient 实例，而不是连接 URL。由于 Prisma 7 的架构变更，此更改是必要的。

¥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.

如果你使用的是 Prisma 6.x 或更早版本，请参阅以下说明。

¥If you're using Prisma 6.x or earlier, see the note below.

通过扩展 Prisma Client 实例来初始化扩展，并为只读副本提供完整的 PrismaClient 实例。默认方法是使用驱动程序适配器：

¥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: {/** */},
})

适用于 Prisma v6 用户

对于 Prisma v6 用户，请安装 Read Replicas 扩展的 0.4.1 版本：

¥For Prisma v6 users, install version 0.4.1 of the Read Replicas extension:

npm install @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: { /* ... */ },
})

所有读取操作，例如 findMany，将针对具有上述设置的数据库副本执行。所有写操作 - 例如 create、update 和 $transaction 查询将针对你的主数据库执行。

¥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.

如果你遇到错误或有反馈，请创建 GitHub 问题 此处。

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

配置多个数据库副本

¥Configure multiple database replicas

replicas 属性接受一个包含所有数据库副本的 PrismaClient 实例数组：

¥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

你可以使用 $primary() 方法对主数据库显式执行读取操作：

¥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

你可以使用 $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(...)