事务和批量查询

数据库事务是指一系列读/写操作，这些操作被保证作为一个整体要么全部成功，要么全部失败。本节介绍了 Prisma Client API 支持事务的方式。

事务概览

信息

在 Prisma ORM 版本 4.4.0 之前，您无法在事务上设置隔离级别。数据库配置中的隔离级别始终适用。

开发者通过将操作包装在事务中来利用数据库提供的安全保证。这些保证通常使用 ACID 首字母缩略词进行概括

• 原子性（Atomic）：确保事务中的操作要么全部成功，要么全部失败。事务要么成功提交，要么中止并回滚。
• 一致性（Consistent）：确保事务前后数据库的状态是有效的（即维持数据中的任何现有不变性）。
• 隔离性（Isolated）：确保并发运行的事务效果与串行运行相同。
• 持久性（Durability）：确保事务成功后，任何写入都被持久存储。

尽管这些属性中的每一个都存在许多模糊和细微之处（例如，一致性实际上可以被视为一种应用程序层面的责任而非数据库属性，或者隔离性通常是在更强和更弱的隔离级别方面得到保证的），但总的来说，它们为开发者在考虑数据库事务时提供了一个良好的高层指导。

"事务是一个抽象层，它允许应用程序假装某些并发问题以及某些硬件和软件故障不存在。一大类错误被简化为一个简单的事务中止，应用程序只需要重试即可。" Designing Data-Intensive Applications, Martin Kleppmann

Prisma Client 支持六种不同的方式来处理三种不同场景下的事务

场景	可用技术
依赖性写入	嵌套写入
独立写入	$transaction([]) API 批量操作
读、修改、写	幂等操作 乐观并发控制 交互式事务

您选择哪种技术取决于您的具体用例。

注意：对于本指南的目的，对数据库进行写入包括创建、更新和删除数据。

关于 Prisma Client 中的事务

Prisma Client 提供以下事务使用选项

• 嵌套写入：使用 Prisma Client API 在同一事务内处理一个或多个相关记录上的多个操作。
• 批量/批处理事务：使用 updateMany、deleteMany 和 createMany 批量处理一个或多个操作。
• Prisma Client 中的 $transaction API
  • 顺序操作：传递一个 Prisma Client 查询数组，这些查询将在事务内部按顺序执行，使用 $transaction<R>(queries: PrismaPromise<R>[]): Promise<R[]>。
  • 交互式事务：传递一个函数，该函数可以包含用户代码，包括 Prisma Client 查询、非 Prisma 代码和其他控制流，这些将在事务中执行，使用 $transaction<R>(fn: (prisma: PrismaClient) => R, options?: object): R

嵌套写入

嵌套写入允许您通过单个 Prisma Client API 调用执行多个操作，这些操作涉及多个关联记录。例如，同时创建一个用户和一个帖子，或者同时更新一个订单和一个发票。Prisma Client 确保所有操作作为一个整体成功或失败。

以下示例演示了使用 create 的嵌套写入

// Create a new user with two posts in a
// single transaction
const newUser: User = await prisma.user.create({
  data: {
    email: 'alice@prisma.io',
    posts: {
      create: [
        { title: 'Join the Prisma Discord at https://pris.ly/discord' },
        { title: 'Follow @prisma on Twitter' },
      ],
    },
  },
})

以下示例演示了使用 update 的嵌套写入

// Change the author of a post in a single transaction
const updatedPost: Post = await prisma.post.update({
  where: { id: 42 },
  data: {
    author: {
      connect: { email: 'alice@prisma.io' },
    },
  },
})

批量/批处理操作

以下批量操作作为事务运行

• createMany()
• createManyAndReturn()
• updateMany()
• updateManyAndReturn()
• deleteMany()

有关更多示例，请参阅关于批量操作的部分。

$transaction API

$transaction API 可以通过两种方式使用

• 顺序操作：传递一个 Prisma Client 查询数组，这些查询将在事务内部按顺序执行。

  $transaction<R>(queries: PrismaPromise<R>[]): Promise<R[]>

• 交互式事务：传递一个函数，该函数可以包含用户代码，包括 Prisma Client 查询、非 Prisma 代码和其他控制流，这些将在事务中执行。

  $transaction<R>(fn: (prisma: PrismaClient) => R): R

顺序 Prisma Client 操作

以下查询返回所有与提供过滤器匹配的帖子以及所有帖子的计数

const [posts, totalPosts] = await prisma.$transaction([
  prisma.post.findMany({ where: { title: { contains: 'prisma' } } }),
  prisma.post.count(),
])

您也可以在 $transaction 内部使用原始查询

关系型数据库

import { selectUserTitles, updateUserName } from '@prisma/client/sql'

const [userList, updateUser] = await prisma.$transaction([
  prisma.$queryRawTyped(selectUserTitles()),
  prisma.$queryRawTyped(updateUserName(2)),
])

MongoDB

