Prisma + PgBouncer 고부하 환경에서 데드락과 커넥션 고갈 해결하기

Node.js와 Fastify 환경에서 Prisma는 우수한 개발 생산성을 제공하지만, 트래픽이 몰리는 고부하 환경에서는 데이터베이스 커넥션이 폭증하는 고질적인 병목에 직면합니다. 이를 해결하기 위해 PgBouncer의 트랜잭션 풀링 모드를 도입하지만, 정교한 설정 없이 결합하면 마이그레이션 실패나 인터랙티브 트랜잭션 데드락 같은 치명적인 장애를 마주하게 됩니다. 대규모 동시 요청에서도 무중단으로 스케일아웃할 수 있는 고성능 데이터 레이어를 구축하기 위해, 두 도구를 결합할 때 반드시 확보해야 하는 아키텍처 핵심 최적화 요소를 살펴봅니다.

트랜잭션 풀링과 마이그레이션 분리: 두 개의 URL을 쓰는 이유

PgBouncer의 트랜잭션 풀링 모드는 고성능 애플리케이션에서 데이터베이스 커넥션을 효율적으로 제어하기 위한 필수 선택입니다. 하지만 이 모드에서는 트랜잭션이 커밋되거나 롤백되는 즉시 물리 커넥션이 회수되기 때문에, 단일 세션 연결 유지가 필수적인 데이터베이스 마이그레이션 작업은 실행 도중 에러를 내며 실패하게 됩니다.

prisma migrate deploy나 prisma db push 같은 마이그레이션 도구는 스키마를 변경하고 잠금을 제어하는 과정에서 지속적인 물리 커넥션을 점유해야 합니다. 따라서 실서비스 쿼리를 처리하는 PgBouncer의 트랜잭션 풀로 마이그레이션을 실행하는 것은 불가능합니다.

이 문제를 해결하려면 Prisma 스키마 설정에서 서비스 쿼리용 커넥션과 마이그레이션 직접 연결용 커넥션을 이원화해야 합니다. Prisma는 이를 위해 url과 directUrl이라는 두 가지 설정을 함께 지원합니다.

// schema.prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")       // PgBouncer 트랜잭션 풀 경로 (예: 포트 6543)
  directUrl = env("DIRECT_DATABASE_URL") // PostgreSQL 직접 연결 경로 (예: 포트 5432)
}

이렇게 이원화하면 서비스 애플리케이션은 PgBouncer를 거쳐 커넥션을 유연하게 공유하고, CI/CD 배포 단계나 관리자 작업 시에는 데이터베이스에 직접 안전하게 붙어 마이그레이션을 정상적으로 마칠 수 있습니다.

PgBouncer 1.21.0+ 업데이트와 prepared statements 실전 가이드

PgBouncer를 도입할 때 가장 골칫거리였던 준비된 구문 오류는 이제 과거의 유물이 되었습니다. 이전에는 트랜잭션 풀링 모드에서 여러 세션이 동일한 물리 커넥션을 공유하면서, Prisma가 생성한 명명된 준비된 구문의 이름이 충돌해 에러를 일으키는 문제가 고질적이었습니다.

이를 피하기 위해 커넥션 URL 끝에 ?pgbouncer=true 파라미터를 붙여 준비된 구문 대신 성능이 떨어지는 무명 매개변수화 쿼리를 강제하는 임시방편을 오랫동안 사용해 왔습니다. 하지만 PgBouncer 1.21.0 버전부터 트랜잭션 모드에서도 준비된 구문을 완벽하게 지원하기 시작했습니다.

이 혜택을 누리려면 PgBouncer 설정 파일(pgbouncer.ini)에서 max_prepared_statements 값을 0보다 크게 지정하기만 하면 됩니다. 이 설정을 적용하면 PgBouncer가 개별 클라이언트 세션의 준비된 구문을 백엔드 데이터베이스 연결에 안전하게 매핑하므로 성능 이점을 그대로 챙길 수 있습니다.

