Transactions and batch queries {prisma}

문제의식

Transactions and batch queries를 주의깊게 읽은 후 애그리거트가 지켜야 하는 트랜잭션 경계를 프리즈마를 사용하여 어떻게 달성할 수 있는지 알아봅시다.

Prisma Client는 트랜잭션을 하나의 API로만 제공하지 않는다. 같은 "여러 작업을 한 번에 성공하거나 실패하게 만든다"는 목적이라도, 작업의 의존성에 따라 선택지가 달라진다.

Batch operations

Batch operations는 같은 모델에 대한 다건 작업을 하나의 쿼리로 표현한다. Prisma 문서에서 트랜잭션으로 실행된다고 설명하는 대표 API는 다음과 같다.

• Bulk operations
  • createMany
  • createManyAndReturn
  • updateMany
  • updateManyAndReturn
  • deleteMany

예를 들어 여러 이메일을 읽음 처리하는 기능은 각 이메일의 업데이트가 서로 독립적이다. 이럴 때는 이메일 하나마다 update를 반복하거나 $transaction([])에 수십 개의 update를 넣기보다 updateMany가 더 단순하다.

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

Batch operations는 "같은 모델, 같은 변경 규칙, 독립적인 레코드"라는 조건이 맞을 때 가장 먼저 고려할 선택지다. 다만 여러 모델을 함께 다루거나, 각 레코드별로 다른 관계 작업이 필요하면 적합하지 않다.

Nested writes

Nested writes는 관련된 레코드들을 하나의 Prisma 쿼리 안에서 함께 쓰는 방식이다. 사용자는 한 번의 create 또는 update를 호출하지만, Prisma는 내부적으로 관련 쓰기 작업들을 하나의 트랜잭션으로 묶는다.

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

이 방식이 중요한 이유는 dependent writes 때문이다. 예를 들어 Team을 만든 뒤 그 Team.id를 사용해 User를 만들어야 한다면, 뒤 작업은 앞 작업의 결과에 의존한다. 데이터베이스가 ID를 생성하는 구조라면 $transaction([]) 배열 안의 다음 쿼리로 그 ID를 넘길 수 없다. 이런 경우에는 Nested writes가 더 자연스럽고 안전하다.

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

Nested writes는 관계 그래프를 한 번에 쓰기 좋지만, bulk operation과 결합되지는 않는다. updateMany, deleteMany 안에서 관계 필드를 타고 들어가 자식 레코드를 함께 수정하거나 삭제할 수는 없다.

$transaction([]) API

$transaction([]) API는 여러 Prisma Client 쿼리를 배열로 넘겨 순서대로 실행하고, 하나라도 실패하면 전체를 롤백한다. 주로 서로 다른 모델의 독립적인 작업들을 하나의 원자적 경계로 묶을 때 사용한다.

UseCase: 여러 테이블에 걸친 Delete Operation

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

여기서는 Post, PrivateMessage, User라는 서로 다른 모델을 함께 삭제해야 한다. 단일 deleteMany로 표현할 수 없고, 각 쿼리는 삭제 대상 사용자 ID만 알면 미리 만들 수 있다. 이런 경우 $transaction([])가 적합하다.

UseCase: pre-computed ID를 사용하고자 하는 경우

문서에서는 UUID를 사용하였으나, 내가 알기론 ObjectId도 애플리케이션 단에서 생성이 가능하다고 들었는데, 굳이 Nested Write를 사용하지 않고도 독립적인 오퍼레이션들로 분리한 다음 하나의 트랜잭션으로 실행하는 것도 적극적으로 도입해볼 수 있겠다.

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를 미리 알고 있느냐이다. 데이터베이스가 ID를 생성하면 뒤 쿼리가 앞 쿼리의 결과를 기다려야 하므로 Nested writes가 맞다. 반대로 UUID나 ObjectId처럼 애플리케이션이 ID를 먼저 계산할 수 있다면, 각 쿼리는 서로의 실행 결과를 기다리지 않아도 되므로 $transaction([])로 분리할 수 있다.

다만 Prisma 문서도 이미 자동 생성 ID와 Nested writes를 잘 쓰고 있다면, 수동 ID 생성과 $transaction([])로 굳이 바꿀 강한 이유는 없다고 설명한다. $transaction([])는 "더 강력한 API"라기보다 "작업들을 독립적인 PrismaPromise로 미리 구성할 수 있을 때 쓰는 API"에 가깝다.

Interactive transactions

Interactive transactions는 콜백 형태의 $transaction(async (tx) => { ... })이다. 배열형 $transaction([])와 달리, 트랜잭션 내부에서 쿼리 결과를 읽고 애플리케이션 로직으로 판단한 다음 다음 쿼리를 실행할 수 있다.

const result = await prisma.$transaction(async (tx) => {
  const sender = await tx.account.update({
    where: { email: 'alice@prisma.io' },
    data: { balance: { decrement: 100 } },
  })

  if (sender.balance < 0) {
    throw new Error('Insufficient funds')
  }

  return tx.account.update({
    where: { email: 'bob@prisma.io' },
    data: { balance: { increment: 100 } },
  })
})