const [findRawData, aggregateRawData, commandRawData] =
  await prisma.$transaction([
    prisma.user.findRaw({
      filter: { age: { $gt: 25 } },
    }),
    prisma.user.aggregateRaw({
      pipeline: [
        { $match: { status: 'registered' } },
        { $group: { _id: '$country', total: { $sum: 1 } } },
      ],
    }),
    prisma.$runCommandRaw({
      aggregate: 'User',
      pipeline: [
        { $match: { name: 'Bob' } },
        { $project: { email: true, _id: false } },
      ],
      explain: false,
    }),
  ])

不是在执行每个操作时立即等待结果，而是先将操作本身存储在一个变量中，稍后通过一个名为 $transaction 的方法提交给数据库。Prisma Client 将确保这三个 create 操作要么全部成功，要么全部失败。

注意：操作按照它们在事务中放置的顺序执行。在事务中使用查询不影响查询本身中操作的顺序。

有关更多示例，请参阅关于事务 API 的部分。

从版本 4.4.0 起，顺序操作事务 API 有第二个参数。您可以在此参数中使用以下可选配置选项

• isolationLevel：设置事务隔离级别。默认情况下，此值设置为您数据库中当前配置的值。

例如

await prisma.$transaction(
  [
    prisma.resource.deleteMany({ where: { name: 'name' } }),
    prisma.resource.createMany({ data }),
  ],
  {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable, // optional, default defined by database configuration
  }
)

交互式事务

概览

有时您需要对事务中执行的查询有更多控制权。交互式事务旨在为您提供一种逃生出口。

信息

交互式事务已从版本 4.7.0 起普遍可用。

如果您在版本 2.29.0 到 4.6.1（含）之间以预览功能使用交互式事务，则需要将 interactiveTransactions 预览功能添加到 Prisma schema 的 generator 块中。

要使用交互式事务，您可以将一个异步函数传递给$transaction。

传递到此异步函数中的第一个参数是 Prisma Client 的一个实例。在下面，我们将此实例称为 tx。在此 tx 实例上调用的任何 Prisma Client 调用都会被封装到事务中。

警告

谨慎使用交互式事务。长时间保持事务开放会损害数据库性能，甚至可能导致死锁。尽量避免在事务函数内部执行网络请求和慢查询。我们建议您尽快进入和退出！

示例

我们来看一个示例

想象一下，您正在构建一个在线银行系统。要执行的操作之一是将钱从一个人发送到另一个人。

作为有经验的开发者，我们要确保在转账过程中，

• 金额不会凭空消失
• 金额不会翻倍

这是一个非常适合交互式事务的用例，因为我们需要在写入之间执行逻辑来检查余额。

在下面的示例中，Alice 和 Bob 的账户里各有 100 美元。如果他们尝试发送超出其拥有金额的钱，转账将被拒绝。

预计 Alice 能够进行 1 次 100 美元的转账，而另一次转账将被拒绝。这将导致 Alice 拥有 0 美元，Bob 拥有 200 美元。

import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

function transfer(from: string, to: string, amount: number) {
  return prisma.$transaction(async (tx) => {
    // 1. Decrement amount from the sender.
    const sender = await tx.account.update({
      data: {
        balance: {
          decrement: amount,
        },
      },
      where: {
        email: from,
      },
    })

    // 2. Verify that the sender's balance didn't go below zero.
    if (sender.balance < 0) {
      throw new Error(`${from} doesn't have enough to send ${amount}`)
    }

    // 3. Increment the recipient's balance by amount
    const recipient = await tx.account.update({
      data: {
        balance: {
          increment: amount,
        },
      },
      where: {
        email: to,
      },
    })

    return recipient
  })
}

async function main() {
  // This transfer is successful
  await transfer('alice@prisma.io', 'bob@prisma.io', 100)
  // This transfer fails because Alice doesn't have enough funds in her account
  await transfer('alice@prisma.io', 'bob@prisma.io', 100)
}

main()

在上面的示例中，两个 update 查询都在数据库事务内运行。当应用程序到达函数末尾时，事务将提交到数据库。

如果您的应用程序在此过程中遇到错误，异步函数将抛出异常并自动回滚事务。

要捕获异常，您可以将 $transaction 包装在 try-catch 块中

try {
  await prisma.$transaction(async (tx) => {
    // Code running in a transaction...
  })
} catch (err) {
  // Handle the rollback...
}

事务选项

事务 API 有第二个参数。对于交互式事务，您可以在此参数中使用以下可选配置选项

• maxWait：Prisma Client 等待从数据库获取事务的最长时间。默认值为 2 秒。
• timeout：交互式事务在被取消和回滚之前的最长时间。默认值为 5 秒。
• isolationLevel：设置事务隔离级别。默认情况下，此值设置为您数据库中当前配置的值。

例如

await prisma.$transaction(
  async (tx) => {
    // Code running in a transaction...
  },
  {
    maxWait: 5000, // default: 2000
    timeout: 10000, // default: 5000
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable, // optional, default defined by database configuration
  }
)

您也可以在构造函数级别全局设置这些选项

const prisma = new PrismaClient({
  transactionOptions: {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
    maxWait: 5000, // default: 2000
    timeout: 10000, // default: 5000
  },
})