Prisma 공식 가이드에서도 최신 PgBouncer 버전을 사용한다면 ?pgbouncer=true 옵션을 더 이상 설정하지 않을 것을 강력히 권장합니다. 특히 최신 Prisma ORM v7 환경에서는 @prisma/adapter-pg 같은 드라이버 어댑터를 기본적으로 활용하며, 이 새로운 구조는 커넥션 제어와 쿼리 전송을 하위 드라이버 레이어로 완전히 위임하므로 예전 방식의 수동 파라미터 제어가 필요하지 않습니다. 성능 저하를 감수하는 편법 대신 인프라 설정을 현대화하여 쿼리 최적화의 이점을 온전히 얻어야 합니다.

인터랙티브 트랜잭션과 커넥션 starvation 데드락

인터랙티브 트랜잭션을 잘못 사용하면 고부하 환경에서 서비스가 완전히 먹통이 되는 로컬 데드락이 발생할 수 있습니다. 이 현상은 데이터베이스 서버 수준에서 락이 걸리는 것이 아니라, 애플리케이션 서버 내부에서 스스로 커넥션 자원을 묶어버리며 발생합니다.

Prisma의 인터랙티브 트랜잭션은 콜백 함수가 실행되는 전체 시간 동안 물리 데이터베이스 커넥션을 독점적으로 점유합니다. 이때 흔히 저지르는 치명적인 실수는 트랜잭션 콜백 안에서 전용 클라이언트가 아닌 전역 Prisma 인스턴스를 호출해 비트랜잭션 쿼리를 섞어 쓰는 안티패턴입니다.

다음 예시를 통해 잘못된 코드와 올바른 해결법을 직관적으로 비교할 수 있습니다.

// ❌ 안티패턴: 트랜잭션 내에서 전역 인스턴스로 비트랜잭션 쿼리 호출
await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUnique({ where: { id: 1 } });
  
  // 오류 지점: tx가 아닌 전역 prisma를 호출해 풀에서 추가 커넥션을 요구함
  const profile = await prisma.profile.findUnique({ where: { userId: user.id } });
  
  await tx.user.update({
    where: { id: 1 },
    data: { status: 'ACTIVE' },
  });
});

//  올바른 패턴: 트랜잭션 스코프 내의 전용 클라이언트인 tx만 사용
await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUnique({ where: { id: 1 } });
  
  // 개선: 모든 쿼리를 트랜잭션 전용 클라이언트로 단일화함
  const profile = await tx.profile.findUnique({ where: { userId: user.id } });
  
  await tx.user.update({
    where: { id: 1 },
    data: { status: 'ACTIVE' },
  });
});

만약 고부하 서버에서 풀 리소스를 아끼려고 커넥션 한도를 지나치게 낮게 설정해 두었다면 심각한 문제가 발생합니다. 콜백 내부에서 전역 클라이언트로 실행한 비트랜잭션 쿼리는 사용 가능한 커넥션을 확보하기 위해 무한대기에 들어갑니다. 하지만 트랜잭션이 이미 선점한 물리 커넥션은 이 콜백이 정상 종료되기 전까지 결코 풀에 반환되지 않습니다. 결국 서로가 완료되기를 영구히 기다리는 커넥션 고갈 데드락에 빠지게 됩니다.

이를 근본적으로 방지하려면 트랜잭션 내부의 모든 쿼리가 반드시 트랜잭션 전용 클라이언트를 통하도록 강제해야 합니다. 또한 동시 요청이 몰리는 컨테이너 기반 환경에서는 트랜잭션 볼륨을 면밀히 예측하여 커넥션 한도를 너무 낮지 않게 조율해야 예기치 못한 교착 상태를 피할 수 있습니다.

성공적인 Prisma 데이터 아키텍처를 위한 요약

고부하 환경에서 Prisma와 PostgreSQL의 성능을 극대화하려면 데이터베이스 연결 관리와 쿼리 실행 방식을 정교하게 제어해야 합니다. 대규모 동시 요청에서도 무중단으로 스케일아웃할 수 있는 데이터 레이어를 위해 다음 세 가지 원칙을 기억하세요.

이 세 가지만 올바르게 설계에 반영해도 고부하 서비스에서 마주하는 데이터베이스 병목과 장애의 대부분을 안정적으로 예방할 수 있습니다.

참고 링크