이 예제는 전형적인 read-modify-write 흐름이다. 첫 번째 쓰기 결과를 보고 잔액이 음수인지 검사한 뒤, 조건을 만족할 때만 두 번째 쓰기를 수행한다. 중간에 예외가 발생하면 트랜잭션은 롤백된다.

Interactive transactions는 강력하지만 비용이 있다. 트랜잭션이 열린 동안 데이터베이스 커넥션을 붙잡고 있으므로, 오래 실행되는 로직을 넣으면 성능 저하나 deadlock 위험이 커진다. Prisma 문서도 트랜잭션을 짧게 유지하라고 권한다. 따라서 트랜잭션 내부에는 꼭 필요한 DB 읽기/쓰기와 짧은 판단 로직만 두는 편이 좋다.

await prisma.$transaction(
  async (tx) => {
    // read -> decide -> write
  },
  {
    maxWait: 5000,
    timeout: 10000,
  },
)

언제 Batch, Nested, Interactive를 써야 할까?

1. 먼저 Batch operations를 의심한다

같은 모델의 여러 레코드를 같은 방식으로 바꾸는가? 그렇다면 createMany, updateMany, deleteMany를 먼저 본다.

• 여러 이메일을 읽음 처리한다.
• 여러 주문의 상태를 DISPATCHED로 바꾼다.
• 조건에 맞는 로그 레코드를 삭제한다.

이 경우에는 개별 레코드가 서로 독립적이다. 애그리거트 관점에서도 "각 레코드별 도메인 규칙"이 아니라 "집합에 대한 동일한 상태 전이"라면 batch operation이 가장 단순하다.

2. 생성된 ID나 관계 그래프에 의존하면 Nested writes를 쓴다

부모를 만들고, 그 부모의 ID로 자식을 만들어야 하는가? 하나의 애그리거트 생성 과정에서 관계된 레코드들이 함께 생겨야 하는가? 그렇다면 Nested writes가 맞다.

• 팀을 만들면서 팀 멤버를 함께 만든다.
• 주문을 만들면서 주문 라인을 함께 만든다.
• 게시글을 만들면서 초기 메타데이터를 함께 만든다.

Nested writes는 "관계된 쓰기"를 Prisma 스키마의 관계 모델 그대로 표현한다. 특히 DB-generated ID를 사용한다면 배열형 $transaction([])보다 Nested writes가 더 적합하다.

3. 독립 쿼리 여러 개를 원자적으로 묶으면 $transaction([])를 쓴다

여러 모델을 건드리지만 각 쿼리가 서로의 실행 결과에 의존하지 않는가? 각 Prisma 쿼리를 트랜잭션 시작 전에 미리 만들 수 있는가? 그렇다면 $transaction([])가 맞다.

• 사용자 탈퇴 시 post.deleteMany, privateMessage.deleteMany, user.delete를 함께 실행한다.
• 사전에 계산한 ID로 여러 레코드를 생성한다.
• Prisma Client가 아직 충분히 표현하지 못하는 작업을 $executeRaw와 함께 묶는다.

배열형 $transaction([])는 순서대로 실행되지만, 배열 안의 쿼리 사이에 애플리케이션 로직을 끼워 넣지는 못한다. 앞 쿼리 결과를 보고 다음 쿼리를 구성해야 한다면 Interactive transactions로 넘어가야 한다.

4. 읽고 판단한 뒤 써야 하면 Interactive transactions를 쓴다

트랜잭션 내부에서 다음과 같은 흐름이 필요하면 Interactive transactions가 필요하다.

1. 현재 상태를 읽는다.
2. 애플리케이션 코드로 도메인 조건을 검사한다.
3. 조건에 따라 다음 쓰기를 실행하거나 예외를 던진다.
4. 전체 작업을 하나의 원자적 경계로 성공/실패시킨다.

예시는 계좌 이체, 재고 차감, 선착순 참여, 낙관적 동시성 제어가 필요한 상태 전이 등이다. 다만 트랜잭션 내부에 네트워크 호출, 사용자 입력 대기, 긴 계산을 넣으면 트랜잭션 시간이 길어진다. Interactive transactions는 "복잡한 로직을 넣어도 되는 곳"이 아니라 "DB 상태를 기준으로 짧게 판단해야 하는 곳"으로 보는 편이 안전하다.

판단 규칙 요약

flowchart TD
  A["여러 DB 작업이 필요한가?"] -->|아니오| B["일반 Prisma query"]
  A -->|예| C["같은 모델의 여러 레코드에 같은 변경인가?"]
  C -->|예| D["Batch operations"]
  C -->|아니오| E["관계된 쓰기이며 생성 ID에 의존하는가?"]
  E -->|예| F["Nested writes"]
  E -->|아니오| G["각 쿼리를 미리 만들 수 있는가?"]
  G -->|예| H["$transaction([])"]
  G -->|아니오| I["Interactive transactions"]

결론적으로 Prisma에서 트랜잭션을 고르는 기준은 "얼마나 복잡한가"가 아니라 쿼리 사이의 의존성이다. 독립적이면 Batch 또는 $transaction([]), 관계 생성에 의존하면 Nested writes, 중간 판단이 필요하면 Interactive transactions를 선택한다.