事务隔离级别

信息

此功能在 MongoDB 上不可用，因为 MongoDB 不支持隔离级别。

您可以为事务设置事务隔离级别。

信息

此功能在以下 Prisma ORM 版本中可用：交互式事务从版本 4.2.0 开始，顺序操作从版本 4.4.0 开始。

在 4.2.0 之前的版本（对于交互式事务）或 4.4.0 之前的版本（对于顺序操作）中，您无法在 Prisma ORM 级别配置事务隔离级别。Prisma ORM 不显式设置隔离级别，因此使用在您的数据库中配置的隔离级别。

设置隔离级别

要设置事务隔离级别，请在 API 的第二个参数中使用 isolationLevel 选项。

对于顺序操作

await prisma.$transaction(
  [
    // Prisma Client operations running in a transaction...
  ],
  {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable, // optional, default defined by database configuration
  }
)

对于交互式事务

await prisma.$transaction(
  async (prisma) => {
    // Code running in a transaction...
  },
  {
    isolationLevel: Prisma.TransactionIsolationLevel.Serializable, // optional, default defined by database configuration
    maxWait: 5000, // default: 2000
    timeout: 10000, // default: 5000
  }
)

支持的隔离级别

如果底层数据库支持，Prisma Client 支持以下隔离级别

• ReadUncommitted
• ReadCommitted
• RepeatableRead
• Snapshot
• Serializable

每个数据库连接器可用的隔离级别如下

数据库	ReadUncommitted	ReadCommitted	RepeatableRead	Snapshot	Serializable
PostgreSQL	✔️	✔️	✔️	否	✔️
MySQL	✔️	✔️	✔️	否	✔️
SQL Server	✔️	✔️	✔️	✔️	✔️
CockroachDB	否	否	否	否	✔️
SQLite	否	否	否	否	✔️

默认情况下，Prisma Client 将隔离级别设置为您数据库中当前配置的值。

每个数据库默认配置的隔离级别如下

数据库	默认
PostgreSQL	ReadCommitted
MySQL	RepeatableRead
SQL Server	ReadCommitted
CockroachDB	Serializable
SQLite	Serializable

关于隔离级别的数据库特定信息

请参阅以下资源

• PostgreSQL 中的事务隔离级别
• Microsoft SQL Server 中的事务隔离级别
• MySQL 中的事务隔离级别

CockroachDB 和 SQLite 只支持 Serializable 隔离级别。

事务时序问题

信息

• 本节中的解决方案不适用于 MongoDB，因为 MongoDB 不支持隔离级别。
• 本节讨论的时序问题不适用于 CockroachDB 和 SQLite，因为这些数据库只支持最高的 Serializable 隔离级别。

当两个或多个事务在某些隔离级别下并发运行时，时序问题可能导致写入冲突或死锁，例如违反唯一约束。例如，考虑以下事件序列，其中事务 A 和事务 B 都尝试执行 deleteMany 和 createMany 操作

1. 事务 B：createMany 操作创建一组新行。
2. 事务 B：应用程序提交事务 B。
3. 事务 A：createMany 操作。
4. 事务 A：应用程序提交事务 A。新行与事务 B 在步骤 2 添加的行发生冲突。

这种冲突可能发生在 ReadCommited 隔离级别，这是 PostgreSQL 和 Microsoft SQL Server 中的默认隔离级别。为避免此问题，您可以设置更高的隔离级别（RepeatableRead 或 Serializable）。您可以在事务上设置隔离级别。这将覆盖该事务的数据库隔离级别。

为避免事务上的写入冲突和死锁

1. 在您的事务上，使用 isolationLevel 参数设置为 Prisma.TransactionIsolationLevel.Serializable。

   这确保您的应用程序提交多个并发或并行事务，就像它们是串行运行一样。当事务由于写入冲突或死锁而失败时，Prisma Client 返回一个 P2034 错误。

2. 在您的应用程序代码中，围绕事务添加重试以处理任何 P2034 错误，如本例所示

   import { Prisma, PrismaClient } from '@prisma/client'
   
   const prisma = new PrismaClient()
   async function main() {
     const MAX_RETRIES = 5
     let retries = 0
   
     let result
     while (retries < MAX_RETRIES) {
       try {
         result = await prisma.$transaction(
           [
             prisma.user.deleteMany({
               where: {
                 /** args */
               },
             }),
             prisma.post.createMany({
               data: {
                 /** args */
               },
             }),
           ],
           {
             isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
           }
         )
         break
       } catch (error) {
         if (error.code === 'P2034') {
           retries++
           continue
         }
         throw error
       }
     }
   }

在 Promise.all() 中使用 $transaction

如果您将 $transaction 包装在 Promise.all() 的调用中，事务内的查询将按顺序执行（即一个接一个）

await prisma.$transaction(async (prisma) => {
  await Promise.all([
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
    prisma.user.findMany(),
  ])
})

这可能与直觉相反，因为 Promise.all() 通常会并行执行传入的调用。

此行为的原因是

• 一个事务意味着其中的所有查询都必须在同一连接上运行。
• 一个数据库连接一次只能执行一个查询。
• 由于一个查询在工作时会阻塞连接，因此将事务放入 Promise.all 实际上意味着查询应按顺序执行。

依赖性写入

写入被认为是彼此依赖的，如果

• 操作依赖于前一个操作的结果（例如，数据库生成 ID）

最常见的场景是创建一条记录并使用生成的 ID 来创建或更新关联记录。示例包括

• 创建一个用户和两个相关的博客文章（一对多关系）—— 在创建博客文章之前必须知道作者 ID
• 创建一个团队并分配成员（多对多关系）—— 在分配成员之前必须知道团队 ID

依赖性写入必须一起成功，以维持数据一致性并防止意外行为，例如没有作者的博客文章或没有成员的团队。

嵌套写入

Prisma Client 解决依赖性写入的方法是嵌套写入功能，该功能由 create 和 update 支持。以下嵌套写入创建一个用户和两篇博客文章

const nestedWrite = await prisma.user.create({
  data: {
    email: 'imani@prisma.io',
    posts: {
      create: [
        { title: 'My first day at Prisma' },
        { title: 'How to configure a unique constraint in PostgreSQL' },
      ],
    },
  },
})

如果任何操作失败，Prisma Client 将回滚整个事务。目前顶层批量操作如 client.user.deleteMany 和 client.user.updateMany 不支持嵌套写入。

何时使用嵌套写入

如果出现以下情况，请考虑使用嵌套写入

• ✔ 您想同时创建两个或多个通过 ID 相关的记录（例如，创建一个博客文章和一个用户）
• ✔ 您想同时更新和创建通过 ID 相关的记录（例如，更改用户的姓名并创建一个新的博客文章）

提示

如果您预先计算 ID，则可以在嵌套写入或使用 $transaction([]) API 之间进行选择。

场景：注册流程

考虑 Slack 的注册流程，它

1. 创建一个团队
2. 将一个用户添加到该团队，该用户自动成为该团队的管理员

此场景可用以下 schema 表示——请注意，用户可以属于多个团队，团队可以拥有多个用户（多对多关系）

model Team {
  id      Int    @id @default(autoincrement())
  name    String
  members User[] // Many team members
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  teams Team[] // Many teams
}

最直接的方法是创建一个团队，然后创建并将用户附加到该团队

// Create a team
const team = await prisma.team.create({
  data: {
    name: 'Aurora Adventures',
  },
})

// Create a user and assign them to the team
const user = await prisma.user.create({
  data: {
    email: 'alice@prisma.io',
    team: {
      connect: {
        id: team.id,
      },
    },
  },
})

但是，此代码存在一个问题——考虑以下场景

1. 创建团队成功——"Aurora Adventures" 现在已被占用
2. 创建和连接用户失败——团队 "Aurora Adventures" 存在，但没有用户
3. 再次执行注册流程并尝试重新创建 "Aurora Adventures" 失败——团队已经存在

创建团队和添加用户应该是一个原子操作，它作为一个整体成功或失败。

要在低级数据库客户端中实现原子写入，您必须将您的插入操作包装在 BEGIN、COMMIT 和 ROLLBACK 语句中。Prisma Client 使用嵌套写入解决此问题。以下查询在一个事务中创建一个团队、创建一个用户并连接这些记录

const team = await prisma.team.create({
  data: {
    name: 'Aurora Adventures',
    members: {
      create: {
        email: 'alice@prisma.io',
      },
    },
  },
})

此外，如果在任何时候发生错误，Prisma Client 将回滚整个事务。

嵌套写入常见问题

为什么我不能使用 $transaction([]) API 解决同样的问题？

$transaction([]) API 不允许您在不同的操作之间传递 ID。在以下示例中，createUserOperation.id 尚不可用

const createUserOperation = prisma.user.create({
  data: {
    email: 'ebony@prisma.io',
  },
})

const createTeamOperation = prisma.team.create({
  data: {
    name: 'Aurora Adventures',
    members: {
      connect: {
        id: createUserOperation.id, // Not possible, ID not yet available
      },
    },
  },
})

await prisma.$transaction([createUserOperation, createTeamOperation])

嵌套写入支持嵌套更新，但更新不是依赖性写入——我应该使用 $transaction([]) API 吗？

可以说，因为您知道团队的 ID，所以可以在 $transaction([]) 中独立地更新团队及其团队成员。以下示例在 $transaction([]) 中执行了这两个操作

const updateTeam = prisma.team.update({
  where: {
    id: 1,
  },
  data: {
    name: 'Aurora Adventures Ltd',
  },
})

const updateUsers = prisma.user.updateMany({
  where: {
    teams: {
      some: {
        id: 1,
      },
    },
    name: {
      equals: null,
    },
  },
  data: {
    name: 'Unknown User',
  },
})

await prisma.$transaction([updateUsers, updateTeam])

但是，您可以通过嵌套写入实现相同的结果

const updateTeam = await prisma.team.update({
  where: {
    id: 1,
  },
  data: {
    name: 'Aurora Adventures Ltd', // Update team name
    members: {
      updateMany: {
        // Update team members that do not have a name
        data: {
          name: 'Unknown User',
        },
        where: {
          name: {
            equals: null,
          },
        },
      },
    },
  },
})

我可以执行多个嵌套写入吗——例如，创建两个新团队并分配用户？

是的，但这结合了不同的场景和技术

• 创建团队并分配用户是依赖性写入——使用嵌套写入
• 同时创建所有团队和用户是独立写入，因为团队/用户组合 #1 和团队/用户组合 #2 是不相关的写入——使用 $transaction([]) API

// Nested write
const createOne = prisma.team.create({
  data: {
    name: 'Aurora Adventures',
    members: {
      create: {
        email: 'alice@prisma.io',
      },
    },
  },
})

// Nested write
const createTwo = prisma.team.create({
  data: {
    name: 'Cool Crew',
    members: {
      create: {
        email: 'elsa@prisma.io',
      },
    },
  },
})

// $transaction([]) API
await prisma.$transaction([createTwo, createOne])

独立写入

写入被认为是彼此独立的，如果它们不依赖于前一个操作的结果。以下几组独立写入可以以任何顺序发生

• 将订单列表的状态字段更新为“已发货”
• 将电子邮件列表标记为“已读”

注意：如果存在约束，独立写入可能必须按特定顺序发生——例如，如果帖子有强制性的 authorId 字段，您必须在删除博客作者之前删除博客文章。但是，它们仍然被认为是独立写入，因为没有任何操作依赖于前一个操作的结果，例如数据库返回生成的 ID。

根据您的要求，Prisma Client 有四种处理应该一起成功或失败的独立写入的选项。

批量操作

批量写入允许您在单个事务中写入同类型的多个记录——如果任何操作失败，Prisma Client 将回滚整个事务。Prisma Client 目前支持

• createMany()
• createManyAndReturn()
• updateMany()
• updateManyAndReturn()
• deleteMany()

何时使用批量操作

如果出现以下情况，请考虑使用批量操作作为解决方案

• ✔ 您想更新一批同类型的记录，例如一批电子邮件

场景：将电子邮件标记为已读

您正在构建一个类似 gmail.com 的服务，您的客户想要一个“标记为已读”功能，该功能允许用户将所有电子邮件标记为已读。对电子邮件状态的每次更新都是一次独立写入，因为这些电子邮件彼此不依赖——例如，您阿姨发来的“生日快乐！🍰”电子邮件与 IKEA 发来的促销电子邮件无关。

在以下 schema 中，一个 User 可以有许多收到的电子邮件（一对多关系）

model User {
  id    Int       @id @default(autoincrement())
  email           String @unique
  receivedEmails  Email[] // Many emails
}

model Email {
  id      Int     @id @default(autoincrement())
  user    User    @relation(fields: [userId], references: [id])
  userId  Int
  subject String
  body    String
  unread  Boolean
}

基于此 schema，您可以使用 updateMany 将所有未读电子邮件标记为已读

await prisma.email.updateMany({
  where: {
    user: {
      id: 10,
    },
    unread: true,
  },
  data: {
    unread: false,
  },
})

我可以在批量操作中使用嵌套写入吗？

不能——updateMany 和 deleteMany 目前都不支持嵌套写入。例如，您不能删除多个团队及其所有成员（级联删除）

await prisma.team.deleteMany({
  where: {
    id: {
      in: [2, 99, 2, 11],
    },
  },
  data: {
    members: {}, // Cannot access members here
  },
})

我可以在 $transaction([]) API 中使用批量操作吗？

是的——例如，您可以在 $transaction([]) 中包含多个 deleteMany 操作。

$transaction([]) API

$transaction([]) API 是一个通用的解决方案，用于处理独立写入，它允许您将多个操作作为单个原子操作运行——如果任何操作失败，Prisma Client 将回滚整个事务。

值得注意的是，操作会按照它们在事务中的顺序执行。

await prisma.$transaction([iRunFirst, iRunSecond, iRunThird])

注意：在事务中使用查询不影响查询本身中操作的顺序。

随着 Prisma Client 的发展，$transaction([]) API 的用例将越来越多地被更专业的批量操作（例如 createMany）和嵌套写入所取代。

何时使用 $transaction([]) API

如果出现以下情况，请考虑使用 $transaction([]) API

• ✔ 您想更新包含不同类型记录的批次，例如电子邮件和用户。这些记录无需以任何方式关联。
• ✔ 您想批量处理原始 SQL 查询（$executeRaw）——例如，对于 Prisma Client 尚未支持的功能。

场景：隐私法规

GDPR 和其他隐私法规赋予用户要求组织删除其所有个人数据的权利。在以下示例 schema 中，一个 User 可以有许多帖子和私信

model User {
  id              Int              @id @default(autoincrement())
  posts           Post[]
  privateMessages PrivateMessage[]
}

model Post {
  id      Int    @id @default(autoincrement())
  user    User   @relation(fields: [userId], references: [id])
  userId  Int
  title   String
  content String
}

model PrivateMessage {
  id      Int    @id @default(autoincrement())
  user    User   @relation(fields: [userId], references: [id])
  userId  Int
  message String
}

如果用户行使被遗忘权，我们必须删除三条记录：用户记录、私信和帖子。至关重要的是，所有删除操作必须全部一起成功，否则就全部失败，这使得它成为一个事务的用例。然而，在这种情况下使用单个批量操作（如 deleteMany）是不可能的，因为我们需要跨三个模型进行删除。相反，我们可以使用 $transaction([]) API 一起运行三个操作——两个 deleteMany 和一个 delete

const id = 9 // User to be deleted

const deletePosts = prisma.post.deleteMany({
  where: {
    userId: id,
  },
})

const deleteMessages = prisma.privateMessage.deleteMany({
  where: {
    userId: id,
  },
})

const deleteUser = prisma.user.delete({
  where: {
    id: id,
  },
})

await prisma.$transaction([deletePosts, deleteMessages, deleteUser]) // Operations succeed or fail together

场景：预计算 ID 与 $transaction([]) API

$transaction([]) API 不支持依赖性写入——如果操作 A 依赖于操作 B 生成的 ID，请使用嵌套写入。但是，如果您预先计算了 ID（例如，通过生成 GUID），您的写入就变成了独立的。考虑嵌套写入示例中的注册流程

await prisma.team.create({
  data: {
    name: 'Aurora Adventures',
    members: {
      create: {
        email: 'alice@prisma.io',
      },
    },
  },
})

不自动生成 ID，而是将 Team 和 User 的 id 字段更改为 String 类型（如果您不提供值，将自动生成一个 UUID）。本示例使用 UUID

model Team {
  id      Int    @id @default(autoincrement())
  id      String @id @default(uuid())
  name    String
  members User[]
}

model User {
  id    Int    @id @default(autoincrement())
  id    String @id @default(uuid())
  email String @unique
  teams Team[]
}

重构注册流程示例，使其使用 $transaction([]) API 而非嵌套写入

import { v4 } from 'uuid'

const teamID = v4()
const userID = v4()

await prisma.$transaction([
  prisma.user.create({
    data: {
      id: userID,
      email: 'alice@prisma.io',
      team: {
        id: teamID,
      },
    },
  }),
  prisma.team.create({
    data: {
      id: teamID,
      name: 'Aurora Adventures',
    },
  }),
])

理论上，如果您喜欢那种语法，仍然可以在预计算的 ID 中使用嵌套写入

import { v4 } from 'uuid'

const teamID = v4()
const userID = v4()

await prisma.team.create({
  data: {
    id: teamID,
    name: 'Aurora Adventures',
    members: {
      create: {
        id: userID,
        email: 'alice@prisma.io',
        team: {
          id: teamID,
        },
      },
    },
  },
})

如果您已经在使用自动生成的 ID 和嵌套写入，就没有充分的理由切换到手动生成的 ID 和 $transaction([]) API。

读、修改、写

在某些情况下，您可能需要执行自定义逻辑作为原子操作的一部分——这也被称为读-修改-写模式。以下是读-修改-写模式的一个示例

• 从数据库读取一个值
• 运行一些逻辑来操作该值（例如，联系外部 API）
• 将该值写回数据库

所有操作都应该一起成功或失败，而不会对数据库进行不必要的更改，但您不一定需要使用实际的数据库事务。本指南的这一部分描述了使用 Prisma Client 和读-修改-写模式的两种方法

• 设计幂等 API
• 乐观并发控制

幂等 API

幂等性是指使用相同的参数多次运行相同的逻辑，并获得相同结果的能力：无论您运行该逻辑一次还是一千次，其对数据库的影响都是相同的。例如

• 非幂等：使用电子邮件地址 "letoya@prisma.io" 在数据库中 Upsert（更新或插入）一个用户。 User 表不强制执行唯一的电子邮件地址。如果您运行该逻辑一次（创建一个用户）或十次（创建十个用户），对数据库的影响是不同的。
• 幂等：使用电子邮件地址 "letoya@prisma.io" 在数据库中 Upsert（更新或插入）一个用户。 User 表强制执行唯一的电子邮件地址。如果您运行该逻辑一次（创建一个用户）或十次（现有用户使用相同的输入进行更新），对数据库的影响是相同的。

在可能的情况下，幂等性是您能够并且应该积极设计到应用程序中的特性。

何时设计幂等 API

• ✔ 您需要能够重试相同的逻辑，而不会在数据库中产生不必要的副作用

场景：升级 Slack 团队

您正在为 Slack 创建一个升级流程，允许团队解锁付费功能。团队可以选择不同的套餐，并按用户每月付费。您使用 Stripe 作为支付网关，并扩展您的 Team 模型以存储 stripeCustomerId。订阅在 Stripe 中管理。

model Team {
  id               Int     @id @default(autoincrement())
  name             String
  User             User[]
  stripeCustomerId String?
}

升级流程如下所示

1. 计算用户数量
2. 在 Stripe 中创建包含用户数量的订阅
3. 将团队与 Stripe 客户 ID 关联以解锁付费功能

const teamId = 9
const planId = 'plan_id'

// Count team members
const numTeammates = await prisma.user.count({
  where: {
    teams: {
      some: {
        id: teamId,
      },
    },
  },
})

// Create a customer in Stripe for plan-9454549
const customer = await stripe.customers.create({
  externalId: teamId,
  plan: planId,
  quantity: numTeammates,
})

// Update the team with the customer id to indicate that they are a customer
// and support querying this customer in Stripe from our application code.
await prisma.team.update({
  data: {
    customerId: customer.id,
  },
  where: {
    id: teamId,
  },
})

这个例子有一个问题：您只能运行该逻辑一次。考虑以下场景

1. Stripe 创建了一个新的客户和订阅，并返回一个客户 ID

2. 更新团队失败 - 该团队在 Slack 数据库中未被标记为客户

3. 客户被 Stripe 收费，但 Slack 中未解锁付费功能，因为该团队缺少有效的 customerId

4. 再次运行相同的代码可能会

   • 导致错误，因为团队（由 externalId 定义）已存在 - Stripe 不会返回客户 ID
   • 如果 externalId 不受唯一约束，Stripe 会创建另一个订阅（非幂等）

您无法在发生错误时重新运行此代码，也无法在不被收费两次的情况下更改到其他套餐。

以下重构（高亮部分）引入了一种机制，用于检查订阅是否已存在，并创建新订阅或更新现有订阅（如果输入相同，现有订阅将保持不变）

// Calculate the number of users times the cost per user
const numTeammates = await prisma.user.count({
  where: {
    teams: {
      some: {
        id: teamId,
      },
    },
  },
})

// Find customer in Stripe
let customer = await stripe.customers.get({ externalId: teamID })

if (customer) {
  // If team already exists, update
  customer = await stripe.customers.update({
    externalId: teamId,
    plan: 'plan_id',
    quantity: numTeammates,
  })
} else {
  customer = await stripe.customers.create({
    // If team does not exist, create customer
    externalId: teamId,
    plan: 'plan_id',
    quantity: numTeammates,
  })
}

// Update the team with the customer id to indicate that they are a customer
// and support querying this customer in Stripe from our application code.
await prisma.team.update({
  data: {
    customerId: customer.id,
  },
  where: {
    id: teamId,
  },
})

您现在可以使用相同的输入多次重试相同的逻辑，而不会产生不利影响。为了进一步改进此示例，您可以引入一种机制，如果在一定次数的尝试后更新仍未成功，则取消或暂时停用订阅。

乐观并发控制

乐观并发控制（OCC）是一种处理单个实体上的并发操作的模型，它不依赖于🔒锁定。相反，我们乐观地假设记录在读取和写入之间保持不变，并使用并发令牌（时间戳或版本字段）来检测记录的更改。

如果发生❌冲突（自您读取后其他人已更改记录），您将取消事务。根据您的场景，您可以然后

• 重试事务（预订另一个电影票）
• 抛出错误（提醒用户他们即将覆盖其他人所做的更改）

本节介绍如何构建您自己的乐观并发控制。另请参阅：GitHub 上的应用级乐观并发控制计划

信息

• 如果您使用 4.4.0 或更早的版本，您无法在 update 操作上使用乐观并发控制，因为您无法按非唯一字段进行过滤。您需要与乐观并发控制一起使用的 version 字段是一个非唯一字段。

• 从 5.0.0 版本开始，您可以在 update 操作中按非唯一字段进行过滤，以便使用乐观并发控制。该功能在 4.5.0 到 4.16.2 版本中也可以通过 Preview 标志 extendedWhereUnique 使用。

何时使用乐观并发控制

• ✔ 您预计会有大量并发请求（多人预订电影票）
• ✔ 您预计这些并发请求之间的冲突很少发生

在高并发请求的应用程序中避免锁定可以使应用程序对负载更具弹性，并且整体上更具可伸缩性。虽然锁定本身并非不好，但在高并发环境中锁定可能导致意外后果——即使您只锁定单个行并且只锁定很短时间。有关更多信息，请参阅

• 为何在 SQL Server 中 ROWLOCK Hints 会使查询变慢并加剧阻塞

场景：预订电影票

您正在为电影院创建一个预订系统。每部电影都有固定数量的座位。以下 Schema 建模了电影和座位

model Seat {
  id        Int   @id @default(autoincrement())
  userId    Int?
  claimedBy User? @relation(fields: [userId], references: [id])
  movieId   Int
  movie     Movie @relation(fields: [movieId], references: [id])
}

model Movie {
  id    Int    @id     @default(autoincrement())
  name  String @unique
  seats Seat[]
}

以下示例代码查找第一个可用座位并将其分配给用户

const movieName = 'Hidden Figures'

// Find first available seat
const availableSeat = await prisma.seat.findFirst({
  where: {
    movie: {
      name: movieName,
    },
    claimedBy: null,
  },
})

// Throw an error if no seats are available
if (!availableSeat) {
  throw new Error(`Oh no! ${movieName} is all booked.`)
}

// Claim the seat
await prisma.seat.update({
  data: {
    claimedBy: userId,
  },
  where: {
    id: availableSeat.id,
  },
})

然而，此代码存在“重复预订问题”——两个人可能会预订同一个座位

1. 座位 3A 返回给 Sorcha（findFirst）
2. 座位 3A 返回给 Ellen（findFirst）
3. 座位 3A 被 Sorcha 预订（update）
4. 座位 3A 被 Ellen 预订（update - 覆盖了 Sorcha 的预订）

尽管 Sorcha 成功预订了座位，系统最终却存储了 Ellen 的预订。要使用乐观并发控制解决此问题，请向座位添加一个 version 字段

model Seat {
  id        Int   @id @default(autoincrement())
  userId    Int?
  claimedBy User? @relation(fields: [userId], references: [id])
  movieId   Int
  movie     Movie @relation(fields: [movieId], references: [id])
  version   Int
}

接下来，调整代码以在更新前检查 version 字段

const userEmail = 'alice@prisma.io'
const movieName = 'Hidden Figures'

// Find the first available seat
// availableSeat.version might be 0
const availableSeat = await client.seat.findFirst({
  where: {
    Movie: {
      name: movieName,
    },
    claimedBy: null,
  },
})

if (!availableSeat) {
  throw new Error(`Oh no! ${movieName} is all booked.`)
}

// Only mark the seat as claimed if the availableSeat.version
// matches the version we're updating. Additionally, increment the
// version when we perform this update so all other clients trying
// to book this same seat will have an outdated version.
const seats = await client.seat.updateMany({
  data: {
    claimedBy: userEmail,
    version: {
      increment: 1,
    },
  },
  where: {
    id: availableSeat.id,
    version: availableSeat.version, // This version field is the key; only claim seat if in-memory version matches database version, indicating that the field has not been updated
  },
})

if (seats.count === 0) {
  throw new Error(`That seat is already booked! Please try again.`)
}

现在不可能两个人预订同一个座位了

1. 座位 3A 返回给 Sorcha（version 为 0）
2. 座位 3A 返回给 Ellen（version 为 0）
3. 座位 3A 被 Sorcha 预订（version 增加到 1，预订成功）
4. 座位 3A 被 Ellen 预订（内存中的 version (0) 与数据库中的 version (1) 不匹配 - 预订不成功）

交互式事务

如果您有一个现有的应用程序，将其重构为使用乐观并发控制可能是一项艰巨的任务。交互式事务为这种情况提供了一个有用的解决方案。

要创建交互式事务，请将一个异步函数传递给 $transaction。

传递到此异步函数中的第一个参数是 Prisma Client 的一个实例。在下面，我们将此实例称为 tx。在此 tx 实例上调用的任何 Prisma Client 调用都会被封装到事务中。

在下面的示例中，Alice 和 Bob 的账户里各有 100 美元。如果他们尝试发送超出其拥有金额的钱，转账将被拒绝。

预期结果是 Alice 完成一次 100 美元的转账，另一次转账将被拒绝。这将导致 Alice 余额为 0 美元，Bob 余额为 200 美元。

import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

async function transfer(from: string, to: string, amount: number) {
  return await prisma.$transaction(async (tx) => {
    // 1. Decrement amount from the sender.
    const sender = await tx.account.update({
      data: {
        balance: {
          decrement: amount,
        },
      },
      where: {
        email: from,
      },
    })

    // 2. Verify that the sender's balance didn't go below zero.
    if (sender.balance < 0) {
      throw new Error(`${from} doesn't have enough to send ${amount}`)
    }

    // 3. Increment the recipient's balance by amount
    const recipient = tx.account.update({
      data: {
        balance: {
          increment: amount,
        },
      },
      where: {
        email: to,
      },
    })

    return recipient
  })
}

async function main() {
  // This transfer is successful
  await transfer('alice@prisma.io', 'bob@prisma.io', 100)
  // This transfer fails because Alice doesn't have enough funds in her account
  await transfer('alice@prisma.io', 'bob@prisma.io', 100)
}

main()

在上面的示例中，两个 update 查询都在数据库事务内运行。当应用程序到达函数末尾时，事务将提交到数据库。

如果应用程序在过程中遇到错误，异步函数将抛出异常并自动回滚事务。

您可以在此章节中了解有关交互式事务的更多信息。

警告

谨慎使用交互式事务。长时间保持事务开放会损害数据库性能，甚至可能导致死锁。尽量避免在事务函数内部执行网络请求和慢查询。我们建议您尽快进入和退出！

结论

Prisma Client 支持多种处理事务的方式，可以直接通过 API 处理，也可以通过支持您在应用程序中引入乐观并发控制和幂等性来处理。如果您觉得您的应用程序中有任何未被建议选项覆盖的用例，请在GitHub 上提出 Issue以开始讨论。